go.tools/ssa: doc tweaks + a sanity check.

R=gri
CC=golang-dev
https://golang.org/cl/14454053

ssa/doc.go

@@ -16,7 +16,7 @@
 //
 // The level of abstraction of the SSA form is intentionally close to
 // the source language to facilitate construction of source analysis
-// tools.  It is not primarily intended for machine code generation.
+// tools.  It is not intended for machine code generation.
 //
 // All looping, branching and switching constructs are replaced with
 // unstructured control flow.  We may add higher-level control flow

ssa/func.go

@@ -368,8 +368,9 @@ func (f *Function) removeNilBlocks() {
 }
 
 // SetDebugMode sets the debug mode for package pkg.  If true, all its
-// functions will include full debug info.  This greatly increases
-// the size of the instruction stream.
+// functions will include full debug info.  This greatly increases the
+// size of the instruction stream, and causes Functions to depend upon
+// the ASTs, potentially keeping them live in memory for longer.
 //
 func (pkg *Package) SetDebugMode(debug bool) {
 	// TODO(adonovan): do we want ast.File granularity?

ssa/sanity.go

@@ -368,6 +368,11 @@ func (s *sanity) checkFunction(fn *Function) bool {
 		s.checkBlock(b, i)
 	}
 	s.block = nil
+	for i, anon := range fn.AnonFuncs {
+		if anon.Enclosing != fn {
+			s.errorf("AnonFuncs[%d]=%s but %s.Enclosing=%s", i, anon, anon, anon.Enclosing)
+		}
+	}
 	s.fn = nil
 	return !s.insane
 }

ssa/ssa.go

@@ -1147,8 +1147,10 @@ type MapUpdate struct {
 //
 // DebugRef is a pseudo-instruction: it has no dynamic effect.
 //
-// Pos() returns Expr.Pos(), the position of the source-level
-// expression.
+// Pos() returns Expr.Pos(), the start position of the source-level
+// expression.  This is not the same as the "designated" token as
+// documented at Value.Pos(). e.g. CallExpr.Pos() does not return the
+// position of the ("designated") Lparen token.
 //
 // Object() returns the source-level (var/const/func) object denoted
 // by Expr if it is an *ast.Ident; otherwise it is nil.