[spec/struct.dd] Improve struct initialization docs (#3217)

[spec/struct.dd] Improve struct initialization docs

Signed-off-by: Dennis <[email protected]>
Merged-on-behalf-of: Dennis <[email protected]>

Author: ntrel

spec/declaration.dd

@@ -105,7 +105,7 @@ $(GNAME Initializer):
 $(GNAME NonVoidInitializer):
     $(GLINK2 expression, AssignExpression)$(LEGACY_LNAME2 ExpInitializer)
     $(GLINK ArrayInitializer)
-    $(GLINK StructInitializer)
+    $(GLINK2 struct, StructInitializer)$(LEGACY_LNAME2 StructInitializer)
 
 $(GNAME ArrayInitializer):
     $(D [) $(GLINK ArrayMemberInitializations)$(OPT) $(D ])
@@ -118,18 +118,6 @@ $(GNAME ArrayMemberInitializations):
 $(GNAME ArrayMemberInitialization):
     $(GLINK NonVoidInitializer)
     $(GLINK2 expression, AssignExpression) $(D :) $(GLINK NonVoidInitializer)
-
-$(GNAME StructInitializer):
-    $(D {) $(GLINK StructMemberInitializers)$(OPT) $(D })
-
-$(GNAME StructMemberInitializers):
-    $(GLINK StructMemberInitializer)
-    $(GLINK StructMemberInitializer) $(D ,)
-    $(GLINK StructMemberInitializer) $(D ,) $(GSELF StructMemberInitializers)
-
-$(GNAME StructMemberInitializer):
-    $(GLINK NonVoidInitializer)
-    $(GLINK_LEX Identifier) $(D :) $(GLINK NonVoidInitializer)
 )
 
 $(H2 $(LNAME2 declaration_syntax, Declaration Syntax))

spec/struct.dd

@@ -136,7 +136,9 @@ S* p;     // ok, knowledge of members is not necessary
         $(LINK2 https://en.wikipedia.org/wiki/Opaque_pointer, PIMPL idiom).)
 
 
-$(H2 $(LNAME2 default_struct_init, Default Initialization of Structs))
+$(H2 $(LNAME2 initialization, Initialization))
+
+$(H3 $(LNAME2 default_struct_init, Default Initialization of Structs))
 
         $(P Struct fields are by default initialized to whatever the
         $(GLINK2 declaration, Initializer) for the field is, and if none is supplied, to
@@ -154,10 +156,24 @@ $(H2 $(LNAME2 default_struct_init, Default Initialization of Structs))
 
         $(P The default initializers may not contain references to mutable data.)
 
-$(H2 $(LNAME2 static_struct_init, Static Initialization of Structs))
+$(H3 $(LNAME2 static_struct_init, Static Initialization of Structs))
+
+$(GRAMMAR
+$(GNAME StructInitializer):
+    $(D {) $(I StructMemberInitializers)$(OPT) $(D })
 
-        $(P If a $(GLINK2 declaration, StructInitializer) is supplied, the
-        fields are initialized by the $(GLINK2 declaration, StructMemberInitializer) syntax.
+$(GNAME StructMemberInitializers):
+    $(I StructMemberInitializer)
+    $(I StructMemberInitializer) $(D ,)
+    $(I StructMemberInitializer) $(D ,) $(GSELF StructMemberInitializers)
+
+$(GNAME StructMemberInitializer):
+    $(GLINK2 declaration, NonVoidInitializer)
+    $(GLINK_LEX Identifier) $(D :) $(GLINK2 declaration, NonVoidInitializer)
+)
+
+        $(P If a $(I StructInitializer) is supplied, the
+        fields are initialized by the $(I StructMemberInitializer) syntax.
         $(I StructMemberInitializers) with the $(I Identifier : NonVoidInitializer) syntax
         may be appear in any order, where $(I Identifier) is the field identifier.
         $(I StructMemberInitializer)s with the $(GLINK2 declaration, NonVoidInitializer) syntax
@@ -186,14 +202,12 @@ $(H2 $(LNAME2 static_struct_init, Static Initialization of Structs))
         ---
         )
 
-$(H2 $(LNAME2 default_union_init, Default Initialization of Unions))
+$(H3 $(LNAME2 default_union_init, Default Initialization of Unions))
 
         $(P Unions are by default initialized to whatever the
         $(GLINK2 declaration, Initializer) for the first field is, and if none is supplied, to
         the default initializer for the first field's type.
-        )
-
-        $(P If the union is larger than the first field, the remaining bits
+        If the union is larger than the first field, the remaining bits
         are set to 0.)
 
         $(SPEC_RUNNABLE_EXAMPLE_COMPILE
@@ -203,6 +217,8 @@ $(H2 $(LNAME2 default_union_init, Default Initialization of Unions))
         ---
         )
 
+        $(P It is an error to supply initializers for members other than the first one.)
+
         $(SPEC_RUNNABLE_EXAMPLE_FAIL
         ---
         union V { int a; long b = 4; }     // error: union field `b` with default initialization `4` must be before field `a`
@@ -215,10 +231,10 @@ $(H2 $(LNAME2 default_union_init, Default Initialization of Unions))
         $(IMPLEMENTATION_DEFINED The values the fields other than the
         default initialized field are set to.)
 
-$(H2 $(LNAME2 static_union_init, Static Initialization of Unions))
+$(H3 $(LNAME2 static_union_init, Static Initialization of Unions))
 
         $(P Unions are initialized similarly to structs, except that only
-        one initializer is allowed.)
+        one member initializer is allowed.)
 
         $(SPEC_RUNNABLE_EXAMPLE_COMPILE
         ---
@@ -240,7 +256,7 @@ $(H2 $(LNAME2 static_union_init, Static Initialization of Unions))
         $(IMPLEMENTATION_DEFINED The values the fields other than the
         initialized field are set to.)
 
-$(H2 $(LNAME2 dynamic_struct_init, Dynamic Initialization of Structs))
+$(H3 $(LNAME2 dynamic_struct_init, Dynamic Initialization of Structs))
 
         $(P The $(RELATIVE_LINK2 static_struct_init, static initializer syntax)
         can also be used to initialize non-static variables.
@@ -269,7 +285,7 @@ S s = t;  // s.a is set to 3
 ----
 )
 
-        $(P If the struct has a $(LINK2 #struct-constructor, constructor), and
+        $(P If the struct has a $(RELATIVE_LINK2 struct-constructor, constructor), and
         the struct is initialized with a value that is of a different type,
         then the constructor is called:)
 
@@ -289,7 +305,8 @@ S s = 3; // sets s.a to 3 using S's constructor
 ----
 )
 
-        $(P If the struct does not have a constructor but $(D opCall) is
+        $(P If the struct does not have a constructor but
+        $(DDSUBLINK spec/operatoroverloading, FunctionCall, `opCall`) is
         overridden for the struct, and the struct is initialized with a value
         that is of a different type, then the $(D opCall) operator is called:)