Merge pull request #3183 from ntrel/template-params

[spec/template.dd] Add *Template Parameters* heading

Signed-off-by: Dennis <dkorpel@users.noreply.github.com>
Merged-on-behalf-of: Dennis <dkorpel@users.noreply.github.com>

Author: dlang-bot

spec/template.dd

@@ -21,13 +21,6 @@ $(GNAME TemplateParameterList):
     $(GLINK TemplateParameter)
     $(GLINK TemplateParameter) $(D ,)
     $(GLINK TemplateParameter) $(D ,) $(GSELF TemplateParameterList)
-
-$(GNAME TemplateParameter):
-    $(GLINK TemplateTypeParameter)
-    $(GLINK TemplateValueParameter)
-    $(GLINK TemplateAliasParameter)
-    $(GLINK TemplateSequenceParameter)
-    $(GLINK TemplateThisParameter)
 )
 
     $(P The *DeclDefs* body of the template must be syntactically correct
@@ -37,8 +30,8 @@ $(GNAME TemplateParameter):
         enums, variables, functions, and other templates.
     )
 
-    $(P Template parameters can take types, values, symbols, or sequences.
-        Type parameters can take any type.)
+    $(P $(RELATIVE_LINK2 parameters, Template parameters) can take types,
+        values, symbols, or sequences.)
 
     ---
     template t(T) // declare type parameter T
@@ -47,19 +40,16 @@ $(GNAME TemplateParameter):
     }
     ---
 
-    $(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 A template parameter can have a *specialization* which
+        constrains an argument the $(I TemplateParameter) can
+        accept.)
 
-    $(P Template parameter specializations
-        constrain the values or types the $(I TemplateParameter) can
-        accept.
-    )
-    $(P Template parameter defaults are the value or type to use for the
-        $(I TemplateParameter) in case one is not supplied.
-    )
+    ---
+    template t(T : int) // type T must implicitly convert to int
+    {
+        ...
+    }
+    ---
 
     $(P If multiple templates with the same $(I Identifier) are
         declared, they are distinct if they have different parameters
@@ -245,10 +235,37 @@ $(H2 $(LNAME2 instantiation_scope, Instantiation Scope))
         ------
 
     $(P $(I TemplateParameter) specializations and default
-        values are evaluated in the scope of the $(I TemplateDeclaration).
+        arguments are evaluated in the scope of the $(I TemplateDeclaration).
     )
 
-$(H2 $(LNAME2 argument_deduction, Argument Deduction))
+
+$(H2 $(LNAME2 parameters, Template Parameters))
+
+$(GRAMMAR
+$(GNAME TemplateParameter):
+    $(GLINK TemplateTypeParameter)
+    $(GLINK TemplateValueParameter)
+    $(GLINK TemplateAliasParameter)
+    $(GLINK TemplateSequenceParameter)
+    $(GLINK TemplateThisParameter)
+)
+
+    $(P Template parameters can take types, values, symbols, or sequences.)
+
+    $(UL
+    $(LI Type parameters can take any type.)
+    $(LI Value parameters can take any expression which can be statically
+        evaluated at compile time.)
+    $(LI Alias parameters can take almost any symbol.)
+    $(LI Sequence parameters can take zero or more types, values or symbols.)
+    )
+
+    $(P $(RELATIVE_LINK2 template_parameter_def_values, A default argument)
+        specifies the type, value or symbol to use for the
+        $(I TemplateParameter) when a matching argument is not supplied.
+    )
+
+$(H3 $(LNAME2 argument_deduction, Type Parameter Deduction))
 
     $(P The types of template parameters are deduced for a particular
         template instantiation by comparing the template argument with
@@ -322,7 +339,7 @@ $(H2 $(LNAME2 argument_deduction, Argument Deduction))
                                    // (3) U is B
         ------
 
-$(H2 $(LNAME2 template_type_parameters, Template Type Parameters))
+$(H3 $(LNAME2 template_type_parameters, Type Parameters))
 
 $(GRAMMAR
 $(GNAME TemplateTypeParameter):
@@ -338,7 +355,7 @@ $(GNAME TemplateTypeParameterDefault):
     $(D =) $(GLINK2 type, Type)
 )
 
-$(H3 $(LNAME2 parameters_specialization, Specialization))
+$(H4 $(LNAME2 parameters_specialization, Specialization))
 
     $(P Templates may be specialized for particular types of arguments
         by following the template parameter identifier with a : and the
@@ -364,7 +381,7 @@ $(H3 $(LNAME2 parameters_specialization, Specialization))
     )
 
 
-$(H2 $(LNAME2 template_this_parameter, Template This Parameters))
+$(H3 $(LNAME2 template_this_parameter, This Parameters))
 
 $(GRAMMAR
 $(GNAME TemplateThisParameter):
@@ -406,7 +423,9 @@ S
 immutable(S)
 )
 
-    $(P This is especially useful when used with inheritance. For example,
+$(H4 $(LNAME2 this_rtti, Avoiding Runtime Type Checks))
+
+    $(P *TemplateThisParameter* is especially useful when used with inheritance. For example,
         consider the implementation of a final base method which returns a derived
         class type. Typically this would return a base type, but that would prohibit
         calling or accessing derived properties of the type:)
@@ -436,7 +455,7 @@ immutable(S)
         ---
 
     $(P Here the method $(D add) returns the base type, which doesn't implement the
-        $(D remove) method. The $(D template this) parameter can be used for this purpose:)
+        $(D remove) method. The template `this` parameter can be used for this purpose:)
 
         $(SPEC_RUNNABLE_EXAMPLE_COMPILE
         ---
@@ -469,7 +488,7 @@ immutable(S)
         ---
         )
 
-$(H2 $(LNAME2 template_value_parameter, Template Value Parameters))
+$(H3 $(LNAME2 template_value_parameter, Value Parameters))
 
 $(GRAMMAR
 $(GNAME TemplateValueParameter):
@@ -508,12 +527,15 @@ $(GNAME TemplateValueParameterDefault):
         -----
         )
 
+$(H4 $(LNAME2 value_specialization, Specialization))
+
     $(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:)
+    $(P In this example, template `foo` has a value parameter that
+        is specialized for `10`:)
 
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
         ------
         template foo(U : int, int v : 10)
         {
@@ -523,10 +545,15 @@ $(GNAME TemplateValueParameterDefault):
         void main()
         {
             assert(foo!(int, 10).x == 10);
+            static assert(!__traits(compiles, foo!(int, 11)));
         }
         ------
+        )
+
+    $(P This can be useful when a different template body is required for a specific value.
+        Another template overload would be defined to take other integer literal values.)
 
-$(H2 $(LNAME2 aliasparameters, Template Alias Parameters))
+$(H3 $(LNAME2 aliasparameters, Alias Parameters))
 
 $(GRAMMAR
 $(GNAME TemplateAliasParameter):
@@ -740,7 +767,7 @@ $(GNAME TemplateAliasParameterDefault):
         ))
     )
 
