go/parser: document that parser accepts a wider language than specified

See also issue #11271.

Change-Id: I34175f46ce137b14ca483500f673b0f8ee1f2108
Reviewed-on: https://go-review.googlesource.com/11262
Reviewed-by: Alan Donovan <adonovan@google.com>

diff --git a/src/go/parser/parser.go b/src/go/parser/parser.go
index 18278ba4b7ba0ed6a13a779d51f8580bc85d111e..e82c0bd12231e6763d1627774d0390dc34514942 100644 (file)
--- a/src/go/parser/parser.go
+++ b/src/go/parser/parser.go
@@ -7,6 +7,13 @@
 // output is an abstract syntax tree (AST) representing the Go source. The
 // parser is invoked through one of the Parse* functions.
 //
+// The parser accepts a larger language than is syntactically permitted by
+// the Go spec, for simplicity, and for improved robustness in the presence
+// of syntax errors. For instance, in method declarations, the receiver is
+// treated like an ordinary parameter list and thus may contain multiple
+// entries where the spec permits exactly one. Consequently, the corresponding
+// field in the AST (ast.FuncDecl.Recv) field is not restricted to one entry.
+//
 package parser
 
 import (