Repository navigation
docs: cut comments in sandbox, tools, mcp, netguard, credential and secret - #695
Merged
Merged
Conversation
Shorten doc and inline comments in sandbox/, tools/, mcp/, netguard/, internal/credential/ and secret/ so each says something the code does not, and delete comments that restate it. Measured platform facts (status codes, SIDs, sysctls, errnos) are kept. The comment baseline loses every entry for these packages, and the long-comment allowlist entry for createWriteRestrictedToken is removed because that comment is now under the threshold. No code changes: gofmt realigned struct fields where a comment line between them was deleted. Signed-off-by: Ion Alpha <contact@ionalpha.io>
The comment on createWriteRestrictedToken is now 14 lines, below the long-comment threshold, and the test fails on an allowlist entry that no longer matches a long block. Signed-off-by: Ion Alpha <contact@ionalpha.io>
Shorten the doc and inline comments on the stream, capture, session, egress, forward, readiness, scratch and containment code to the invariant or reason each one records. Measured platform facts stay: the SIGSYS wait-status read, ENETUNREACH on a direct dial, the tmpfs mounts over /tmp and /dev/shm, and the SCM_RIGHTS handoff. The captureExec doc comment sat above runCounted; it moves to the function it describes. No code changes. Signed-off-by: Ion Alpha <contact@ionalpha.io>
Shorten the doc and inline comments in the per-platform confinement, read-deny, network-deny, seccomp, microVM, remote and grant code. Measured facts stay: syscall table gaps, seccomp_data offsets, openat2 behaviour, Windows SIDs and access-entry semantics. Comments that restated the code are deleted. No code changes. Signed-off-by: Ion Alpha <contact@ionalpha.io>
ReviewThread and New lost their one-line docs in the comment cut, which revive reports as missing exported comments. Put them back. Signed-off-by: Ion Alpha <contact@ionalpha.io>
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
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
Shortens the comments in
sandbox/,tools/,mcp/,netguard/,internal/credential/andsecret/, about 4400 comment lines down to about 2270. Comments that restated the code are deleted; the rest keep the invariant, the failure guarded against, or the measured platform fact. The diff is comment-only.Why
Doc comments are the published API reference, and AGENTS.md asks for comments that say why and not what. These packages carried long restating blocks, repeated arguments and history, and 16 lines of
internal/rigor/testdata/comment_baseline.txtwere exemptions for them.How to verify
Run
./dev/test ./sandbox/... ./tools/... ./mcp/... ./netguard/... ./internal/credential/... ./secret/...andgo test ./internal/rigor/.... To confirm no code changed, strip comments from each changed file at the base and at the head, run both throughgo/printer, and compare: all 93 changed files are identical, and a deliberate code edit and a changed//go:directive are both caught by the same check.Notes for reviewers
All 16 baseline lines for these packages are removed, none added. The
commentlen_test.goallowlist entry for these packages is dropped because the gate now passes without it. Windows token SIDs, status codes (0xC0000142), seccomp,openat2and ACL facts are kept in full, socreateWriteRestrictedTokenandCleanStaleProfilesstay long.GOOS=linux go vetneedsCGO_ENABLED=0on a Windows host; Linux, Windows and macOS vet pass.