Skip to content

docs(cmd): tighten and cut comments - #692

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

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

Conversation

@ion-alpha-dev

Copy link
Copy Markdown
Collaborator

What

Shortens the comments in the root agent.go, approval/, session/ and the larger cmd/flynn files so each one states something the code does not, and deletes the comments that restated the code. Comment lines across these packages drop from 5148 to 4414. The comment baseline loses the 19 entries for the files fixed here.

Why

Doc comments are the published API reference, and restatement buries the invariants, failure modes and ordering reasons a reader needs. The comment gate also still carried baseline exemptions for banned words and over-long blocks in these files.

How to verify

Parsing each touched file at main and on this branch without comments and comparing the go/printer output gives identical results for all 32 Go files, so no code changed. go test ./internal/rigor/... passes with the reduced baseline, and putting a banned word back into cmd/flynn/tui.go makes it fail. ./dev/lint reports 0 issues, and ./dev/test . ./cmd/... ./session/... ./approval/... passes.

Notes for reviewers

Exported names keep a one-line doc, with wording that adds to the signature where there was something to add. About 60 smaller cmd/flynn files are untouched apart from targeted fixes for baseline entries; they can follow in a separate change.

Shorten the comments in the root agent.go, approval/, session/ and the
larger cmd/flynn files so each states what the code does not: the
invariant, the failure guarded against, or the reason for an order.
Comments that restated the code are deleted; exported names keep a
one-line doc.

The parsed code is unchanged: every touched file prints identically
with comments stripped. The comment baseline loses the entries for the
files fixed here.

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 7c471a2 into main Nov 15, 2026
34 checks passed
@ion-alpha-dev
ion-alpha-dev deleted the docs/comments-cmd-session branch November 15, 2026 08:44
@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