spec: remove evaluation order inconsistency

This is a clarification of what happens already.
Not a language change.

Fixes issue 7137.

LGTM=iant, r, rsc
R=r, rsc, iant, ken
CC=golang-codereviews
https://codereview.appspot.com/96000044

1 files changed, 31 insertions, 6 deletions

diff --git a/doc/go_spec.html b/doc/go_spec.html
index 496a7b2c3..114ceed86 100644
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -3996,8 +3996,11 @@ precision.
 <h3 id="Order_of_evaluation">Order of evaluation</h3>
 
 <p>
-When evaluating the <a href="#Operands">operands</a> of an expression,
-<a href="#Assignments">assignment</a>, or
+At package level, <a href="#Program_execution"</a>initialization dependencies</a>
+determine the evaluation order of individual initialization expressions in
+<a href="#Variable_declarations">variable declarations</a>.
+Otherwise, when evaluating the <a href="#Operands">operands</a> of an
+expression, assignment, or
 <a href="#Return_statements">return statement</a>,
 all function calls, method calls, and
 communication operations are evaluated in lexical left-to-right
@@ -4005,7 +4008,7 @@ order.
 </p>
 
 <p>
-For example, in the assignment
+For example, in the (function-local) assignment
 </p>
 <pre>
 y[f()], ok = g(h(), i()+x[j()], &lt;-c), k()
@@ -4022,12 +4025,34 @@ of <code>y</code> is not specified.
 <pre>
 a := 1
 f := func() int { a++; return a }
-x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified
-m := map[int]int{a: 1, a: 2} // m may be {2: 1} or {2: 2}: evaluation order between the two map assignments is not specified
-m2 := map[int]int{a: f()} // m2 may be {2: 3} or {3: 3}: evaluation order between the key and the value is not specified
+x := []int{a, f()}            // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified
+m := map[int]int{a: 1, a: 2}  // m may be {2: 1} or {2: 2}: evaluation order between the two map assignments is not specified
+n := map[int]int{a: f()}      // n may be {2: 3} or {3: 3}: evaluation order between the key and the value is not specified
 </pre>
 
 <p>
+At package level, initialization dependencies override the left-to-right rule
+for individual initialization expressions, but not for operands within each
+expression: 
+</p>
+
+<pre>
+var a, b, c = f() + v(), g(), sqr(u()) + v()
+
+func f() int        { return c }
+func g() int        { return a }
+func sqr(x int) int { return x*x }
+
+// functions u and v are independent of all other variables and functions
+</pre>
+
+<p>
+The function calls happen in the order
+<code>u()</code>, <code>sqr()</code>, <code>v()</code>,
+<code>f()</code>, <code>v()</code>, and <code>g()</code>.
+</p>
+
+<p>
 Floating-point operations within a single expression are evaluated according to
 the associativity of the operators.  Explicit parentheses affect the evaluation
 by overriding the default associativity.