[spec/template.dd] Improve docs (#3173)

* [spec/template.dd] Improve docs

Add *Template Declarations* heading.
Fix: Value parameters are not limited to int, float, string.

Under *Explicit Instantiation*, add *Common Instantiation* subheading
and move paragraph (about multiple template with the same) name above
it.

Add *Type Sequence Deduction* subheading of *Sequence Parameters*.

Move *Template Constructors* below *Aggregate Templates* section.

* Fix multi-module example formatting

* Add *Template Instantiation* heading

Rename parameter deduction heading.

* Move ConstructorTemplate below FunctionTemplate

* Add note about using short syntax instead of template block

* Move 'IFTI vs static if' section to IFTI & add Restrictions subheading

Also tweak eponymous templates paragraph.
Add links.

* Undo *Parameter Type Deduction* change, will be done in another PR

* Single member templates are usually written with short syntax

* Move paragraph about overloaded templates to TemplateDeclaration

Change arguments -> parameters

* Tweak links

* Add example for template type parameter in TemplateDeclaration

Tweak wording of other parameter kinds.

* Alias parameters can take local symbols

* Tweak sentence about value parameters & restore CT specialization

* Tweak TemplateDeclaration docs & mention eponymous templates

* Remove *Template Instantiation* changes (for another PR)

Author: ntrel

spec/template.dd

@@ -4,8 +4,10 @@ $(SPEC_S Templates,
 
 $(HEADERNAV_TOC)
 
+$(H2 $(LNAME2 declarations, Template Declarations))
+
     $(P Templates are D's approach to generic programming.
-        Templates are defined with a $(I TemplateDeclaration):
+        Templates can be defined with a $(I TemplateDeclaration):
     )
 
 $(GRAMMAR
@@ -28,21 +30,27 @@ $(GNAME TemplateParameter):
     $(GLINK TemplateThisParameter)
 )
 
-    $(P The body of the $(I TemplateDeclaration) must be syntactically correct
+    $(P The *DeclDefs* body of the template must be syntactically correct
         even if never instantiated. Semantic analysis is not done until
-        instantiated. A template forms its own scope, and the template
-        body can contain classes, structs, types, enums, variables,
-        functions, and other templates.
+        instantiation. A template forms its own scope, and the template
+        body can contain declarations such as classes, structs, types,
+        enums, variables, functions, and other templates.
     )
 
-    $(P Template parameters can be types, values, symbols, or sequences.
-        Types can be any type.
-        Value parameters must be of an integral type, floating point
-        type, or string type and
-        specializations for them must resolve to an integral constant,
-        floating point constant, null, or a string literal.
-        Symbols can be any non-local symbol.
-        Sequences can contain zero or more types, values or symbols.
+    $(P Template parameters can take types, values, symbols, or sequences.
+        Type parameters can take any type.)
+
+    ---
+    template t(T) // declare type parameter T
+    {
+        T v; // declare a member variable of type T within template t
+    }
+    ---
+
+    $(P Value parameters can take any expression which can be statically
+        evaluated at compile time.
+        Alias parameters can take almost any symbol.
+        Sequence parameters can take zero or more types, values or symbols.
     )
 
     $(P Template parameter specializations
@@ -53,6 +61,19 @@ $(GNAME TemplateParameter):
         $(I TemplateParameter) in case one is not supplied.
     )
 
+    $(P If multiple templates with the same $(I Identifier) are
+        declared, they are distinct if they have different parameters
+        or are differently specialized.
+    )
+
+    $(P If a template has a member which has the same identifier as the
+        template, the template is an
+        $(RELATIVE_LINK2 implicit_template_properties, Eponymous Template).
+        `template` declarations with one eponymous member are usually
+        written as specific $(RELATIVE_LINK2 aggregate_templates, short syntax)
+        template declarations instead.)
+
+
 $(H2 $(LNAME2 explicit_tmp_instantiation, Explicit Template Instantiation))
 
     $(P Templates are explicitly instantiated with:
@@ -159,11 +180,6 @@ $(GNAME TemplateSingleArgument):
         static assert(is(TFoo!(3) == TFoo!(3u)));
         -----
 
-    $(P If multiple templates with the same $(I Identifier) are
-        declared, they are distinct if they have a different number of
-        arguments or are differently specialized.
-    )
-
     $(H3 $(LNAME2 copy_example, Practical Example))
 
     $(P A simple generic copy template would be:)
@@ -463,8 +479,8 @@ $(GNAME TemplateValueParameterDefault):
     $(D =) $(GLINK2 expression, SpecialKeyword)
 )
 
-    $(P Template value parameter types can be any type which can
-        be statically initialized at compile time.
+    $(P A template value parameter can take an argument of any expression which can
+        be statically evaluated at compile time.
         Template value arguments can be integer values, floating point values,
         nulls, string values, array literals of template value arguments,
         associative array literals of template value arguments,
@@ -485,6 +501,9 @@ $(GNAME TemplateValueParameterDefault):
         -----
         )
 
+    $(P Any specialization or default expression provided must be evaluatable
+        at compile-time.)
+
     $(P This example of template foo has a value parameter that
         is specialized for 10:)
 
@@ -820,6 +839,8 @@ $(GNAME TemplateSequenceParameter):
         to dynamically change, add, or remove elements either at compile-time or run-time.
     )
 
+$(H3 $(LNAME2 typeseq_deduction, Type Sequence Deduction))
+
     $(P Type sequences can be deduced from the trailing parameters
         of an $(RELATIVE_LINK2 ifti, implicitly instantiated) function template:)
 
@@ -940,7 +961,8 @@ $(H2 $(LNAME2 implicit_template_properties, Eponymous Templates))
         }
         ------
 
-        $(P Using functions and more types than the template:)
+        $(P The following example has more than one eponymous member and uses
+        $(RELATIVE_LINK2 ifti, Implicit Function Template Instantiation):)
 
         ------
         template foo(S, T)
@@ -957,36 +979,7 @@ $(H2 $(LNAME2 implicit_template_properties, Eponymous Templates))
         }
         ------
 
-        $(P When the template parameters must be deduced, the eponymous members
-        can't rely on a $(LINK2 version.html#StaticIfCondition, `static if`)
-        condition since the deduction relies on how the in members are used:)
-
-        ------
-        template foo(T)
-        {
-            static if (is(T)) // T is not yet known...
-                void foo(T t) {} // T is deduced from the member usage
-        }
-
-        void main()
-        {
-            foo(0); // Error: cannot deduce function from argument types
-            foo!int(0); // Ok since no deduction necessary
-        }
-        ------
-
-$(H2 $(LNAME2 template_ctors, Template Constructors))
-
-$(GRAMMAR
-$(GNAME ConstructorTemplate):
-    $(D this) $(GLINK TemplateParameters) $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK Constraint)$(OPT) $(D :)
-    $(D this) $(GLINK TemplateParameters) $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK Constraint)$(OPT) $(GLINK2 function, FunctionBody)
-)
-
-    $(P Templates can be used to form constructors for classes  and structs.
-    )
-
-$(H2 $(LNAME2 aggregate_templates, Aggregate Templates))
+$(H2 $(LNAME2 aggregate_templates, Aggregate Type Templates))
 
 $(GRAMMAR
 $(GNAME ClassTemplateDeclaration):
@@ -1103,6 +1096,8 @@ $(H3 $(LNAME2 ifti, Implicit Function Template Instantiation (IFTI)))
         from the function arguments.
     )
 
