Update Compile-Time Argument Lists article

Add headings.
Mention .tupleof.

Author: ntrel

articles/ctarguments.dd

@@ -4,27 +4,29 @@ $(D_S Compile-time Argument Lists,
 
 $(HEADERNAV_TOC)
 
-    $(P Compile-time lists is an important metaprogramming concept that comes naturally
+    $(H2 $(LNAME2 Background, Background))
+
+    $(P Compile-time lists are an important metaprogramming concept that comes naturally
         from D support for $(LINK2 variadic-function-templates.html, variadic templates). They
-        allow a programmer to operate on types, symbols and expressions enabling the ability to define
+        allow a programmer to operate on types, symbols and expressions, enabling the ability to define
         compile-time algorithms that operate on types, symbols and expressions.
     )
 
-    $(P For historical reasons those sometimes can be called tuples in documentation or compiler
-        internals but don't get confused : this doesn't have much in common with tuples that
+    $(P $(B Note:) For historical reasons these lists can sometimes be called tuples in documentation or compiler
+        internals, but don't get confused - they don't have much in common with tuples that
         commonly exist in other languages. Sequences of values of different types that can be
-        returned from functions are provided by $(LINK2 phobos/std_typecons.html#.Tuple, std.typecons.Tuple).
+        returned from functions are provided by $(PHOBOS typecons, .Tuple, std.typecons.Tuple).
         Using term "tuple" to mean compile-time lists is discouraged to avoid confusion, and if encountered
         should result in a $(LINK2 https://issues.dlang.org, documentation bug report).
     )
 
-    $(P Consider this simple snippet:)
+    $(P Consider this simple variadic template:)
 
     ---
     template Variadic(T...) { /* ... */ }
     ---
 
-    $(P `T` here is variadic $(LINK2 spec/template.html#TemplateArgumentList, template argument list)
+    $(P `T` here is a $(DDSUBLINK spec/template, variadic-templates, TemplateParameterSequence),
         which is a core language feature. It has its own special semantics,
         and, from the programmer's point of view, is most similar to an array of compile-time entities - types,
         symbols (names) and expressions (values). One can check the length of this list
@@ -39,15 +41,17 @@ $(HEADERNAV_TOC)
         pragma(msg, T[1]);
     }
 
-    alias Dummy = Variadic!(int, 42);
+    alias dummy = Variadic!(int, 42);
     // prints during compilation:
     // int
     // 42
     ---
 
-    $(P However, the language itself does not provide any means to define such lists outside of
+    $(H2 $(LNAME2 AliasSeq, AliasSeq))
+
+    $(P The language itself does not provide any means to define such lists outside of
         a template parameter declaration. Instead, there is a
-        $(MREF_ALTTEXT simple utility, std, meta) provided by the D standard
+        $(MREF_ALTTEXT simple utility, std, meta) provided by the standard
         library:
     )
 
@@ -63,10 +67,10 @@ $(HEADERNAV_TOC)
     import std.meta;
     // can alias to some other name
     alias Name = AliasSeq!(int, 42);
-    pragma(msg, Name[0]);
-    pragma(msg, Name[1]);
+    pragma(msg, Name[0]);   // int
+    pragma(msg, Name[1]);   // 42
     // or work with a list directly
-    pragma(msg, AliasSeq!("aaa", 0, double)[2]);
+    pragma(msg, AliasSeq!("aaa", 0, double)[2]);    // double
     ---
 
 $(H2 $(LNAME2 available-operations, Available operations))
@@ -137,6 +141,9 @@ $(H2 $(LNAME2 available-operations, Available operations))
         */
         ---
 
+        $(P $(B Note:) $(DDSUBLINK version, staticforeach, Static foreach)
+        should be preferred in new code.)
+
 $(H2 $(LNAME2 auto-expansion, Auto-expansion))
 
     $(P One less obvious property of compile-time argument lists is that when used
@@ -163,11 +170,13 @@ $(H2 $(LNAME2 auto-expansion, Auto-expansion))
 
 $(H2 $(LNAME2 homogenous-lists, Homogenous lists))
 
-    $(P An `AliasSeq` that consist of only type or expression (value) elements are
+    $(P An $(ALOCAL AliasSeq, AliasSeq) that consists of only type or expression (value) elements are
         commonly called "type lists" or "expression lists" respectively. The concept of
         a "symbol list" is rarely mentioned explicitly but fits the same pattern.
     )
 
+$(H3 $(LNAME2 type-seq, Type lists))
+
     $(P It is possible to use homogenous type lists in declarations:)
 
     ---
@@ -176,6 +185,8 @@ $(H2 $(LNAME2 homogenous-lists, Homogenous lists))
     void foo(Params); // void foo(int, double, string);
     ---
 
+$(H4 $(LNAME2 type-seq-instantiation, Type list instantiation))
+
     $(P D supports a special variable declaration syntax where a type list acts as a type:)
 
     ---
@@ -188,33 +199,49 @@ $(H2 $(LNAME2 homogenous-lists, Homogenous lists))
         variables[1] = 42.0;
         variables[2] = "just a normal variable";
     }
-
-    /* The compiler will rewrite such a declaration to something like this:
-
+    ---
+    $(P The compiler will rewrite such a declaration to something like this:)
+    ---
     int __var1;
     double __var2;
     string __var3;
     alias variables = AliasSeq!(__var1, __var2, __var3);
-    */
     ---
 
-    $(P This is also what happens when declaring a variadic template function:)
+    $(P So a type list instance acts as a symbol list that only aliases
+    variables.)
+
+    $(P $(DDSUBLINK spec/template, variadic-templates, Variadic template functions)
+    use a type list instance for a function parameter:)
 
     ---
     void foo(T...)(T args)
     {
-        // 'args' here is a compile-time list of symbols that
-        // refer to underlying compiler-generated arguments
+        // 'T' is a type list of argument types.
+        // 'args' is an instance of T whose elements are the function parameters
+        static assert(is(typeof(args) == T));
+        args[0] = T[0].init;
     }
     ---
 
+    $(P $(B Note:) $(PHOBOS typecons, .Tuple, std.typecons.Tuple) wraps a type list instance,
+    preventing auto-expansion, and allowing it to be returned from functions.)
+
+$(H3 $(LNAME2 value-seq, Expression lists))
+
     $(P It is possible to use expression lists with values of the same type to declare array literals:)
 
     ---
     import std.meta;
     static assert ([ AliasSeq!(1, 2, 3) ] == [ 1, 2, 3 ]);
     ---
 
+$(H4 $(LNAME2 tupleof, Aggregate field lists))
+
+    $(P $(DDSUBLINK spec/class, class_properties, `.tupleof`) is a
+    class/struct instance property that provides an expression list
+    of fields.)
+
 )
 
 Macros: