Make great documentation goal 1.2, and plan the README's reorganisation and the nested-template gaps #33

Open
lilleman wants to merge 966 commits from worktree-todo-relative-dates-exact-counts into main
4 changed files with 10 additions and 9 deletions
Showing only changes of commit 48495944fa - Show all commits
+1 -1
View File
@@ -1,4 +1,4 @@
# The merge gate: `docker build .` fails if vet, formatting or tests fail, and CI # The merge gate: `docker build .` fails if vet, complexity, formatting or tests fail, and CI
# runs exactly this. Day-to-day, prefer `docker compose run` (bind-mounts source, # runs exactly this. Day-to-day, prefer `docker compose run` (bind-mounts source,
# no rebuilds). GO_VERSION defaults to the latest stable Go; the lowest supported # no rebuilds). GO_VERSION defaults to the latest stable Go; the lowest supported
# version builds the `portable` stage, which every supported Go must pass: # version builds the `portable` stage, which every supported Go must pass:
+1 -4
View File
@@ -8,10 +8,7 @@ import (
// heldCheck rejects every route to a held sibling name except the ones that read its // heldCheck rejects every route to a held sibling name except the ones that read its
// draw. An expansion holds one draw of that name; anything else that renders it draws // draw. An expansion holds one draw of that name; anything else that renders it draws
// again, and the two disagree. checkNoOverlap settles the spellings within one format // again, and the two disagree.
// (a token, an operand); this settles the rest — a reference, whether it sits in that
// format or in anything the format renders, however deep. A reference path is held
// for the whole render instead, which drawCheck fences.
func heldCheck(path string, n node) error { func heldCheck(path string, n node) error {
t, ok := n.(*template) t, ok := n.(*template)
if !ok || len(t.held) == 0 { if !ok || len(t.held) == 0 {
-1
View File
@@ -194,7 +194,6 @@ func TestReadmeTableExample(t *testing.T) {
} }
} }
// TestLayoutNamesEverySourceFile holds an added, renamed or split file to its Layout line.
func TestLayoutNamesEverySourceFile(t *testing.T) { func TestLayoutNamesEverySourceFile(t *testing.T) {
src := readme(t) src := readme(t)
i := strings.Index(src, "## Layout") i := strings.Index(src, "## Layout")
+8 -3
View File
@@ -30,8 +30,8 @@ This round, in order:
`drawVisit` and `drawRoute` no longer tell each other apart. `drawVisit` and `drawRoute` no longer tell each other apart.
- Spell one fresh draw set one way: `newDrawSet` exists, and `render.go` and `draw.go` - Spell one fresh draw set one way: `newDrawSet` exists, and `render.go` and `draw.go`
hand-roll `drawSet{unnamed: draws{s: s}}` at three sites; name the lazy-map variant hand-roll `drawSet{unnamed: draws{s: s}}` at three sites; name the lazy-map variant
if the difference is deliberate, and say whether `draw.go`, 57 lines after the split, if the difference is deliberate, and put the draw set in one file: `draw.go` holds 57
still earns a file of its own. lines after the split, and `render.go` two of the three sites.
- Run the package doc's Go example under test, as `readme_test.go` runs the README's - Run the package doc's Go example under test, as `readme_test.go` runs the README's
JSON blocks: `doc.go` and the README both print `Järvedsvägen 43\n891 77 Järved` JSON blocks: `doc.go` and the README both print `Järvedsvägen 43\n891 77 Järved`
for seed 42, and nothing renders either, so a draw that moves leaves both false. for seed 42, and nothing renders either, so a draw that moves leaves both false.
@@ -269,7 +269,12 @@ because pairing a street with its exact postnummer rewrites shipped rows.
- Name the draw fences at one level in `doc.go`: the Vocabulary calls them `heldCheck`, - Name the draw fences at one level in `doc.go`: the Vocabulary calls them `heldCheck`,
`drawCheck` and `checkFamilies`, where `checkFamilies` runs under `drawCheck` beside `drawCheck` and `checkFamilies`, where `checkFamilies` runs under `drawCheck` beside
`checkOwnFamily` and `checkColumnDraws`, which it names nowhere — so a reader looking `checkOwnFamily` and `checkColumnDraws`, which it names nowhere — so a reader looking
for the fence over a record's columns finds no entry reaching it. for the fence over a record's columns finds no entry reaching it. `holdfence.go` and
`drawfence.go` now index the fences by file, so deleting the sentence closes it too.
- Cut `AGENTS.md` to the rules only it states: the round procedure stands word for word
in `todo.md` and the `gh` rule opens with the README's GitHub decision, so each is a
second copy that drifts. Split the comprehension rule while there, which packs the
gate, its exceptions, the round and the at-or-above-7.0 regime into one line.
- Scope `AGENTS.md`'s `Hard tabs.` to the Go source, or drop it: `gofmt` already gates - Scope `AGENTS.md`'s `Hard tabs.` to the Go source, or drop it: `gofmt` already gates
Go at `Dockerfile:21`, and the shipped JSON under `data/` is two-space, so the rule as Go at `Dockerfile:21`, and the shipped JSON under `data/` is two-space, so the rule as
written is one no Go file can break and every data file does. written is one no Go file can break and every data file does.