Document named arguments

Fix issue 24241

Author: dkorpel

spec/expression.dd

@@ -1621,7 +1621,7 @@ $(GNAME NamedArgument):
     $(GLINK AssignExpression)
 )
 
-    $(P A callable expression can precede a list of arguments in parentheses.)
+    $(P A callable expression can precede a list of named arguments in parentheses.)
 
 ---
 void f(int, int);
@@ -1630,20 +1630,32 @@ f(5, 6);
 (&f)(5, 6);
 ---
 
-    $(P A type can precede a list of arguments.)
+$(H4 $(LNAME2 argument-parameter-matching, Matching Arguments to Parameters))
 
----
-struct S
-{
-    int x, y;
-}
-
-S s = S(1, 2);
----
+    $(P
+        Arguments in the `NamedArgumentList` are matched to function parameters as follows:
+    )
 
-    $(P See also: $(RELATIVE_LINK2 uniform_construction_syntax,
-    Uniform construction syntax for built-in scalar types))
+    $(P
+        If the first argument has no name, it will be assigned to the first function parameter.
+    )
+    $(P
+        A named argument is assigned to the function parameter with the same name.
+        It is an error if no such parameter exists.
+    )
+    $(P
+        Any other argument is assigned to the next parameter relative to the preceding argument's parameter.
+        It is an error if no such field exists, i.e. when the preceding argument assigns to the last parameter.
+    )
+    $(P
+        Assigning a parameter more than once is an error.
+        Not assigning a parameter any argument is also an error,
+        unless the parameter has a $(DDSUBLINK spec/function, function-default-args, Default Argument).
+    )
 
+$(H4 $(LNAME2 type-constructor-arguments, Constructing a Type with an Argument List))
+    $(P A type can precede a list of arguments.
+    See: $(DDSUBLINK spec/struct, struct-literal, Struct Literals)) and $(RELATIVE_LINK2 uniform_construction_syntax, Uniform construction syntax for built-in scalar types))
 
 $(H3 $(LEGACY_LNAME2 index_operations, index_expressions, Index Operations))
 
@@ -2499,6 +2511,12 @@ $(H3 $(LNAME2 uniform_construction_syntax, Uniform construction syntax for built
         auto b = wchar();   // same as: wchar.init
         ---
 
+    $(P The argument may not be given a name:)
+
+        ---
+        auto a = short(x: 1); // Error
+        ---
+
     $(P See also: $(DDSUBLINK spec/type, usual-arithmetic-conversions, Usual Arithmetic Conversions).)
 
 

spec/function.dd

@@ -1287,6 +1287,12 @@ $(H2 $(LNAME2 function-overloading, Function Overloading))
         $(LI exact match)
         )
 
+        $(P Named Arguments are resolved for a candidate according to
+        $(DDSUBLINK spec/expression, argument-parameter-matching, Matching Arguments to Parameters).
+        If this fails (for example, because the overload does not have a parameter with an argument's assigned named),
+        the level is $(I no match). Other than that, named arguments do not affect the matching level.
+        )
+
         $(P Each argument (including any $(CODE this) reference) is
         compared against the function's corresponding parameter to
         determine the match level for that argument. The match level
@@ -1694,10 +1700,6 @@ pure void f()
 }
 ---
 
-        $(P If the default value for a parameter is given, all following
-        parameters must also have default values.
-        )
-
         $(P See also: function type aliases
         $(DDSUBLINK spec/declaration, alias-function, with default values).)
 

spec/struct.dd

@@ -464,7 +464,7 @@ void test(int i)
 $(H2 $(LEGACY_LNAME2 StructLiteral, struct-literal, Struct Literals))
 
         $(P A struct literal consists of the name of the struct followed
-        by a parenthesized argument list:)
+        by a parenthesized named argument list:)
 
         $(SPEC_RUNNABLE_EXAMPLE_RUN
         ---
@@ -473,31 +473,58 @@ $(H2 $(LEGACY_LNAME2 StructLiteral, struct-literal, Struct Literals))
         int foo(S s) { return s.x; }
 
         foo( S(1, 2) ); // set field x to 1, field y to 2
+        foo( S(y: 2, x: 1) ); // same as above
         ---
         )
 
         $(P Struct literals are syntactically like function calls.
-        If a struct has a member function named $(CODE opCall), then
+        If a struct has a $(RELATIVE_LINK2 struct-constructor, Constructor)
+        or a member function named `opCall`, then
         struct literals for that struct are not possible. See also
         $(DDSUBLINK spec/operatoroverloading, FunctionCall, opCall operator overloading)
         for the issue workaround.)
         $(P
-        It is an error if there are more arguments than fields of
-        the struct.
-        If there are fewer arguments than fields, the remaining
-        fields are initialized with their respective default
-        initializers.)
+            If the first argument has no name, it will be assigned to the struct field that is defined first lexically.
+        )
+        $(P
+            A named argument is assigned to the struct field with the same name.
+            It is an error if no such field exists.
+        )
+        $(P
+            Any other argument is assigned to the next lexically defined struct field relative to the preceding argument's struct field.
+            It is an error if no such field exists, i.e. when the preceding argument assigns to the last struct field.
+        )
+        $(P
+            It is also an error to assign a field more than once.
+        )
         $(P
-        If there is a union field in the struct, only the first
+            Any fields not assigned a value are initialized with their respective default initializers.
+        )
+        $(NOTE
+            These rules are consistent with function calls, see $(DDSUBLINK spec/function, argument-parameter-matching, Matching Arguments to Parameters).
+        )
+        $(P
+        If there is a union field in the struct, only one
         member of the union can be initialized inside a
         struct literal. This matches the behaviour for union literals.
         )
 
+        $(SPEC_RUNNABLE_EXAMPLE_FAIL
+        ---
+        struct S { int x = 1; int y = 2, int z = 3; }
+
+        S s0 = S(y: 5, 6, x: 4); // `6` is assigned to field `z`, which comes after `y`
+        S s1 = S(y: 5, z: 6);    // Field x is not assigned, set to default initializer `1`
+        S s2 = S(y: 5, x: 4, 5); // Error: field `y` is assigned twice
+        S s3 = S(z: 2, 3);       // Error: no field beyond `z`
+        ---
+        )
+
 $(H2 $(LNAME2 union-literal, Union Literals))
 
-    $(P A union literal is like a struct literal, but only the first field can
-    be initialized with an initializer expression. Any field larger than the
-    first will have the remainder of its memory initialized to zero.
+    $(P A union literal is like a struct literal, but only one field can
+    be initialized with an initializer expression.
+    The remainder of the union's memory is initialized to zero.
     )
 
 $(SPEC_RUNNABLE_EXAMPLE_RUN
@@ -657,6 +684,21 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
         ---
         )
 
+        $(P Named arguments will be forwarded to the constructor and match parameter names, not struct field names.)
+
+        $(SPEC_RUNNABLE_EXAMPLE_FAIL
+        ---
+        struct S
+        {
+            int x;
+            int y;
+            this(int y, int z) { this.x = y; this.y = z; }
+        }
+        S a = S(x: 3, y: 4); // Error: constructor has no parameter named `x`
+        S b = S(y: 3, 4); // `y: 3` will set field `x` through parameter `y`
+        ---
+        )
+
         $(P A $(I default constructor) (i.e. one with an empty $(GLINK2 function, ParameterList))
         is not allowed.)