format.go

@@ -375,19 +375,17 @@ type op struct {
 	operands []arm
 }
 
-// formatOps is a compiled format: its ops, the size of its literal text (to size
+// formatOps is a compiled format: its ops, the size of its literal text, and the
-// the render buffer), and the names drawn once per expansion. pathKeys maps each key
+// names it holds. pathKeys maps each key a path starts from to the first such path;
-// a path starts from to the first such path; held is every such key plus the
+// held is every such key plus the fields an operand reads; holder maps each held
-// fields an operand reads; holder maps each held name to the first reader holding
+// name to the first reader holding it, for error messages.
-// it, for error messages. The maps are nil when the format holds nothing, so data
-// that holds nothing carries no render-time cost.
 type formatOps struct {
 	ops       []op
 	grow      int
 	pathKeys  map[string]string
 	held      map[string]bool
 	holder    map[string]string
-	heldLocal bool // some held name is kept by the expansion itself rather than the render's hold
+	heldLocal bool // some held name is not a reference path, so expand makes a hold
 }
 
 func (c *formatOps) holdName(a arm, label string) {

hold.go

@@ -24,10 +24,10 @@ type readValue struct {
 }
 
 // readField renders one arm of a token. A name the expansion holds — a level some
-// token addresses by dotted path, or a field an operand reads — is drawn once and
+// token addresses by a dotted path that is not a reference, or a field an operand
-// kept in held, so {place.postal-code} and {place.locality} read one row, either read
+// reads — is drawn once and kept in held, so {place.postal-code} and {place.locality}
-// twice gives one value, and a shown operand is the operand computed. Every other name
+// read one row, either read twice gives one value, and a shown operand is the operand
-// is drawn afresh, so {word} {word} still draws twice.
+// computed. Every other name is drawn afresh, so {word} {word} still draws twice.
 func readField(s *session, t *template, held *hold, sc renderScope, a arm) readValue {
 	if isRef(a.key) && len(a.tail) > 0 {
 		return readReference(s, t, sc, a)