Add some comments.

Author: sbarzowski

linter/internal/types/build_graph.go

@@ -33,8 +33,22 @@ func (g *typeGraph) getExprPlaceholder(node ast.Node) placeholderID {
 	return g.exprPlaceholder[node]
 }
 
-// XXX(sbarzowski): Tests for imported type
-// XXX(sbarzowski): explain the difference between prepare and calc
+// prepareTP recursively creates type placeholders for all expressions
+// in a subtree and calculates the definitions for them.
+func prepareTP(node ast.Node, varAt map[ast.Node]*common.Variable, g *typeGraph) {
+	if node == nil {
+		panic("Node cannot be nil")
+	}
+	p := g.newPlaceholder()
+	g.exprPlaceholder[node] = p
+	prepareTPWithPlaceholder(node, varAt, g, p)
+}
+
+// prepareTPWithPlaceholder recursively creates type placeholders for all
+// expressions in a subtree.
+//
+// The type placeholder for the root of the subtree is not created, but already provided.
+// This allows us to express mutually recursive relationships.
 func prepareTPWithPlaceholder(node ast.Node, varAt map[ast.Node]*common.Variable, g *typeGraph, p placeholderID) {
 	if node == nil {
 		panic("Node cannot be nil")
@@ -74,15 +88,6 @@ func prepareTPWithPlaceholder(node ast.Node, varAt map[ast.Node]*common.Variable
 	*(g.placeholder(p)) = calcTP(node, varAt, g)
 }
 
-func prepareTP(node ast.Node, varAt map[ast.Node]*common.Variable, g *typeGraph) {
-	if node == nil {
-		panic("Node cannot be nil")
-	}
-	p := g.newPlaceholder()
-	g.exprPlaceholder[node] = p
-	prepareTPWithPlaceholder(node, varAt, g, p)
-}
-
 func (g *typeGraph) addRoots(roots map[string]ast.Node, vars map[string]map[ast.Node]*common.Variable) {
 	for _, rootNode := range roots {
 		p := g.newPlaceholder()
@@ -104,6 +109,7 @@ func countRequiredParameters(params []ast.Parameter) int {
 	return count
 }
 
+// calcTP calculates a definition for a type placeholder.
 func calcTP(node ast.Node, varAt map[ast.Node]*common.Variable, g *typeGraph) typePlaceholder {
 	switch node := node.(type) {
 	case *ast.Array: