[spec/statement.dd] Improve foreach docs

Explain the variables declared in ForeachTypeList more.

Move paragraph about inferring the type of the ForeachType declaration
from the `ref` subheading to main foreach section. Also move note about
`auto` being redundant from array subheading, along with the example.
Modify the example as no need to show `auto` causing an error.

Mark resizing/reassigning a container during foreach as undefined
behaviour.

Author: ntrel

spec/statement.dd

@@ -445,7 +445,7 @@ for (int i = 0; i < 10; i++)
 
 $(H2 $(LEGACY_LNAME2 ForeachStatement, foreach-statement, Foreach Statement))
 
-$(P A `foreach` statement loops over the contents of an aggregate.)
+$(P A `foreach` statement iterates a series of values.)
 
 $(GRAMMAR
 $(GNAME AggregateForeach):
@@ -483,26 +483,48 @@ $(GNAME ForeachAggregate):
 
 $(P
         $(I ForeachAggregate) is evaluated. It must evaluate to an expression
-        of type static array, dynamic array, associative array,
+        which is a static array, dynamic array, associative array,
         struct, class, delegate, or sequence.
         The *NoScopeNonEmptyStatement* is executed, once for each element of the
         aggregate.
-        At the start of each iteration, the variables declared by
-        the $(I ForeachTypeList)
-        are set to be a copy of the elements of the aggregate.
-        If the $(I ForeachTypeAttribute) is $(D ref), it is a reference to the
-        contents of that aggregate.
-        If the $(I ForeachTypeAttribute) is $(D scope), the $(I ForeachType) declaration
-        will have $(D scope) semantics.
 )
 $(P
-        The aggregate must be loop invariant, meaning that
-        elements to the aggregate cannot be added or removed from it
+        The number of variables declared in $(I ForeachTypeList)
+        depends on the kind of aggregate. The declared variables are
+        set at the start of each iteration.
+)
+$(UL
+        $(LI By default a single declared variable is a copy of the current element.)
+        $(LI If the $(I ForeachTypeAttribute) is $(D ref), that variable will
+        be a reference to the current element of the aggregate.)
+        $(LI If the $(I ForeachTypeAttribute) is $(D scope), the variable
+        will have $(DDSUBLINK spec/function, scope-parameters, `scope`) semantics.)
+)
+$(P
+        If not specified, the type of a $(I ForeachType) variable
+        can be inferred from the type of the $(I ForeachAggregate).
+        Note that `auto` is not a valid $(I ForeachTypeAttribute).
+        The two `foreach` statements below are equivalent:
+)
+$(SPEC_RUNNABLE_EXAMPLE_RUN
+--------------
+int[] arr = [1, 2, 3];
+
+foreach (int n; arr)
+    writeln(n);
+
+foreach (n; arr) // ok, n is an int
+    writeln(n);
+--------------
+)
+$(P
+        The aggregate must be *loop invariant*, meaning that
+        elements cannot be added or removed from the aggregate
         in the *NoScopeNonEmptyStatement*.
 )
 
         $(P A $(GLINK BreakStatement) in the body of the foreach will exit the
-        foreach, a $(GLINK ContinueStatement) will immediately start the
+        loop. A $(GLINK ContinueStatement) will immediately start the
         next iteration.
         )
 
@@ -541,21 +563,6 @@ foreach (size_t i, char c; a)
         order.
         )
 
-        $(P $(B Note:) The $(I ForeachTypeAttribute) is implicit, and when a
-        type is not specified, it is inferred. In that case, $(D auto) is
-        implied, and it is not necessary (and actually forbidden) to use it.
-        )
-
---------------
-int[] arr;
-...
-foreach (n; arr) // ok, n is an int
-    writeln(n);
-
-foreach (auto n; arr) // error, auto is redundant
-    writeln(n);
---------------
-
 $(H3 $(LNAME2 foreach_over_arrays_of_characters, Foreach over Arrays of Characters))
 
         $(P If the aggregate expression is a static or dynamic array of
@@ -960,7 +967,8 @@ main()
 
 $(H3 $(LNAME2 foreach_ref_parameters, Foreach Ref Parameters))
 
-        $(P $(D ref) can be used to update the original elements:
+        $(P $(D ref) can be used to update the original elements for some
+        kinds of container. Arrays support this:
         )
 
     $(SPEC_RUNNABLE_EXAMPLE_RUN
@@ -984,30 +992,28 @@ $(CONSOLE
 8
 9
 )
-        $(P $(D ref) can not be applied to the index values.)
-
-        $(P If not specified, the $(I Type)s in the $(I ForeachType) can be
-        inferred from
-        the type of the $(I ForeachAggregate).
-        )
+        $(P $(D ref) cannot be applied to an array index variable.)
 
 $(H3 $(LNAME2 foreach_restrictions, Foreach Restrictions))
 
-        $(P The aggregate itself must not be resized, reallocated, free'd,
+        $(UNDEFINED_BEHAVIOR The aggregate itself must not be resized, reallocated, free'd,
         reassigned or destructed
         while the foreach is iterating over the elements.
         )
 
 --------------
-int[] a;
-int[] b;
-foreach (int i; a)
+int[] a, b;
+...
+foreach (int v; a)
 {
-    a = null;       // error
+    a ~= 4;         // error
     a.length += 10; // error
+
+    a = null;       // error
     a = b;          // error
 }
-a = null;         // ok
+a ~= 4;   // OK
+a = null; // OK
 --------------
 
 $(H3 $(LEGACY_LNAME2 ForeachRangeStatement, foreach-range-statement, Foreach Range Statement))
@@ -1030,11 +1036,13 @@ $(GNAME ForeachRangeStatement):
 
         $(P
         $(I ForeachType) declares a variable with either an explicit type,
-        or a type inferred from $(I LwrExpression) and $(I UprExpression).
+        or a common type inferred from $(I LwrExpression) and $(I UprExpression).
         The $(I ScopeStatement) is then executed $(I n) times, where $(I n)
-        is the result of $(I UprExpression) - $(I LwrExpression).
+        is the result of $(I UprExpression) `-` $(I LwrExpression).
         If $(I UprExpression) is less than or equal to $(I LwrExpression),
-        the $(I ScopeStatement) is executed zero times.
+        the $(I ScopeStatement) is not executed.)
+
+        $(P
         If $(I Foreach) is $(D foreach), then the variable is set to
         $(I LwrExpression), then incremented at the end of each iteration.
         If $(I Foreach) is $(D foreach_reverse), then the variable is set to