Merge pull request #2972 from ntrel/inout

spec/function.dd: Improve inout section

Author: mdparker

spec/function.dd

@@ -43,9 +43,9 @@ $(GNAME Parameter):
     $(I ParameterAttributes)$(OPT) $(GLINK2 type, Type) $(D ...)
 
 $(GNAME ParameterAttributes):
-    $(I InOut)
+    $(GLINK InOut)
     $(GLINK2 attribute, UserDefinedAttribute)
-    $(I ParameterAttributes InOut)
+    $(I ParameterAttributes) $(GLINK InOut)
     $(I ParameterAttributes) $(GLINK2 attribute, UserDefinedAttribute)
     $(I ParameterAttributes)
 
@@ -646,52 +646,80 @@ $(H2 $(LNAME2 auto-ref-functions, Auto Ref Functions))
 
 $(H2 $(LNAME2 inout-functions, Inout Functions))
 
-    $(P Functions that differ only in whether the parameters are mutable, const or immutable
-        and have corresponding mutable, const or immutable return types can be combined
-        into one function with the $(D inout) type constructor.
+    $(P Functions that differ only in whether the parameters are mutable, `const` or `immutable`,
+        and have corresponding mutable, `const` or `immutable` return types, can be combined
+        into one function using the $(D inout) type constructor. Consider the following
+        overload set:
      )
-        $(SPEC_RUNNABLE_EXAMPLE_COMPILE
         ---
-        int[] f1(int[] a, int x, int y) { return a[x .. y]; }
+        int[] slice(int[] a, int x, int y) { return a[x .. y]; }
 
-        const(int)[] f2(const(int)[] a, int x, int y) { return a[x .. y]; }
+        const(int)[] slice(const(int)[] a, int x, int y) { return a[x .. y]; }
 
-        immutable(int)[] f3(immutable(int)[] a, int x, int y) { return a[x .. y]; }
+        immutable(int)[] slice(immutable(int)[] a, int x, int y) { return a[x .. y]; }
         ---
-        )
 
-    $(P The code generated by these three functions is identical.
-        To combine into one function, the $(D_KEYWORD inout)
-        type constructor is employed:)
+    $(P The code generated by each of these functions is identical.
+        The $(D_KEYWORD inout) type constructor can combine them into one function:)
 
         $(SPEC_RUNNABLE_EXAMPLE_COMPILE
         ---
-        inout(int)[] foo(inout(int)[] a, int x, int y) { return a[x .. y]; }
+        inout(int)[] slice(inout(int)[] a, int x, int y) { return a[x .. y]; }
         ---
         )
 
-    $(P The $(D_KEYWORD inout) forms a wildcard that stands in for
-        any of mutable, const, immutable, inout, or inout const. When the
-        function is called, the inout of the return type is changed to whatever
-        the mutable, const, immutable, inout, or inout const status of the
-        argument type to the parameter inout was.
+    $(P The $(D_KEYWORD inout) keyword forms a wildcard that stands in for
+        mutable, `const`, `immutable`, `inout`, or `inout const`.
+        When calling the function, the `inout` state of the return type is changed to
+        match that of the argument type passed to the `inout` parameter.
     )
 
-    $(P Inout types can be implicitly converted to const or inout const,
-        but to nothing else. Other types cannot be implicitly converted to inout.
-        Casting to or from inout is not allowed in @safe functions.
+    $(P `inout` can also be used as a type constructor inside a function that has a
+        parameter declared with `inout`. The `inout` state of a type declared with
+        `inout` is changed to match that of the argument type passed to the `inout`
+        parameter:
+    )
+
+        $(SPEC_RUNNABLE_EXAMPLE_COMPILE
+        ---
+        inout(int)[] asymmetric(inout(int)[] input_data)
+        {
+            inout(int)[] r = input_data;
+            while (r.length > 1 && r[0] == r[$-1])
+                r = r[1..$-1];
+            return r;
+        }
+        ---
+        )
+
+    $(P Inout types can be implicitly converted to `const` or `inout const`,
+        but to nothing else. Other types cannot be implicitly converted to `inout`.
+        Casting to or from `inout` is not allowed in `@safe` functions.
     )
 
-    $(P A set of arguments to a function with inout parameters is considered
-        a match if any inout argument types match exactly, or:)
+        $(SPEC_RUNNABLE_EXAMPLE_FAIL
+        ---
+        void f(inout int* ptr)
+        {
+            const int* p = ptr;
+            int* q = ptr; // error
+            immutable int* r = ptr; // error
+        }
+        ---
+        )
+
+    $(H3 $(LNAME2 matching-an-inout-parameter, Matching an `inout` Parameter))
+
+    $(P A set of arguments to a function with `inout` parameters is considered
+        a match if any `inout` argument types match exactly, or:)
 
     $(OL
-        $(LI No argument types are composed of inout types.)
-        $(LI A mutable, const or immutable argument type can be matched against each
-        corresponding parameter inout type.)
+        $(LI No argument types are composed of `inout` types.)
+        $(LI A mutable, `const` or `immutable` argument type can be matched against each
+        corresponding parameter `inout` type.)
     )
 
-    $(P If such a match occurs, the inout is considered the common qualifier of
+    $(P If such a match occurs, `inout` is considered the common qualifier of
         the matched qualifiers. If more than two parameters exist, the common
         qualifier calculation is recursively applied.
     )
@@ -705,7 +733,7 @@ $(H2 $(LNAME2 inout-functions, Inout Functions))
         $(TROW $(D inout const) $(LPAREN)= wc$(RPAREN), c, c, wc, wc, wc)
     )
 
-    $(P The inout in the return type is then rewritten to be the inout matched
+    $(P The `inout` in the return type is then rewritten to match the `inout`
         qualifiers:)
 
         $(SPEC_RUNNABLE_EXAMPLE_COMPILE
@@ -749,7 +777,7 @@ $(H2 $(LNAME2 inout-functions, Inout Functions))
         )
 
     $(P $(B Note:) Shared types cannot
-        be matched with inout.
+        be matched with `inout`.
     )
 
 $(H2 $(LNAME2 optional-parenthesis, Optional Parentheses))