Merge pull request dlang#3599 from ntrel/method-delegates

[spec/function] Tweak delegate docs

Signed-off-by: Dennis <dkorpel@users.noreply.github.com>
Signed-off-by: Nicholas Wilson <thewilsonator@users.noreply.github.com>
Merged-on-behalf-of: Nicholas Wilson <thewilsonator@users.noreply.github.com>

Author: dlang-bot

spec/function.dd

@@ -3143,7 +3143,9 @@ void main()
 
         $(P The stack variables referenced by a nested function are
         still valid even after the function exits (NOTE this is different
-        from D 1.0.) This is called a $(I closure).
+        from D 1.0).
+        This combining of the environment and the function is called
+        a $(I dynamic closure).
         )
 
         $(P Those referenced stack variables that make up the closure
@@ -3184,6 +3186,8 @@ void main()
         a closure and is an error.
         )
 
+$(H4 $(LNAME2 method-delegates, Method Delegates))
+
         $(P Delegates to non-static nested functions contain two pieces of
         data: the pointer to the stack frame of the lexically enclosing
         function (called the $(I context pointer)) and the address of the
@@ -3193,39 +3197,40 @@ void main()
         Both forms of delegates are indistinguishable, and are
         the same type.
         )
+        $(P A delegate can be set to a particular object and method using `&obj.method`:)
 
 $(SPEC_RUNNABLE_EXAMPLE_RUN
 ------
 struct Foo
 {
-    int a = 7;
-    int bar() { return a; }
+    int a;
+    int get() { return a; }
 }
 
-int foo(int delegate() dg)
+int add1(int delegate() dg)
 {
     return dg() + 1;
 }
 
 void main()
 {
-    Foo f;
-    int i = foo(&f.bar);
+    Foo f = {7};
+    int delegate() dg = &f.get; // bind to an instance of Foo and a method
+    assert(dg.ptr == &f);
+    assert(dg.funcptr == &Foo.get);
+
+    int i = add1(dg);
     assert(i == 8);
 
     int x = 27;
     int abc() { return x; }
 
-    i = foo(&abc);
+    i = add1(&abc);
     assert(i == 28);
 }
 ------
 )
 
-        $(P This combining of the environment and the function is called
-        a $(I dynamic closure).
-        )
-
         $(P The $(D .ptr) property of a delegate will return the
         $(I context pointer) value as a $(D void*).
         )