docs(go): finish per-file doc-comment migration for config, cmdutil, mcp — last three packages-and-layout rows #17

New issue

Closed

opened 2026-07-11 21:39:39 +00:00 by hexajon · 0 comments

hexajon commented

2026-07-11 21:39:39 +00:00

(Migrated from codeberg.org)

Remaining rows to migrate then delete:

internal/config — add per-file comments to config.go (core loading, cache), credentials.go (secure backends), user.go (FetchUser, identity), git.go (DetectRepo, branch helpers), storage.go (TokenStore), keychain.go, pass.go, systemd_creds.go, version.go. scheme.go already has one.
internal/cmdutil — output.go (OutputStruct, OutputItem, OutputPaginatedList, PrintMessage), flags.go (ListFlags), bodypatch.go/bodyverbs.go (anchored body-edit spine). services.go already has one.
internal/mcp — server.go (NewServer, Run), context.go (DetectContext), register.go, tools.go and the per-resource tools_*.go registration files; many other mcp files already carry the per-file style.

Accuracy requirement (learned in an earlier verify pass, where two freshly written comments mis-stated file roles): each comment must be written from READING the file's actual declarations, never from the table row alone — the rows are hints, the code is the source of truth. Note Go concatenates multiple package doc comments in filename order in go doc output, so each per-file comment must read sensibly in a concatenated stream (the existing // Package X — <file> ... prefix convention handles this).

Acceptance:

Every file listed above carries an accurate // Package <pkg> — <file> ... comment.
The remaining 3-row table and the follow-up note in docs/architecture/packages-and-layout.md are deleted; the doc keeps only cross-package content.
gofmt/vet/gate green; go doc output for each package reads coherently.
Add the second half of the doc-drift enforcement (companion to TestEveryInternalPackageHasDocComment in internal/parity, added in an earlier change): a guard asserting docs/architecture/packages-and-layout.md contains no per-package key-file rows (no line matching | \internal/`) — so a hand-rolled markdown package map can never creep back once this table is gone.

Follow-up to an earlier issue. The packages-and-layout.md per-package table was migrated into Go doc comments for all packages except three whose house style is per-FILE package comments (`// Package config — <file> does ...`): most of their files today carry a bare `package` clause, so deleting their table rows would lose the file map. Remaining rows to migrate then delete: - `internal/config` — add per-file comments to config.go (core loading, cache), credentials.go (secure backends), user.go (FetchUser, identity), git.go (DetectRepo, branch helpers), storage.go (TokenStore), keychain.go, pass.go, systemd_creds.go, version.go. scheme.go already has one. - `internal/cmdutil` — output.go (OutputStruct, OutputItem, OutputPaginatedList, PrintMessage), flags.go (ListFlags), bodypatch.go/bodyverbs.go (anchored body-edit spine). services.go already has one. - `internal/mcp` — server.go (NewServer, Run), context.go (DetectContext), register.go, tools.go and the per-resource tools_*.go registration files; many other mcp files already carry the per-file style. Accuracy requirement (learned in an earlier verify pass, where two freshly written comments mis-stated file roles): each comment must be written from READING the file's actual declarations, never from the table row alone — the rows are hints, the code is the source of truth. Note Go concatenates multiple package doc comments in filename order in `go doc` output, so each per-file comment must read sensibly in a concatenated stream (the existing `// Package X — <file> ...` prefix convention handles this). Acceptance: - Every file listed above carries an accurate `// Package <pkg> — <file> ...` comment. - The remaining 3-row table and the follow-up note in docs/architecture/packages-and-layout.md are deleted; the doc keeps only cross-package content. - gofmt/vet/gate green; `go doc` output for each package reads coherently. - Add the second half of the doc-drift enforcement (companion to `TestEveryInternalPackageHasDocComment` in internal/parity, added in an earlier change): a guard asserting docs/architecture/packages-and-layout.md contains no per-package key-file rows (no line matching `| \`internal/`) — so a hand-rolled markdown package map can never creep back once this table is gone.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#17

No description provided.

Rows
Columns