Repository navigation
docs(memory): tighten and cut comments - #694
Merged
Merged
Conversation
Rewrite the comments in memory, learn, skill, internal/playbook, notices, inbox, watch and jobs so each says something the code does not. Comments that restated the code, retold history or hedged are deleted; the invariants, failure guards, ordering reasons, units and doc links stay. The diff is comment-only: the token stream of every changed file, comments excluded, matches the base commit. The comments in scope drop from 4215 lines to about 2150, and the matching lines leave the comment gate baseline. Signed-off-by: Ion Alpha <contact@ionalpha.io>
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
Restore the baseline file to its base version so the branch merges with main cleanly; the rewritten comments' entries are removed in the next commit, on top of main's copy. Signed-off-by: Ion Alpha <contact@ionalpha.io>
Remove the 31 baseline entries for memory, learn, skill, internal/playbook, notices, inbox, watch and jobs. Their comments no longer break the gate. Signed-off-by: Ion Alpha <contact@ionalpha.io>
Signed-off-by: Ion Alpha <contact@ionalpha.io>
Signed-off-by: Ion Alpha <contact@ionalpha.io>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Rewrites the comments in memory, learn, skill, internal/playbook, notices, inbox, watch and jobs (65 production files) so each says something the code does not. Comment lines in scope drop from 4215 to 2152. The 31 matching lines leave
internal/rigor/testdata/comment_baseline.txt.Why
Many comments restated the code, retold history or hedged, and the comment gate baseline still listed them. Doc comments are the published API reference, so shorter ones that give the invariant, the failure guarded against or the ordering reason are easier to read on pkg.go.dev.
How to verify
Run
./dev/check.go test ./internal/rigor/...fails if a baseline line is stale or a[Name]doc link does not resolve. The diff is comment-only: scanning each changed file at the base commit and at head, with comments excluded, gives the same token stream in all 65 files.Notes for reviewers
Every exported name keeps at least a one-line doc, because revive requires one. Test files and directives (
//go:,//nolint) are untouched. Lint caught three doc comments that began "Name, ..." instead of "Name ...", and those are fixed. gofumpt also reformatted layout inmemory/memory.go,skill/skillmd/skillmd.goandinbox/entry.go.