calc.go

@@ -11,8 +11,8 @@ import (
 	"github.com/larvit/fejkdata/internal/invariant"
 )
 
-// checkCalcFields checks each calc operand a field holds; an operand no field holds is a name,
-// which checkCalcNames checks once names resolve.
+// checkCalcFields runs checkOperands over each calc operand naming a field; an operand naming no
+// field is a name, which checkCalcNames checks once names resolve.
 func checkCalcFields(args []string, fields map[string]node) error {
 	return checkOperands(args[0], builtinfunc.ParsedCalc(args[0]), func(name string) []node {
 		if n, ok := fields[name]; ok {

data-import/geo-se.py

@@ -135,8 +135,9 @@ class Nearest:
 
 
 def street_delivery(name, codes):
-    """The codes delivered to a street: the digit after the postort's own prefix is 0 or 1 for boxes and 8 for reply mail
-    outside ONE_POSITION's cities, per docs/research/research-geo-se.md, Postal codes → Structure."""
+    """The codes delivered to a street. Outside ONE_POSITION's cities, the digit after the postort's own prefix is 0 or 1
+    for boxes and 8 for reply mail; inside them, a second digit 0 marks boxes.
+    Per docs/research/research-geo-se.md, Postal codes → Structure."""
     if name in ONE_POSITION:
         return [c for c in codes if c[1] != "0"]
     largest = collections.Counter(c[:3] for c in codes).most_common(1)[0][1]

inline.go

@@ -18,7 +18,7 @@ type Template struct {
 	n node
 }
 
-// Fake renders the template once, each {…} drawn afresh.
+// Fake renders the template once; each call draws anew.
 func (t *Template) Fake() string {
 	t.g.mu.Lock()
 	defer t.g.mu.Unlock()

namefence.go

@@ -65,7 +65,8 @@ func rendersInside(nodes []node, t *template) bool {
 // refuseSingleRead refuses b when its one read sits in b's own scope, not in a repeat nested inside
 // it, at a spot where the bound spelling could stand. That spelling draws the same without the
 // name: write {/word} for {/word as w}{w}. A bound field can stand in only where the reading
-// template reaches the binder through fields. A calc operand cannot read a reference or a path.
+// template reaches the binder through fields. A single read as a calc operand stands where a calc
+// could not read the spelling, a reference or a path.
 // Where the spelling would be a whole CLI argument or a whole struct tag, that entry point refuses
 // it and names the bare path.
 func (b *nameBinding) refuseSingleRead(uses []nameUse) error {
@@ -121,10 +122,10 @@ func calcReads(spelling string) bool {
 	return err == nil && isVar && v.Name == spelling
 }
 
-// refuseTwiceDrawn refuses read, a read of a name landing on n at key under the name's pick, where n
-// renders a field twice and another read of the name addresses that field: the pick keeps one draw
-// of the field, so beside {n} for a category {w}-{w}, {n.w} cannot say which draw it reads.
-// addressed maps each level a read of the name addresses to that read.
+// refuseTwiceDrawn refuses read, a read of a name that lands on n, where n renders a field twice and
+// another read of the name addresses that field. The pick keeps one draw of the field: where n binds
+// a category whose format is {w}-{w}, a {n.w} beside {n} cannot say which draw it reads. key is n's
+// level under the pick; addressed maps each level a read of the name addresses to that read.
 func refuseTwiceDrawn(addressed map[pickKey]string, read string, n node, key pickKey) error {
 	switch n := n.(type) {
 	case *choice:

reference.go

@@ -7,14 +7,14 @@ import (
 	"github.com/larvit/fejkdata/internal/grammar"
 )
 
-// resolvedRef is what a reference resolves to: the head its category is held under, a "/"
-// and then the category's path from the root, and the tail read into it.
+// resolvedRef is what a reference resolves to. head is "/" and the category's path from the root,
+// the key the category is held under; tail is the path read into the category.
 type resolvedRef struct {
 	head string
 	tail []string
 }
 
-// categoryOf is the category path a resolvedRef's head names: the head without its "/".
+// categoryOf is the category path a resolvedRef's head names.
 func categoryOf(head string) string { return strings.TrimPrefix(head, "/") }
 
 // refSegments resolves a reference written in folder to a path from the root.