Answer prose round 1: true fixture and item 116 claims, plainer DrawIn, takeStep, Link and decision wording, and two comments deleted

CHANGELOG.md

@@ -13,7 +13,7 @@ replacement, and each removed path, column or flag.
   drawing afresh. `New` refuses a `..` naming anything but the parent table, and a
   selector after a `..`.
 - A path, given to `Fake` or the CLI or referenced in a template, may not read into a
-  level carrying a `repeat`, and `List` advertises none that does: where `x` carries
+  level carrying a `repeat`, and `List` advertises no such path: where `x` carries
   `"repeat": 3`, `Fake("x.a")` fails naming the level `x`, and `Fake("x")` renders it
   whole.
 - Every `{…}` draws afresh, and a name is the one way to keep a pick: `{p.a} {p.b}`,

README.md

@@ -796,7 +796,7 @@ token {p.postal-code}: not every variant of this 2-way choice carries "postal-co
 
 The sub-fields stay addressable — `Fake("address.place.locality")` renders, and
 `List` advertises it. A path may not read into a level carrying a `repeat`, and `List`
-advertises none that does; read that level whole.
+advertises no such path; read that level whole.
 
 ### Performance
 

doc.go

@@ -29,7 +29,7 @@ package fejkdata
 //     and the value each path read: `drawMemo`.
 //   - pin — fixing which row of a table one path, or one named pick, uses:
 //     `pinSet`, `namedPick.pins`, `table.drawStep`.
-//   - family — a table and every table reaching it through a chain of links
-//     `table.linkParent` makes.
+//   - family — a table and every table reaching it through a chain of parent
+//     links (`table.linkParent`).
 //   - fence — a load-time check, run over each category, template or struct as it
 //     loads or compiles, so rendering a compiled tree cannot fail.

docs/decisions.md

@@ -839,8 +839,8 @@ each value one writer would spread that knot across packages, behind forwarding
 every public method. The draw state, the grammar, `DataType`, what a proof knows of a
 value, the builtins, the reading of data files and a table's rows read no engine type, so
 each sits in a package under `internal/`, behind the import list `imports_test.go` checks.
-A table's rows reach the engine table owning them as their owner, a value of a type parameter. Valid
-until `todo.md` item 107 moves the engine.
+A rows table holds the engine table owning it as a value of a type parameter, so
+`internal/rows` imports no engine type. Valid until `todo.md` item 107 moves the engine.
 
 ## Goal 5.1's `{…}` covers `{{`, `}}` and a lone `}`, so the goal names no escape
 

fejkdata.go

@@ -113,8 +113,8 @@ func (c config) load() (folder, error) {
 }
 
 // List returns the sorted dotted paths Fake renders: each category and every field,
