cmd/compile: update comments only for Node types and some functions

Improve the comments in syntax.go on Node structs and constants. Also, updated a
few function header comments.

Change-Id: I3e6e4a3c5678fc0b4e18844507b3460303ce1240
Reviewed-on: https://go-review.googlesource.com/c/go/+/269538
Reviewed-by: Matthew Dempsky <mdempsky@google.com>
Trust: Dan Scales <danscales@google.com>

src/cmd/compile/internal/gc/syntax.go

@@ -344,14 +344,22 @@ func (n *Node) CanBeAnSSASym() {
 
 // Name holds Node fields used only by named nodes (ONAME, OTYPE, OPACK, OLABEL, some OLITERAL).
 type Name struct {
-	Pack      *Node      // real package for import . names
-	Pkg       *types.Pkg // pkg for OPACK nodes
-	Defn      *Node      // initializing assignment
-	Curfn     *Node      // function for local variables
-	Param     *Param     // additional fields for ONAME, OTYPE
-	Decldepth int32      // declaration loop depth, increased for every loop or label
-	Vargen    int32      // unique name for ONAME within a function.  Function outputs are numbered starting at one.
-	flags     bitset16
+	Pack *Node      // real package for import . names
+	Pkg  *types.Pkg // pkg for OPACK nodes
+	// For a local variable (not param) or extern, the initializing assignment (OAS or OAS2).
+	// For a closure var, the ONAME node of the outer captured variable
+	Defn *Node
+	// The ODCLFUNC node (for a static function/method or a closure) in which
+	// local variable or param is declared.
+	Curfn     *Node
+	Param     *Param // additional fields for ONAME, OTYPE
+	Decldepth int32  // declaration loop depth, increased for every loop or label
+	// Unique number for ONAME nodes within a function. Function outputs
+	// (results) are numbered starting at one, followed by function inputs
+	// (parameters), and then local variables. Vargen is used to distinguish
+	// local variables/params with the same name.
+	Vargen int32
+	flags  bitset16
 }
 
 const (
@@ -608,10 +616,16 @@ func (p *Param) SetEmbedFiles(list []string) {
 // Func holds Node fields used only with function-like nodes.
 type Func struct {
 	Shortname *types.Sym
-	Enter     Nodes // for example, allocate and initialize memory for escaping parameters
-	Exit      Nodes
-	Cvars     Nodes   // closure params
-	Dcl       []*Node // autodcl for this func/closure
+	// Extra entry code for the function. For example, allocate and initialize
+	// memory for escaping parameters. However, just for OCLOSURE, Enter is a
+	// list of ONAME nodes of captured variables
+	Enter Nodes
+	Exit  Nodes
+	// ONAME nodes for closure params, each should have closurevar set
+	Cvars Nodes
+	// ONAME nodes for all params/locals for this func/closure, does NOT
+	// include closurevars until transformclosure runs.
+	Dcl []*Node
 
 	// Parents records the parent scope of each scope within a
 	// function. The root scope (0) has no parent, so the i'th
@@ -630,7 +644,7 @@ type Func struct {
 	DebugInfo  *ssa.FuncDebug
 	Ntype      *Node // signature
 	Top        int   // top context (ctxCallee, etc)
-	Closure    *Node // OCLOSURE <-> ODCLFUNC
+	Closure    *Node // OCLOSURE <-> ODCLFUNC (see header comment above)
 	Nname      *Node // The ONAME node associated with an ODCLFUNC (both have same Type)
 	lsym       *obj.LSym
 
@@ -680,6 +694,8 @@ const (
 	funcWrapper                   // is method wrapper
 	funcNeedctxt                  // function uses context register (has closure variables)
 	funcReflectMethod             // function calls reflect.Type.Method or MethodByName
+	// true if closure inside a function; false if a simple function or a
+	// closure in a global variable initialization
 	funcIsHiddenClosure
 	funcHasDefer                 // contains a defer statement
 	funcNilCheckDisabled         // disable nil checks when compiling this function
@@ -731,8 +747,10 @@ const (
 	OXXX Op = iota
 
 	// names
-	ONAME    // var or func name
-	ONONAME  // unnamed arg or return value: f(int, string) (int, error) { etc }
+	ONAME // var or func name
+	// Unnamed arg or return value: f(int, string) (int, error) { etc }
+	// Also used for a qualified package identifier that hasn't been resolved yet.
+	ONONAME
 	OTYPE    // type name
 	OPACK    // import
 	OLITERAL // literal
@@ -752,14 +770,18 @@ const (
 	OSTR2BYTES    // Type(Left) (Type is []byte, Left is a string)
 	OSTR2BYTESTMP // Type(Left) (Type is []byte, Left is a string, ephemeral)
 	OSTR2RUNES    // Type(Left) (Type is []rune, Left is a string)
-	OAS           // Left = Right or (if Colas=true) Left := Right
-	OAS2          // List = Rlist (x, y, z = a, b, c)
-	OAS2DOTTYPE   // List = Right (x, ok = I.(int))
-	OAS2FUNC      // List = Right (x, y = f())
-	OAS2MAPR      // List = Right (x, ok = m["foo"])
-	OAS2RECV      // List = Right (x, ok = <-c)
-	OASOP         // Left Etype= Right (x += y)
-	OCALL         // Left(List) (function call, method call or type conversion)
+	// Left = Right or (if Colas=true) Left := Right
+	// If Colas, then Ninit includes a DCL node for Left.
+	OAS
+	// List = Rlist (x, y, z = a, b, c) or (if Colas=true) List := Rlist
+	// If Colas, then Ninit includes DCL nodes for List
+	OAS2
+	OAS2DOTTYPE // List = Right (x, ok = I.(int))
+	OAS2FUNC    // List = Right (x, y = f())
+	OAS2MAPR    // List = Right (x, ok = m["foo"])
+	OAS2RECV    // List = Right (x, ok = <-c)
+	OASOP       // Left Etype= Right (x += y)
+	OCALL       // Left(List) (function call, method call or type conversion)
 
 	// OCALLFUNC, OCALLMETH, and OCALLINTER have the same structure.
 	// Prior to walk, they are: Left(List), where List is all regular arguments.