From 2a6d1df1bf8c75cb727bb226b8b8a7523f6e179c Mon Sep 17 00:00:00 2001
From: Lilleman auf Larv <lilleman@larvit.se>
Date: Mon, 21 Sep 2026 10:27:04 +0200
Subject: [PATCH] Keep the vocabulary out of the page a consumer lands on

---
 README.md   |  7 +++++++
 doc.go      |  8 +++++---
 doc_test.go | 11 +++++------
 3 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 08132e0..f6590d4 100644
--- a/README.md
+++ b/README.md
@@ -861,6 +861,13 @@ the Development section below, and who ships a register the four above then draw
   a personal instance. Valid while the project wants contribution from outside: the
   workflow decided nothing, being portable already — `github.api_url` and
   `secrets.GITHUB_TOKEN` resolve on either host, so only the names moved.
+- **The vocabulary sits below `doc.go`'s package clause, not in the package doc.**
+  Goal 1 is what a developer choosing a library reads first, and the package doc is
+  that page: a glossary of unexported units would fill two thirds of it with names
+  no consumer can call, and Go doc comments have no code markup, so each one would
+  render its backticks literally. Below the clause it reaches goal 2's reader — who
+  opens the file — and nothing else. Valid while the glossary names units a consumer
+  cannot reach; one that came to name the exported API would belong above the clause.
 - **Options and fields share one namespace.** `format`, `weight`, `repeat`,
   `separator`, `datatype` and `drawGroup` are reserved; every other key is a field. Nesting fields under a
   key, or prefixing options, would tax every template to guard against a
diff --git a/doc.go b/doc.go
index 667b40c..691ca0f 100644
--- a/doc.go
+++ b/doc.go
@@ -9,9 +9,12 @@
 //	f.Fake("sv_SE.address.locality") // "Sundbyberg": a second call draws afresh
 //
 // Several sources merge in order, the last winning a name clash, so custom data
-// layers over the built-ins. The JSON template format is documented in the README.
+// layers over the built-ins. The JSON template format is documented in the [README].
 //
-// # Vocabulary
+// [README]: https://github.com/larvit/fejkdata#readme
+package fejkdata
+
+// Vocabulary
 //
 // The words the rest of the package uses, and the unit that owns each:
 //
@@ -41,4 +44,3 @@
 //     expansion's held names, `drawCheck` over a render's reference paths, and
 //     `checkFamilies` over the rows they pin. `New` runs them over the data set,
 //     `NewTemplate` and `FakeStruct` over what those compile.
-package fejkdata
diff --git a/doc_test.go b/doc_test.go
index 56124f1..e544a37 100644
--- a/doc_test.go
+++ b/doc_test.go
@@ -47,14 +47,13 @@ func sourceFiles(t *testing.T) []*ast.File {
 func vocabulary(t *testing.T, files []*ast.File) string {
 	t.Helper()
 	for _, f := range files {
-		if f.Doc == nil {
-			continue
-		}
-		if _, section, found := strings.Cut(f.Doc.Text(), "\n# Vocabulary\n"); found {
-			return section
+		for _, c := range f.Comments {
+			if section, found := strings.CutPrefix(c.Text(), "Vocabulary\n"); found {
+				return section
+			}
 		}
 	}
-	t.Fatal("no package doc carries a Vocabulary heading, so fence, hold, pin and the rest are defined nowhere a reader of the code meets them")
+	t.Fatal("no comment opens with a Vocabulary heading, so fence, hold, pin and the rest are defined nowhere a reader of the code meets them")
 	return ""
 }