spec: shadowed return parameters may be disallowed

This documents the implemented behavior of both
gc and gccgo as an implementation restriction.

NOT A LANGUAGE CHANGE.

Fixes #5425.

LGTM=rsc, r, iant
R=r, iant, rsc, ken
CC=golang-codereviews
https://golang.org/cl/71430043

diff --git a/doc/go_spec.html b/doc/go_spec.html
index 9043431c4d1df1e687e425d18f3de76af5e9009f..dada50357498c44c68424421bb9d38779004989a 100644 (file)
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -1,6 +1,6 @@
 <!--{
        "Title": "The Go Programming Language Specification",
-       "Subtitle": "Version of March 4, 2014",
+       "Subtitle": "Version of March 5, 2014",
        "Path": "/ref/spec"
 }-->
 
@@ -5002,6 +5002,21 @@ function. A "return" statement that specifies results sets the result parameters
 any deferred functions are executed.
 </p>
 
+<p>
+Implementation restriction: A compiler may disallow an empty expression list
+in a "return" statement if a different entity (constant, type, or variable)
+with the same name as a result parameter is in
+<a href="#Declarations_and_scope">scope</a> at the place of the return.
+</p>
+
+<pre>
+func f(n int) (res int, err error) {
+       if _, err := f(n-1); err != nil {
+               return  // invalid return statement: err is shadowed
+       }
+       return
+}
+</pre>
 
 <h3 id="Break_statements">Break statements</h3>