-// column and linked table below it, a direct descent at a time, stopping at a level
-// carrying a repeat. A choice consumes no segment, so a path continues through one
+// column and linked table below it, a direct descent at a time, listing a level
+// carrying a repeat but nothing below it. A choice consumes no segment, so a path continues through one
 // only where every variant carries it.
 func (f *Generator) List() []string {
 	f.mu.Lock()
@@ -126,8 +126,8 @@ func (f *Generator) List() []string {
 
 // paths lists the dot paths addressable from n, relative to it, where "" is n
 // itself. A folder has no value of its own, so it contributes only its children's.
-// intoRepeats lists the fields under a level carrying a repeat too, which a path
-// reaches only to be refused.
+// With intoRepeats, it also lists the paths below a level carrying a repeat, so a path
+// there meets the repeat's refusal.
 func paths(n node, intoRepeats bool) []string {
 	switch n := n.(type) {
 	case *folder:
@@ -163,7 +163,6 @@ func paths(n node, intoRepeats bool) []string {
 	}
 }
 
-// appendUnder appends each of ps to out under name.
 func appendUnder(out []string, name string, ps []string) []string {
 	for _, p := range ps {
 		out = append(out, join(name, p))

internal/grammar/path.go

@@ -139,7 +139,7 @@ func HasSelector(segs []string) bool {
 func SelectorOf(seg string) string { return seg[1 : len(seg)-1] }
 
 // inSelector is what a selector may not contain: the path grammar reserves brackets and
-// braces, and a quote or a bar would make the selector no path and no token arm.
+// braces, and inside a token a quote would end the path and a bar would split the token into arms.
 const inSelector = `[]{}"|`
 
 // UnspellableInSelector is the first character of s a selector cannot spell, "" where there is none.

internal/rows/pins.go

@@ -28,7 +28,7 @@ func (p *Pins[O]) Pinned(t *Table[O]) (int, bool) {
 	return r, ok
 }
 
-// MustRow is the row pinned for t, which the caller pinned.
+// MustRow is the row pinned for t; the caller must have pinned one.
 func (p *Pins[O]) MustRow(t *Table[O]) int {
 	r, ok := p.Pinned(t)
 	if !ok {

internal/rows/rows.go

@@ -141,7 +141,7 @@ func (t *Table[O]) appendRow(row string, line int) error {
 	return nil
 }
 
-// bindOptions resolves each option to its column, refuses a name reading the key column, and
+// bindOptions resolves each option to its column, refuses a name option naming the key column, and
 // proves what the options claim of the cells: a key is unique, a weight a positive number.
 func (t *Table[O]) bindOptions() error {
 	o := t.options
@@ -253,8 +253,8 @@ func (t *Table[O]) checkSelectorCells() error {
 }
 
 // Link links t to p, the table its link column names, after proving p has a key, every
-// link cell is one, and every row of p is linked to. sibling is the table beside t
-// named name, nil where none is. It is the only writer of a table's parent and children.
+// link cell is one, and every row of p is linked to. sibling returns the table beside t
+// named name, or nil. Link is the only writer of a table's parent and children.
 // docs/decisions.md#a-parent-row-with-no-child-row-is-a-load-error
 func (t *Table[O]) Link(p *Table[O], sibling func(name string) *Table[O]) error {
 	name := t.header[t.parentIndex]
@@ -307,7 +307,7 @@ func (t *Table[O]) checkAncestors(p *Table[O], sibling func(name string) *Table[
 	return nil
 }
 
-// Children is the tables linked to t, by segment.
+// Children is the tables linked to t, sorted by segment.
 func (t *Table[O]) Children() []*Table[O] {
 	out := make([]*Table[O], 0, len(t.children))
 	for _, c := range t.children {
@@ -411,9 +411,9 @@ func (t *Table[O]) drawUnder(s *drawstate.State, pr int) int {
 	return rows[s.Weighted(lookup.childCum[k])]
 }
 
-// DrawIn is the row of t inside the rows p pins: the one pinned in p, else one drawn inside the nearest
-// pinned ancestor — its parent drawn inside that first where the ancestor is further up — or
-// over the whole table, and pinned with its ancestors.
+// DrawIn returns the row of t that p pins. Where p pins none, it draws one inside the nearest
+// ancestor p pins, drawing t's parent there first when that ancestor is higher up; with no
+// ancestor pinned, it draws over the whole table. It pins the row drawn and its ancestors' rows in p.
 func (t *Table[O]) DrawIn(s *drawstate.State, p *Pins[O]) int {
 	if r, ok := p.Pinned(t); ok {
 		return r

internal/rows/rows_test.go

@@ -16,7 +16,7 @@ func parse(t *testing.T, segment, data string, o Options) *Table[string] {
 	return tb
 }
 
-// family is a country table with two cities linked to it, each with a name only unique inside its country.
+// family is a country table, SE and NO, and a city table linked to it, where Borg names a city in each country.
 func family(t *testing.T) (country, city *Table[string]) {
 	t.Helper()
 	country = parse(t, "country", "code\tname\nSE\tSweden\nNO\tNorway\n", Options{Key: "code"})

path.go

@@ -146,8 +146,8 @@ func repeatLevelError(level string) error {
 	return fmt.Errorf("the level %q carries a repeat, so a path cannot read one draw of it; read %q whole", level, level)
 }
 
-// pathPos is where a walk stands: the node reached, the tail left to walk from it, and whether
-// it descended there, as route reads it.
+// pathPos is where a walk stands: the node reached, the tail left to walk from it, and route's
+// descended flag for it.
 type pathPos struct {
 	n         node
 	tail      []string
@@ -156,9 +156,9 @@ type pathPos struct {
 
 func (p pathPos) more() bool { return len(p.tail) > 0 || p.descended }
 
-// takeStep moves at past the step its tail starts with, from its node, which is no choice, and
-// appends what it takes to steps: a field, or the route a table passes. whole is the full path,
-// at.tail its unwalked end, and level names its head in errors.
+// takeStep takes the first step of at.tail from at.n, which must not be a choice, moves at past
+// it, and appends the step to steps: a field, or the route through a table. whole is the full
+// path; level is the prefix an error puts before it.
 func takeStep(at *pathPos, whole []string, level string, steps []pathStep, pins *pinSet) ([]pathStep, error) {
 	i := len(whole) - len(at.tail)
 	switch x := at.n.(type) {

path_test.go

@@ -62,7 +62,6 @@ func TestDescendIntoStringErrors(t *testing.T) {
 	}
 }
 
-// TestPathRefusesALevelCarryingARepeat holds a caller's path to the rule a reference obeys.
 func TestPathRefusesALevelCarryingARepeat(t *testing.T) {
 	dir := writeData(t, map[string]string{
 		"outer": `{"format":"{inner}","inner":{"format":"{a}","a":"v","repeat":3,"separator":","}}`,

todo.md

@@ -464,7 +464,7 @@ Its doc says render failure, and it wraps what `NewTemplate` and `NewRecordTempl
 
 ### 116. Turn a row index into its rows file's line in one function.
 
-Today `namedNode`'s cell line in `graph.go` and each site in `internal/rows` add the header line and the one-based count.
+Today `namedNode`'s cell line in `graph.go`, `table.checkCells` and each site in `internal/rows` add the header line and the one-based count.
 
 ### 56. Build on a manual run of `test.yml`.