Skip to content

docs: tighten comments in the model and inference packages - #693

Merged
ion-alpha-dev merged 2 commits into
mainfrom
docs/comments-models-inference
Nov 15, 2026
Merged

ion-alpha-dev merged 2 commits into
mainfrom
docs/comments-models-inference

Conversation

@ion-alpha-dev

Copy link
Copy Markdown
Collaborator

What

This rewrites the comments in externagent, internal/inference, llm, localmodel, provider, internal/catalog, internal/huggingface, internal/hardware, usage and internal/gbnf so each one says something the code does not. Comment lines in these packages fall from 4,681 to 3,405. Sixteen lines leave internal/rigor/testdata/comment_baseline.txt because the comments they excused are fixed.

Why

Many comments restated the code, made the same argument twice, or told the history of a change. Every comment left states an invariant, the failure a line guards against, an ordering reason, a unit or range, or a security or concurrency contract. Doc links that resolve are kept.

How to verify

The diff is comments only. Each changed file was parsed with go/parser at the base commit and at the head, comments were stripped, and the go/printer output was compared: all 70 Go files are byte-identical. go build ./..., go vet and ./dev/test on the ten packages pass, as do go test ./internal/rigor/... and ./dev/lint. Adding a banned word back into a rewritten gbnf comment makes TestCommentsStayTerse fail on that line.

Notes for reviewers

Struct field docs and in-function comments that follow code were shortened rather than deleted. Deleting them would realign field columns or drop a blank line, which changes the printed code. The localmodel package doc stays at 40 lines, the package-comment limit, because it documents the trust model and the runtime and weights lifecycle that the rest of the package relies on.

Rewrite the comments in externagent, internal/inference, llm,
localmodel, provider, internal/catalog, internal/huggingface,
internal/hardware, usage and internal/gbnf. Each comment now states an
invariant, a failure it guards against, an ordering reason, a unit, or
a security or concurrency contract. Comments that restated the code,
repeated an argument, or told the history of a change are removed or
cut to the one line revive requires on an exported name.

The change touches comments only: every file parses and prints
identically to its previous version with comments stripped.

Sixteen lines leave comment_baseline.txt because the comments they
excused are fixed.

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 96e5dd9 into main Nov 15, 2026
34 checks passed
@ion-alpha-dev
ion-alpha-dev deleted the docs/comments-models-inference branch November 15, 2026 09:05
@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