Merge pull request #2813 from ntrel/nested-class

Improve Nested Classes section
merged-on-behalf-of: Nicholas Wilson <thewilsonator@users.noreply.github.com>

Author: dlang-bot

spec/class.dd

@@ -1358,9 +1358,11 @@ void func()
 }
 ------
 
+$(H3 $(LNAME2 static-nested, Static Nested Classes))
+
 $(P If a nested class has the $(D static) attribute, then it can not access
 variables of the enclosing scope that are local to the stack or need a
-`this`:)
+`this` reference:)
 
 ------
 class Outer
@@ -1394,9 +1396,11 @@ void func()
 }
 ------
 
+$(H3 $(LNAME2 nested-context, Context Pointer))
+
 $(P Non-static nested classes work by containing an extra hidden member (called
 the context pointer) that is the frame pointer of the enclosing function if it
-is nested inside a function, or the $(D this) of the enclosing class's instance
+is nested inside a function, or the $(D this) reference of the enclosing class's instance
 if it is nested inside a class.)
 
         $(P When a non-static nested class is instantiated, the context pointer
@@ -1425,9 +1429,9 @@ void func()
 }
 ------
 
+$(H3 $(LNAME2 nested-explicit, Explicit Instantiation))
 
-
-        $(P A $(I this) can be supplied to the creation of an
+        $(P A `this` reference can be supplied to the creation of an
         inner class instance by prefixing it to the $(I NewExpression):
         )
 
@@ -1454,14 +1458,16 @@ int bar()
 }
 ---------
 
-        $(P Here $(D o) supplies the $(I this) to the outer class
+        $(P Here $(D o) supplies the `this` reference to the inner class
         instance of $(D Outer).
         )
 
-        $(P The property $(D .outer) used in a nested class gives the
-        $(D this) pointer to its enclosing class. If there is no enclosing
-        class context, $(D .outer) would return a pointer to enclosing
-        function frame with $(D void*).
+$(H3 $(LNAME2 outer-property, `outer` Property))
+
+        $(P For a nested class instance, the $(D .outer) property is the
+        $(D this) reference for the enclosing class's instance. If there
+        is no enclosing class context, $(D .outer) would be a $(D void*)
+        to the enclosing function frame.
         )
 
 ----
@@ -1484,16 +1490,16 @@ class Outer
     void bar()
     {
         // x is referenced from nested scope, so
-        // bar makes a closure envronment.
+        // bar makes a closure environment.
         int x = 1;
 
         class Inner2
         {
             Outer getOuter()
             {
                 x = 2;
-                // The Inner2 instance owns function frame of bar
-                // as static frame pointer, but .outer yet returns
+                // The Inner2 instance has access to the function frame
+                // of bar as a static frame pointer, but .outer returns
                 // the enclosing Outer class instance property.
                 return this.$(CODE_HIGHLIGHT outer);
             }
@@ -1503,18 +1509,19 @@ class Outer
         assert(i.getOuter() is this);
     }
 
+    // baz cannot access an instance of Outer
     static void baz()
     {
-        // make a closure envronment
+        // make a closure environment
         int x = 1;
 
         class Inner3
         {
             void* getOuter()
             {
                 x = 2;
-                // There's no accessible enclosing class instance, so
-                // .outer property returns the function frame of bar.
+                // There's no accessible enclosing class instance, so the
+                // .outer property returns the function frame of baz.
                 return this.$(CODE_HIGHLIGHT outer);
             }
         }
@@ -1525,29 +1532,48 @@ class Outer
 }
 ----
 
-$(H2 $(LNAME2 anonymous, Anonymous Nested Classes))
+$(H3 $(LNAME2 anonymous, Anonymous Nested Classes))
 
         $(P An anonymous nested class is both defined and instantiated with
         a $(I NewAnonClassExpression):
         )
 
 $(GRAMMAR
 $(GNAME NewAnonClassExpression):
-    $(D new) $(GLINK2 expression, AllocatorArguments)$(OPT) $(D class) $(I ClassArguments)$(OPT) $(GLINK SuperClass)$(OPT) $(GLINK Interfaces)$(OPT) $(GLINK2 struct, AggregateBody)
+    $(D new) $(GLINK2 expression, AllocatorArguments)$(OPT) $(D class) $(I ConstructorArgs)$(OPT) $(GLINK SuperClass)$(OPT) $(GLINK Interfaces)$(OPT) $(GLINK2 struct, AggregateBody)
 
-$(GNAME ClassArguments):
+$(GNAME ConstructorArgs):
     $(D $(LPAREN)) $(GLINK2 expression, ArgumentList)$(OPT) $(D $(RPAREN))
 )
 
 which is equivalent to:
 
 $(GRAMMAR
 $(D class) $(GLINK_LEX Identifier) $(D :) $(I SuperClass) $(I Interfaces) $(I AggregateBody)
-$(D new) $(D $(LPAREN))$(I ArgumentList)$(D $(RPAREN)) $(GLINK_LEX Identifier) $(D $(LPAREN))$(I ArgumentList)$(D $(RPAREN));
+// ...
+$(D new) $(I AllocatorArguments) $(I Identifier) $(I ConstructorArgs)
 )
 
 where $(I Identifier) is the name generated for the anonymous nested class.
 
+$(SPEC_RUNNABLE_EXAMPLE_RUN
+---
+interface I
+{
+    void foo();
+}
+
+auto obj = new class I
+{
+    void foo()
+    {
+        writeln("foo");
+    }
+};
+obj.foo();
+---
+)
+
 $(SECTION2 $(LEGACY_LNAME2 ConstClass, const-class, $(ARGS Const, Immutable and Shared Classes)),
 
     $(P If a $(I ClassDeclaration) has a $(D const), $(D immutable)

spec/template.dd

@@ -1388,6 +1388,8 @@ $(H3 $(LNAME2 implicit-nesting, Implicit Nesting))
         }
         ----
 
+    $(P See also: $(DDSUBLINK spec/class, nested-explicit, Nested Class Instantiation).)
+
         ----
         void main()
         {