go.tools: various comments + doc tweaks.

No functional changes.

LGTM=gri
R=gri
CC=golang-codereviews
https://golang.org/cl/74270043

go/callgraph/callgraph.go

@@ -100,6 +100,7 @@ func (e Edge) String() string {
 }
 
 // AddEdge adds the edge (caller, site, callee) to the call graph.
+// Elimination of duplicate edges is the caller's responsibility.
 func AddEdge(caller *Node, site ssa.CallInstruction, callee *Node) {
 	e := &Edge{caller, site, callee}
 	callee.In = append(callee.In, e)

go/callgraph/util.go

@@ -82,6 +82,10 @@ func PathSearch(start *Node, isEnd func(*Node) bool) []*Edge {
 // synthetic functions (except g.Root and package initializers),
 // preserving the topology.
 func (g *Graph) DeleteSyntheticNodes() {
+	// TODO(adonovan): opt: this step results in duplicate
+	// edges---approx 10% of the total.  I suspect this is due to
+	// some interface method calls dispatching to both (C).f and
+	// (*C).f where the latter is a wrapper.
 	for fn, cgn := range g.Nodes {
 		if cgn == g.Root || fn.Synthetic == "" || isInit(cgn.Func) {
 			continue // keep

go/pointer/gen.go

@@ -1103,6 +1103,10 @@ func (a *analysis) genRootCalls() *cgnode {
 	r.String()      // (asserts that it doesn't crash)
 	root := a.makeCGNode(r, 0, nil)
 
+	// TODO(adonovan): make an ssa utility to construct an actual
+	// root function so we don't need to special-case site-less
+	// call edges.
+
 	// For each main package, call main.init(), main.main().
 	for _, mainPkg := range a.config.Mains {
 		main := mainPkg.Func("main")

go/pointer/labels.go

@@ -14,7 +14,7 @@ import (
 )
 
 // A Label is an entity that may be pointed to by a pointer, map,
-// channel, 'func', slice or interface.  Labels include:
+// channel, 'func', slice or interface.
 //
 // Labels include:
 //      - functions
@@ -79,8 +79,9 @@ func (l Label) Pos() token.Pos {
 // String returns the printed form of this label.
 //
 // Examples:                                    Object type:
+//      x                                       (a variable)
 //      (sync.Mutex).Lock                       (a function)
-//      "foo":[]byte                            (a slice constant)
+//      convert                                 (array created by conversion)
 //      makemap                                 (map allocated via make)
 //      makechan                                (channel allocated via make)
 //      makeinterface                           (tagged object allocated by makeinterface)

go/ssa/const.go

@@ -73,6 +73,7 @@ func (c *Const) RelString(from *types.Package) string {
 	} else if c.Value.Kind() == exact.String {
 		s = exact.StringVal(c.Value)
 		const max = 20
+		// TODO(adonovan): don't cut a rune in half.
 		if len(s) > max {
 			s = s[:max-3] + "..." // abbreviate
 		}

go/ssa/create.go

@@ -48,6 +48,8 @@ func Create(iprog *loader.Program, mode BuilderMode) *Program {
 	}
 
 	for _, info := range iprog.AllPackages {
+		// TODO(adonovan): relax this constraint if the
+		// program contains only "soft" errors.
 		if info.TransitivelyErrorFree {
 			prog.CreatePackage(info)
 		}

go/ssa/ssa.go

@@ -312,11 +312,11 @@ type Function struct {
 // The tree may be navigated using Idom()/Dominees() and queried using
 // Dominates().
 //
-// The order of Preds and Succs are significant (to Phi and If
+// The order of Preds and Succs is significant (to Phi and If
 // instructions, respectively).
 //
 type BasicBlock struct {
-	Index        int            // index of this block within Func.Blocks
+	Index        int            // index of this block within Parent().Blocks
 	Comment      string         // optional label; no semantic significance
 	parent       *Function      // parent function
 	Instrs       []Instruction  // instructions in order
@@ -521,6 +521,7 @@ type BinOp struct {
 // MUL is pointer indirection (load).
 // XOR is bitwise complement.
 // SUB is negation.
+// NOT is logical negation.
 //
 // If CommaOk and Op=ARROW, the result is a 2-tuple of the value above
 // and a boolean indicating the success of the receive.  The
@@ -689,7 +690,7 @@ type MakeChan struct {
 // Both Len and Cap must be non-nil Values of integer type.
 //
 // (Alloc(types.Array) followed by Slice will not suffice because
-// Alloc can only create arrays of statically known length.)
+// Alloc can only create arrays of constant length.)
 //
 // Type() returns a (possibly named) *types.Slice.
 //

go/types/methodset.go

@@ -13,7 +13,7 @@ import (
 )
 
 // A MethodSet is an ordered set of concrete or abstract (interface) methods;
-// a method is a MethodVal selection.
+// a method is a MethodVal selection, and they are ordered by ascending m.Obj().Id().
 // The zero value for a MethodSet is a ready-to-use empty method set.
 type MethodSet struct {
 	list []*Selection

oracle/implements.go

@@ -97,7 +97,7 @@ func implements(o *Oracle, qpos *QueryPos) (queryResult, error) {
 		pos = nt.Obj()
 	}
 
-	// Sort types (arbitrarily) to ensure test nondeterminism.
+	// Sort types (arbitrarily) to ensure test determinism.
 	sort.Sort(typesByString(to))
 	sort.Sort(typesByString(from))
 	sort.Sort(typesByString(fromPtr))

oracle/oracle.go

@@ -162,7 +162,7 @@ type Result struct {
 	fset     *token.FileSet
 	q        queryResult       // the query-specific result
 	mode     string            // query mode
-	warnings []pointer.Warning // pointer analysis warnings
+	warnings []pointer.Warning // pointer analysis warnings (TODO(adonovan): fix: never populated!)
 }
 
 // Serial returns an instance of serial.Result, which implements the

oracle/peers.go

@@ -19,9 +19,10 @@ import (
 // peers enumerates, for a given channel send (or receive) operation,
 // the set of possible receives (or sends) that correspond to it.
 //
-// TODO(adonovan): support reflect.{Select,Recv,Send}.
+// TODO(adonovan): support reflect.{Select,Recv,Send,Close}.
 // TODO(adonovan): permit the user to query based on a MakeChan (not send/recv),
 // or the implicit receive in "for v := range ch".
+// TODO(adonovan): support "close" as a channel op.
 //
 func peers(o *Oracle, qpos *QueryPos) (queryResult, error) {
 	arrowPos := findArrow(qpos)
@@ -132,7 +133,7 @@ type chanOp struct {
 
 // chanOps returns a slice of all the channel operations in the instruction.
 func chanOps(instr ssa.Instruction) []chanOp {
-	// TODO(adonovan): handle calls to reflect.{Select,Recv,Send} too.
+	// TODO(adonovan): handle calls to reflect.{Select,Recv,Send,Close} too.
 	var ops []chanOp
 	switch instr := instr.(type) {
 	case *ssa.UnOp: