Skip to content

docs: tighten and cut comments in core packages - #697

Merged
ion-alpha-dev merged 7 commits into
mainfrom
docs/comments-tui-chain-state
Nov 15, 2026
Merged

ion-alpha-dev merged 7 commits into
mainfrom
docs/comments-tui-chain-state

Conversation

@ion-alpha-dev

Copy link
Copy Markdown
Collaborator

What

Rewrites the comments in internal/tui, chain, extension, state, storage, runtime, spine, bus, instance, orchestration and observe. Comments that restated the code or told its history are removed; the rest are shorter and keep only what the code cannot say: invariants, failure guards, ordering reasons, units and ranges, security and concurrency contracts, and wire-contract statements. Exported names keep a one-line doc, and every contract statement in state and extension is kept. Production .go files only; no code changes.

Why

The comment gate added in the last few PRs fixes the rules but leaves a large body of older comments that narrate the code. Shorter comments are easier to keep true, and the published API reference reads as a contract instead of a walkthrough. This also removes the baseline entries for violations that no longer exist.

How to verify

go test ./internal/rigor/... passes, including TestCommentsStayTerse with the smaller baseline, and ./dev/lint reports 0 issues. A scanner-level comparison of each changed file against its pre-change version (tokens with comments skipped, plus directive comments such as //go:embed and //nolint) shows all 105 files identical, so only comments differ.

Notes for reviewers

Comment lines in these packages go from 5804 to 3326. The baseline loses 21 lines. Two entries stay because they are not fixed here: chain/conformance/crypto.go still has one over-long block.

Shorten comments in internal/tui, chain, extension, state, storage, runtime, spine, bus, instance, orchestration and observe. Each remaining comment states an invariant, a failure it guards against, an ordering reason, a unit or range, or a wire contract; comments that restated the code or told its history are removed. Exported names keep a one-line doc.

The change touches comments only: the non-comment token stream and the directive comments of every changed file are identical to main.

Removes the baseline entries for the comment violations that no longer exist.

Signed-off-by: Ion Alpha <contact@ionalpha.io>
Signed-off-by: Ion Alpha <contact@ionalpha.io>
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 d96b568 into main Nov 15, 2026
60 of 62 checks passed
@ion-alpha-dev
ion-alpha-dev deleted the docs/comments-tui-chain-state branch November 15, 2026 10: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