cmd/compile: document function syntax representation

Not perfect, but it's a start.

Change-Id: I3283385223a39ea73567b0130290bfe4de69d018
Reviewed-on: https://go-review.googlesource.com/73552Reviewed-by: Robert Griesemer <gri@golang.org>

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

@@ -351,6 +351,48 @@ type Param struct {
 	Alias  bool // node is alias for Ntype (only used when type-checking ODCLTYPE)
 }
 
+// Functions
+//
+// A simple function declaration is represented as an ODCLFUNC node f
+// and an ONAME node n. They're linked to one another through
+// f.Func.Nname == n and n.Name.Defn == f. When functions are
+// referenced by name in an expression, the function's ONAME node is
+// used directly.
+//
+// Function names have n.Class() == PFUNC. This distinguishes them
+// from variables of function type.
+//
+// Confusingly, n.Func and f.Func both exist, but commonly point to
+// different Funcs. (Exception: an OCALLPART's Func does point to its
+// ODCLFUNC's Func.)
+//
+// A method declaration is represented like functions, except n.Sym
+// will be the qualified method name (e.g., "T.m") and
+// f.Func.Shortname is the bare method name (e.g., "m").
+//
+// Method expressions are represented as ONAME/PFUNC nodes like
+// function names, but their Left and Right fields still point to the
+// type and method, respectively. They can be distinguished from
+// normal functions with isMethodExpression. Also, unlike function
+// name nodes, method expression nodes exist for each method
+// expression. The declaration ONAME can be accessed with
+// x.Type.Nname(), where x is the method expression ONAME node.
+//
+// Method values are represented by ODOTMETH/ODOTINTER when called
+// immediately, and OCALLPART otherwise. They are like method
+// expressions, except that for ODOTMETH/ODOTINTER the method name is
+// stored in Sym instead of Right.
+//
+// Closures are represented by OCLOSURE node c. They link back and
+// forth with the ODCLFUNC via Func.Closure; that is, c.Func.Closure
+// == f and f.Func.Closure == c.
+//
+// Function bodies are stored in f.Nbody, and inline function bodies
+// are stored in n.Func.Inl. Pragmas are stored in f.Func.Pragma.
+//
+// Imported functions skip the ODCLFUNC, so n.Name.Defn is nil. They
+// also use Dcl instead of Inldcl.
+
 // Func holds Node fields used only with function-like nodes.
 type Func struct {
 	Shortname *types.Sym