[spec/class] Improve construction docs

Make Constructors a subheading of Class Instantiation, because:
* `new Object` is valid and it has no constructor
* Explaining how to create a class instance should be done before the
  details of delegating constructors etc.
* Field initialization was listed under Constructors, but applies for
  `new C` when there isn't a constructor.

Make examples runnable.
Explain when arguments to `new` are required, and how constructors are
matched.
Add relative link to class invariants.

Author: ntrel

spec/class.dd

@@ -382,14 +382,7 @@ $(H3 $(LNAME2 synchronized-classes, Synchronized Classes))
         $(NOTE struct types cannot be marked `synchronized`.)
 
 
-$(H2 $(LNAME2 constructors, Constructors))
-
-$(GRAMMAR
-$(GNAME Constructor):
-    $(D this) $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK2 function, FunctionBody)
-    $(D this) $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK2 function, MissingFunctionBody)
-    $(GLINK2 template, ConstructorTemplate)
-)
+$(H2 $(LNAME2 class-instantiation, Class Instantiation))
 
         $(P Fields are by default initialized to the
         $(DDSUBLINK spec/property, init, default initializer)
@@ -398,34 +391,74 @@ $(GNAME Constructor):
         If the field declaration has an optional $(GLINK2 declaration, Initializer)
         that will be used instead of the default.
         )
+
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
         ------
         class Abc
         {
             int a;      // default initializer for a is 0
             long b = 7; // default initializer for b is 7
             float f;    // default initializer for f is NAN
         }
+
+        void main()
+        {
+            Abc obj = new Abc;
+            assert(obj.b == 7);
+        }
         ------
+        )
 
         $(P The $(I Initializer) is evaluated at compile time.)
 
-        $(P This initialization is done before any constructors are
-        called.)
+        $(P This initialization is done before any
+        $(RELATIVE_LINK2 constructors, constructors) are called.)
+
+        $(P Instances of class objects are created with a $(GLINK2 expression, NewExpression).)
+
+        * A class `C` without a constructor (or with a nullary constructor) is instantiated
+          using `new C`, without passing any arguments.
+        * Otherwise, a class can be instantiated with an argument list, e.g.
+          `new C(arguments)`. The arguments are passed to a constructor with a matching
+          parameter list (and resolved like $(DDSUBLINK spec/function, function-overloading,
+          overloaded methods)).
+
+        $(P By default, a class instance is allocated on the garbage-collected heap.
+        A $(DDSUBLINK spec/attribute, scope-class-var, `scope` class instance)
+        is allocated on the stack.)
+
+
+$(H3 $(LNAME2 constructors, Constructors))
+
+$(GRAMMAR
+$(GNAME Constructor):
+    $(D this) $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK2 function, FunctionBody)
+    $(D this) $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK2 function, MissingFunctionBody)
+    $(GLINK2 template, ConstructorTemplate)
+)
 
         $(P Constructors are defined with a function name of $(D this)
         and have no return value:)
 
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
         ------
-        class Foo
+        class A
         {
-            $(CODE_HIGHLIGHT this)(int x)  // declare constructor for Foo
-            {   ...
-            }
-            $(CODE_HIGHLIGHT this)()
-            {   ...
+            int i;
+
+            this(int i) // constructor taking an int argument
+            {
+                this.i = i; // initialize field `i` from parameter `i`
             }
         }
+
+        void main()
+        {
+            A a = new A(3);
+            assert(a.i == 3);
+        }
         ------
+        )
 
 $(H3 $(LNAME2 base-construction, Base Class Construction))
 
@@ -528,16 +561,7 @@ $(H3 $(LNAME2 implicit-base-construction, Implicit Base Class Construction))
         base class has a constructor that requires arguments and no
         nullary constructor, a matching call to `super` is required.)
 
-$(H3 $(LNAME2 class-instantiation, Class Instantiation))
-
-        $(P Instances of class objects are created with a $(GLINK2 expression, NewExpression):)
-
-        ------
-        A a = new A(3);
-        ------
-
-        $(P A $(DDSUBLINK spec/attribute, scope-class-var, `scope` class instance)
-        is allocated on the stack.)
+$(H3 $(LNAME2 instantiation-process, Instantiation Process))
 
         $(P The following steps happen:)
 
@@ -568,8 +592,8 @@ $(H3 $(LNAME2 class-instantiation, Class Instantiation))
 
         $(LI The body of the constructor is executed.)
 
-        $(LI If class invariant checking is turned on, the class invariant
-        is called at the end of the constructor.
+        $(LI If class invariant checking is turned on, the
+        $(RELATIVE_LINK2 invariants, class invariant) is called at the end of the constructor.
         )
     )