calc.go

@@ -33,10 +33,6 @@ func (n calcIdx) eval(operands []string) float64 {
 	return v
 }
 
-// eval on an unplaced name cannot happen: calcPrep runs indexVars over every
-// expression it compiles, so only a calcIdx reaches a render. It panics rather
-// than returning NaN, so a node kind indexVars forgets is a stack trace and not a
-// silently wrong number.
 func (n calcVar) eval([]string) float64 {
 	panic(internalError("calc operand %q was never placed", string(n)))
 }
@@ -58,9 +54,7 @@ func (n calcBin) eval(operands []string) float64 {
 }
 
 // checkCalc validates a calc token at compile time: a parseable expression whose
-// operands all name existing fields, and an optional non-negative integer dp. It
+// operands all name existing fields, and an optional non-negative integer dp.
-// is a builtin check (fields first), so calc dispatches through the registry like
-// every other {name(args)} function.
 func checkCalc(fields map[string]node, args []string) error {
 	if len(args) < 1 || len(args) > 2 {
 		return fmt.Errorf("calc takes an expression and an optional decimals count, got %d args", len(args))

cmd/fejkdata/main.go

@@ -234,7 +234,6 @@ var recordFormats = map[string]recordFormat{
 
 func jsonLine(r *fejkdata.Record, _ string) string { return r.JSON() }
 
-// writesRecords reports whether the format writes records rather than plain text.
 func (in invocation) writesRecords() bool {
 	return in.format != "text"
 }

data.go

@@ -106,7 +106,6 @@ type categoryFiles struct {
 	tsv map[string]bool
 }
 
-// readRows reads the rows file a category names beside it.
 func (c *categoryFiles) readRows(name string) (string, error) {
 	if _, present := c.tsv[name]; !present {
 		return "", fmt.Errorf("rows names %s, which is not beside it in %s", name, c.src.labelled(c.dir))

doc.go

@@ -32,7 +32,7 @@ package fejkdata
 //   - draw group — reference draws kept apart inside one render:
 //     `template.drawGroup` as the data spells it, `templateLink.drawGroupKey` as a
 //     render reads it, `renderDraws`, `groupDraws`, `renderScope`.
-//   - pin — fixing which row of a table the render uses, which the draw fences replay:
+//   - pin — fixing which row of a table the render uses, which the fences replay:
 //     `pinSet`, `pinSet.pin`, `table.drawIn`.
 //   - family — a table and every table reaching it through a chain of
 //     `table.parentT`, named by the root that chain ends at: `table.familyRoot`.
@@ -40,4 +40,4 @@ package fejkdata
 //     the `table` itself, so it draws a row apart from every pin: `branches.wholePins`.
 //   - fence — a load-time check, so rendering a compiled tree cannot fail: `New`
 //     runs them over the data set, `NewTemplate` and `FakeStruct` over what those
-//     compile. The draw fences are `heldCheck` and `drawFence`.
+//     compile.

format.go

@@ -386,8 +386,7 @@ func checkSegments(a arm) error {
 type callFn func(s *generatorState, emitted string, operands []string) string
 
 // op is one compiled unit of a format string: a literal run, a name read,
-// or a builtin already prepared with its args. compile builds these so render never
+// or a builtin already prepared with its args.
-// re-scans the format.
 type op struct {
 	formatToken
 	arms []arm // nameRead: the '|' alternatives, split into head and tail once

graph.go

@@ -193,9 +193,7 @@ func repeatCheck(path string, n node, mem renderCounts) error {
 // checkNoCycles rejects a reference cycle: a node whose rendering can reach itself
 // — directly, mutually, or through a chain — never terminates, so it must fail at
 // New rather than stack-overflow at render. It is a depth-first walk of the render
-// graph (renderEdges); grey marks nodes on the current path so a back-edge to one
+// graph (renderEdges). Every node is a root: a field its parent's format never renders is still reachable
-// is the cycle, while black lets a shared node (a DAG, not a cycle) be skipped.
-// Every node is a root: a field its parent's format never renders is still reachable
 // by dot path, so a cycle in one would otherwise reach render and be fatal there.
 func checkNoCycles(root map[string]node) error {
 	const (

node.go

@@ -10,8 +10,7 @@ import (
 )
 
 // node is a compiled element of the namespace tree: a folder, choice, null,
-// template, table, column or row. Compiling JSON into these once (see compile)
+// template, table, column or row.
-// means rendering never re-inspects the raw JSON.
 type node interface{ isNode() }
 
 // folder is a namespace of named children, built from a directory of JSON files
@@ -513,7 +512,6 @@ func weightOf(raw any) (float64, error) {
 // than where it would be unreachable.
 const reservedInName = ".|({}/[]\""
 
-// reservedList spells reservedInName for an error message, so the two cannot drift.
 var reservedList = strings.Join(strings.Split(reservedInName, ""), " ")
 
 // checkName rejects a name the dot path, {token} and JSON grammars cannot spell, or a struct

path.go

@@ -87,7 +87,6 @@ func indexOutside(s string, c byte) int {
 	return -1
 }
 
-// splitOutside splits s on c outside any [selector].
 func splitOutside(s string, c byte) []string {
 	var parts []string
 	for {

render.go

@@ -115,7 +115,6 @@ func pick(s *generatorState, c *choice) node {
 	return c.items[pickCum(s, c.cum)]
 }
 
-// expand renders a template's compiled ops.
 func expand(s *generatorState, t *template, sc renderScope) string {
 	var b strings.Builder
 	b.Grow(t.compiled.grow)

todo.md

@@ -40,14 +40,6 @@ maintainer chose on 2026-09-30 to go on with the path steps regardless.
 
 This round, in order:
 
-- Delete the comments the panel found restating their code or arranging the file:
-  `node`'s second sentence, `op`'s "compile builds these so render never re-scans the
-  format", `checkCalc`'s last sentence, `calcVar.eval`'s four lines, `checkNoCycles`'
-  grey and black, and the docs on `expand`, `readRows`, `splitOutside`, `reservedList`
-  and `writesRecords`.
-- Delete `doc.go`'s "The draw fences are …" sentence, which misses `checkDrawGroup`,
-  `checkOwnFamily` and `checkNestedDrawGroup`; the README's Layout indexes the fences by
-  file. Say "fences" in the `pin` entry then, which names the draw fences too.
 - Run the nine-seat panel again and file what it names here.
 
 ### Data