+$(H4 $(LNAME2 ifti-restrictions, Restrictions))
+
     $(P Function template type parameters that are to be implicitly
         deduced may not have specializations:)
 
@@ -1114,6 +1109,25 @@ $(H3 $(LNAME2 ifti, Implicit Function Template Instantiation (IFTI)))
         foo(&y);         // error, T has specialization
         ------
 
+        $(P When the template parameters must be deduced, the
+        $(RELATIVE_LINK2 implicit_template_properties, eponymous members)
+        can't rely on a $(LINK2 version.html#StaticIfCondition, `static if`)
+        condition since the deduction relies on how the members are used:)
+
+        ------
+        template foo(T)
+        {
+            static if (is(T)) // T is not yet known...
+                void foo(T t) {} // T is deduced from the member usage
+        }
+
+        void main()
+        {
+            foo(0); // Error: cannot deduce function from argument types
+            foo!int(0); // Ok since no deduction necessary
+        }
+        ------
+
 $(H4 $(LNAME2 ifti-conversions, Type Conversions))
 
     $(P If template type parameters match the literal expressions on function arguments,
@@ -1214,6 +1228,17 @@ $(H3 $(LNAME2 function-default, Default Arguments))
         ---
         )
 
+$(H2 $(LNAME2 template_ctors, Template Constructors))
+
+$(GRAMMAR
+$(GNAME ConstructorTemplate):
+    $(D this) $(GLINK TemplateParameters) $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK Constraint)$(OPT) $(D :)
+    $(D this) $(GLINK TemplateParameters) $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK Constraint)$(OPT) $(GLINK2 function, FunctionBody)
+)
+
+    $(P Templates can be used to form constructors for classes and structs.
+    )
+
 $(H2 $(LNAME2 variable-template, Enum & Variable Templates))
 
     $(P Like aggregates and functions, manifest constant and variable