Merge pull request #2810 from ntrel/struct-ctor

Improve struct constructor docs, add subsections
merged-on-behalf-of: Nicholas Wilson <thewilsonator@users.noreply.github.com>

Author: dlang-bot

spec/class.dd

@@ -342,7 +342,7 @@ $(GNAME Constructor):
         called.)
 
         $(P Constructors are defined with a function name of $(D this)
-        and having no return value:)
+        and have no return value:)
 
         ------
         class Foo

spec/struct.dd

@@ -379,6 +379,12 @@ $(H2 $(LEGACY_LNAME2 ConstStruct, const-struct, Const, Immutable and Shared Stru
         ----
         )
 
+
+$(H2 $(LNAME2 UnionConstructor, Union Constructors))
+
+        $(P Unions are constructed in the same way as structs.)
+
+
 $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors))
 
         $(P Struct constructors are used to initialize an instance of a struct when a more
@@ -387,15 +393,15 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
         $(LINK2 #struct-literal, struct literal).
         )
 
-        $(P Constructors are defined with a function name of `this` and having no return value.
+        $(P Constructors are defined with a function name of `this` and have no return value.
         The grammar is the same as for the class $(GLINK2 class, Constructor).
         )
 
         $(P A struct constructor is called by the name of the struct followed by
-        $(GLINK2 class, Parameters).
-        $(P If the $(GLINK2 class, ParameterList) is empty,
-        the struct instance is default initialized.)
+        $(GLINK2 function, Parameters).
         )
+        $(P If the $(GLINK2 function, ParameterList) is empty,
+        the struct instance is default initialized.)
 
         $(SPEC_RUNNABLE_EXAMPLE_FAIL
         ---
@@ -412,7 +418,7 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
         void main()
         {
             S a = S(4, 5); // calls S.this(4, 5):  a.x = 4, a.y = 5, a.z = 6
-            S b = S();  // default initialized:    a.x = 0, b.y = 4, b.y = 6
+            S b = S();  // default initialized:    b.x = 0, b.y = 4, b.z = 6
             S c = S(1); // error, matching this(int) not found
         }
         ---
@@ -431,9 +437,11 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
         ---
         )
 
-        $(P Constructors can call other constructors for the same struct
-        in order to share common initializations
-        (this is called a $(DDSUBLINK spec/class, delegating-constructors, delegating constructor)):
+$(H3 $(LNAME2 delegating-constructor, Delegating Constructors))
+
+        $(P A constructor can call another constructor for the same struct
+        in order to share common initializations. This is called a
+        $(I delegating constructor):
         )
 
         $(SPEC_RUNNABLE_EXAMPLE_FAIL
@@ -458,12 +466,12 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
         ---
         )
 
-        $(P The following restrictions apply to struct construction:)
+        $(P The following restrictions apply:)
 
         $(OL
-        $(LI If a constructor's code contains a delegate constructor call, all
+        $(LI If a constructor's code contains a delegating constructor call, all
         possible execution paths through the constructor must make exactly one
-        delegate constructor call:
+        delegating constructor call:
 
         $(SPEC_RUNNABLE_EXAMPLE_FAIL
         ---
@@ -494,14 +502,18 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
         )
 
         $(LI It is illegal to refer to $(D this) implicitly or explicitly
-        prior to making a delegate constructor call.)
+        prior to making a delegating constructor call.)
 
-        $(LI Once the delegate constructor returns, all fields are considered
+        $(LI Once the delegating constructor returns, all fields are considered
         constructed.)
 
-        $(LI Delegate constructor calls cannot appear after labels.)
+        $(LI Delegating constructor calls cannot appear after labels.)
         )
 
+        $(P See also: $(DDSUBLINK spec/class, delegating-constructors, delegating class constructors).)
+
+
+$(H3 $(LNAME2 struct-instantiation, Struct Instantiation))
 
         $(P When an instance of a struct is created, the following steps happen:)
 
@@ -522,6 +534,8 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
         )
 
 
+$(H3 $(LNAME2 constructor-attributes, Constructor Attributes))
+
         $(P A constructor qualifier (`const`, `immutable` or `shared`) constructs the object instance
         with that specific qualifier.
         )
@@ -583,6 +597,8 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
         ---
         )
 
+$(H4 $(LNAME2 pure-constructors, Pure Constructors))
+
         $(P If the constructor can create a unique object (i.e. if it is `pure`),
         the object is implicitly convertible to any qualifiers.
         )
@@ -611,9 +627,9 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
 
 
 
-$(H2 $(LNAME2 disable_default_construction, Disabling Default Struct Construction))
+$(H3 $(LNAME2 disable_default_construction, Disabling Default Struct Construction))
 
-        $(P If struct constructor is annotated with $(D @disable) and has
+        $(P If a struct constructor is annotated with $(D @disable) and has
         an empty $(GLINK2 function, ParameterList), the struct has disabled default construction.
         The only way it can be constructed is via a call to another constructor with a non-empty
         $(I ParameterList).
@@ -624,7 +640,7 @@ $(H2 $(LNAME2 disable_default_construction, Disabling Default Struct Constructio
 
         $(P A disabled default constructor may not have a $(GLINK2 function, FunctionBody).)
 
-        $(P If any fields have disabled default construction, the struct default construction is
+        $(P If any fields have disabled default construction, struct default construction is
         also disabled.)
 
         $(SPEC_RUNNABLE_EXAMPLE_FAIL
@@ -661,20 +677,15 @@ $(H2 $(LNAME2 disable_default_construction, Disabling Default Struct Constructio
         such as `null`, is not acceptable.)
 
 
-$(H2 $(LNAME2 UnionConstructor, Union Constructors))
-
-        $(P Unions are constructed in the same way as structs.)
+$(H3 $(LNAME2 field-init, Field initialization inside a constructor))
 
-
-$(H2 $(LNAME2 field-init, Field initialization inside constructor))
-
-        $(P In a constructor body, if a delegate constructor is called,
+        $(P In a constructor body, if a delegating constructor is called,
         all field assignments are considered assignments.
         Otherwise, the first instance of field assignment is
         its initialization, and assignments of the form `field = expression`
         are treated as equivalent to `typeof(field)(expression)`.
         The values of fields may be read before initialization or construction
-        with a delegate constructor.
+        with a delegating constructor.
         )
 
         $(SPEC_RUNNABLE_EXAMPLE_COMPILE
@@ -810,7 +821,7 @@ $(H2 $(LNAME2 field-init, Field initialization inside constructor))
         ---
         )
 
-$(H2 $(LEGACY_LNAME2 StructCopyConstructor, struct-copy-constructor, Struct Copy Constructors))
+$(H3 $(LEGACY_LNAME2 StructCopyConstructor, struct-copy-constructor, Struct Copy Constructors))
 
     $(P Copy constructors are used to initialize a `struct` instance from
     another `struct` of the same type.)
@@ -910,6 +921,14 @@ $(H2 $(LEGACY_LNAME2 StructCopyConstructor, struct-copy-constructor, Struct Copy
     }
     ---
 
+    $(P If a `union S` has fields that define a copy constructor, whenever an object of type `S`
+    is initialized by copy, an error will be issued. The same rule applies to overlapped fields
+    (anonymous unions).)
+
+    $(P A `struct` that defines a copy constructor is not a POD.)
+
+$(H4 $(LNAME2 copy-constructor-attributes, Copy Constructor Attributes))
+
     $(P The copy constructor can be overloaded with different qualifiers applied
     to the parameter (copying from a qualified source) or to the copy constructor
     itself (copying to a qualified destination):
@@ -957,6 +976,8 @@ $(H2 $(LEGACY_LNAME2 StructCopyConstructor, struct-copy-constructor, Struct Copy
     }
     ---
 
+$(H4 $(LNAME2 implicit-copy-constructors, Implicit Copy Constructors))
+
     $(P A copy constructor is generated implicitly by the compiler for a `struct S`
     if all of the following conditions are met:)
 
@@ -977,11 +998,6 @@ $(H2 $(LEGACY_LNAME2 StructCopyConstructor, struct-copy-constructor, Struct Copy
 
     $(P If the generated copy constructor fails to type check, it will receive the `@disable` attribute.)
 
-    $(P If a `union S` has fields that define a copy constructor, whenever an object of type `S`
-    is initialized by copy, an error will be issued. The same rule applies to overlapped fields
-    (anonymous unions).)
-
-    $(P A `struct` that defines a copy constructor is not a POD.)
 
 $(H2 $(LEGACY_LNAME2 StructPostblit, struct-postblit, Struct Postblits))
 
@@ -991,8 +1007,9 @@ $(GNAME Postblit):
     $(D this $(LPAREN) this $(RPAREN)) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK2 function, FunctionBody)
 )
 
-    $(P WARNING: The postblit is considered legacy and is not recommended for new code. Code should use copy
-    constructors defined in the previous section. For backward compatibility reasons, a `struct` that defines
+    $(P WARNING: The postblit is considered legacy and is not recommended for new code.
+    Code should use $(RELATIVE_LINK2 struct-copy-constructor, copy constructors)
+    defined in the previous section. For backward compatibility reasons, a `struct` that defines
     both a copy constructor and a postblit will only use the postblit for implicit copying.)
 
         $(P $(I Copy construction) is defined as initializing