-$(H3 $(LNAME2 typed_alias_op, Typed alias parameters))
+$(H4 $(LNAME2 typed_alias_op, Typed Alias Parameters))
 
     $(P Alias parameters can also be typed.
         These parameters will accept symbols of that type:)
@@ -754,7 +781,7 @@ $(H3 $(LNAME2 typed_alias_op, Typed alias parameters))
         Foo!f;  // fails to instantiate
         ------
 
-$(H3 $(LNAME2 alias_parameter_specialization, Specialization))
+$(H4 $(LNAME2 alias_parameter_specialization, Specialization))
 
     $(P Alias parameters can accept both literals and user-defined type symbols,
         but they are less specialized than the matches to type parameters and
@@ -782,7 +809,7 @@ $(H3 $(LNAME2 alias_parameter_specialization, Specialization))
         alias bar = Bar!(C!int);    // instantiates #5
         ------
 
-$(H2 $(LNAME2 variadic-templates, Template Sequence Parameters))
+$(H3 $(LNAME2 variadic-templates, Sequence Parameters))
 
 $(GRAMMAR
 $(GNAME TemplateSequenceParameter):
@@ -846,7 +873,7 @@ $(GNAME TemplateSequenceParameter):
         to dynamically change, add, or remove elements either at compile-time or run-time.
     )
 
-$(H3 $(LNAME2 typeseq_deduction, Type Sequence Deduction))
+$(H4 $(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:)
@@ -913,7 +940,7 @@ a
         )
         See also: $(REF partial, std,functional)
 
-$(H3 $(LNAME2 variadic_template_specialization, Specialization))
+$(H4 $(LNAME2 variadic_template_specialization, Specialization))
 
     $(P If both a template with a sequence parameter and a template
         without a sequence parameter exactly match a template instantiation,
@@ -935,9 +962,9 @@ $(H3 $(LNAME2 variadic_template_specialization, Specialization))
         alias foo4 = Foo!(int, 3, std);  // instantiates #4
         ----
 
-$(H2 $(LNAME2 template_parameter_def_values, Template Parameter Default Values))
+$(H3 $(LNAME2 template_parameter_def_values, Default Arguments))
 
-    $(P Trailing template parameters can be given default values:)
+    $(P Trailing template parameters can be given default arguments:)
 
         ------
         template Foo(T, U = int) { ... }
@@ -1032,7 +1059,7 @@ $(GNAME UnionTemplateDeclaration):
         }
         ------
 
-    $(P See also: $(RELATIVE_LINK2 template_this_parameter, Template This Parameters).
+    $(P See also: $(RELATIVE_LINK2 template_this_parameter, This Parameters).
     )
 
     $(P Analogously to class templates, struct, union and interfaces