Merge pull request #4302 from ntrel/delegates2

[spec] Improve delegate docs

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

Author: dlang-bot

spec/function.dd

@@ -3278,7 +3278,8 @@ uint function(uint) fp2 = &def;
 
 $(H3 $(LNAME2 closures, Delegates & Closures))
 
-        $(P A delegate can be set to a non-static nested function:)
+        $(P A $(DDSUBLINK spec/type, delegates, delegate) can be set to a
+        non-static $(RELATIVE_LINK2 nested, nested function):)
 
 $(SPEC_RUNNABLE_EXAMPLE_RUN
 ------
@@ -3312,8 +3313,9 @@ void main()
         $(P Those referenced stack variables that make up the closure
         are allocated on the GC heap, unless:)
 
-        * The closure is passed to a `scope` parameter.
-        * The closure is an initializer for a `scope` variable.
+        * The closure is passed to a $(RELATIVE_LINK2 scope-parameters, `scope` parameter).
+        * The closure is an initializer for a
+          $(DDSUBLINK spec/attribute, scope, `scope` variable).
         * The closure is assigned to a `scope` variable.
 
 $(SPEC_RUNNABLE_EXAMPLE_COMPILE
@@ -3347,7 +3349,7 @@ void main()
         a closure and is an error.
         )
 
-$(H4 $(LNAME2 method-delegates, Method Delegates))
+$(H3 $(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
@@ -3377,9 +3379,6 @@ void main()
 {
     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);
 
@@ -3392,14 +3391,6 @@ void main()
 ------
 )
 
-        $(P The $(D .ptr) property of a delegate will return the
-        $(I context pointer) value as a $(D void*).
-        )
-
-        $(P The $(D .funcptr) property of a delegate will return the
-        $(I function pointer) value as a function type.
-        )
-
 $(H3 $(LNAME2 function-delegate-init, Initialization))
 
         $(P Function pointers are zero-initialized by default.

spec/type.dd

@@ -221,7 +221,7 @@ assert(i == 4);
 
         $(BEST_PRACTICE Use a $(DDSUBLINK spec/function, ref-params,
         `ref` function parameter) or a $(DDSUBLINK spec/declaration, ref-variables,
-        `ref` local variable) when the address doesn't escape.
+        `ref` local variable) when the address doesn't escape.)
 
 
 $(H2 $(LEGACY_LNAME2 User Defined Types, user-defined-types, User-Defined Types))
@@ -698,27 +698,47 @@ $(P See $(DDSUBLINK spec/function, function-pointers, Function Pointers).)
 
 $(H3 $(LNAME2 delegates, Delegates))
 
-$(P Delegates are an aggregate of two pieces of data, either:)
+$(P Delegates are an aggregate of two pieces of data, a *context pointer* and
+a *function pointer*. A valid delegate holds either:)
+
 * An object reference and a pointer to a non-static
   $(DDSUBLINK spec/class, member-functions, member function).
-* A pointer to a closure and a pointer to a
-  $(DDSUBLINK spec/function, nested, nested function).
-  The object reference forms the `this` pointer when the function is called.)
+  The object reference forms the `this` pointer when the function is called.
+* A pointer to a $(DDSUBLINK spec/function, closures, closure)
+  and a pointer to a $(DDSUBLINK spec/function, nested, nested function).
+
+$(P The $(D .ptr) property of a delegate will return the
+$(I context pointer) value as a $(D void*).
+)
+
+$(P The $(D .funcptr) property of a delegate will return the
+$(I function pointer) value as a function type.
+)
 
 $(P Delegates are declared and initialized similarly to function pointers:)
 
-$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 -------------------
-int delegate(int) dg; // dg is a delegate to a function
+void func(int) {}
+void function(int) fp; // fp is a function pointer
+void delegate(int) dg; // dg is a delegate to a function
 
 class OB
 {
-    int member(int);
+    void member(int) {}
 }
 
-void f(OB o)
+void main()
 {
-    dg = &o.member; // dg is a delegate to object o and member function member
+    OB o = new OB;
+
+    fp = &func; // fp points to function `func`
+
+    dg = &o.member; // dg is a delegate to object `o` and member function `member`
+    assert(dg.ptr == cast(void*) o);
+    assert(dg.funcptr == &OB.member);
+
+    dg = (int i) { o.member(i); }; // dg holds a delegate literal with main's execution context
 }
 -------------------
 )
@@ -735,6 +755,11 @@ fp(3);   // call func(3)
 dg(3);   // call o.member(3)
 -------------------
 
+    $(P See:)
+
+    * $(DDSUBLINK spec/function, closures, Delegates and Closures)
+    * $(DDSUBLINK spec/function, method-delegates, Method Delegates)
+
     $(P The equivalent of member function pointers can be constructed
     using $(DDSUBLINK spec/expression, function_literals, anonymous lambda functions):)