Skip to content

docs: tighten and cut comments in the remaining packages - #696

Merged
ion-alpha-dev merged 1 commit into
mainfrom
docs/comments-remaining
Nov 15, 2026
Merged

ion-alpha-dev merged 1 commit into
mainfrom
docs/comments-remaining

Conversation

@ion-alpha-dev

Copy link
Copy Markdown
Collaborator

What

Rewrites the doc and inline comments in 142 production Go files across 56 packages that the earlier comment passes did not cover (controlplane, diag, capability, resource, the internal release, sigstore, selfupdate, vault and integration packages, and others). Comments that restated the code are deleted; every exported name keeps a one-line doc. Comment lines in the changed files go from 6263 to 4698.

Why

Doc comments are the published API reference. Many of these restated the signature or narrated how the code came to be, which buries the comments that carry an invariant, a failure being guarded against, an ordering reason, a security or concurrency contract, or a unit. What remains says something the code does not.

How to verify

The change is comment-only. For every changed .go file, the AST with comments stripped is identical to the same file on main; editing one token in a copy (maxConflictRetries in resource/retry.go) makes that comparison report a difference. No //go:, //nolint or build-constraint line is added, removed or changed.

go build ./..., ./dev/lint (0 issues) and go test ./internal/rigor/... pass locally, and ./dev/test passed on all 56 changed packages. TestCommentsStayTerse passes with 34 lines removed from internal/rigor/testdata/comment_baseline.txt and none added.

Notes for reviewers

The blocks still over 14 lines are package comments (limit 40), kept because they state the security or ordering contract for the whole package: internal/portregister, internal/release, internal/sigstore, internal/hostneutral, internal/projectctx and govbench.

The inertext.Escape doc now writes the bidirectional override as the text ‮ instead of the literal character, which gosec flags.

Rewrite doc and inline comments across the production packages not
covered by earlier passes. Comments that restated the code are
deleted; exported names keep a one-line doc. What remains states an
invariant, a failure guarded against, an ordering reason, a security
or concurrency contract, or a unit or range.

Comment-only: the AST of every changed file, with comments stripped,
is identical to the parent commit. Directives are unchanged. Lines
for comments that now pass are removed from the comment baseline.

Signed-off-by: Ion Alpha <contact@ionalpha.io>
@codecov

codecov Bot commented Nov 15, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@ion-alpha-dev
ion-alpha-dev merged commit fa423e2 into main Nov 15, 2026
34 checks passed
@ion-alpha-dev
ion-alpha-dev deleted the docs/comments-remaining branch November 15, 2026 10:00
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 15, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant