Skip to content

docs: cut comments in sandbox, tools, mcp, netguard, credential and secret - #695

Merged
ion-alpha-dev merged 7 commits into
mainfrom
docs/comments-sandbox-tools
Nov 15, 2026
Merged

ion-alpha-dev merged 7 commits into
mainfrom
docs/comments-sandbox-tools

Conversation

@ion-alpha-dev

Copy link
Copy Markdown
Collaborator

What

Shortens the comments in sandbox/, tools/, mcp/, netguard/, internal/credential/ and secret/, 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.txt were exemptions for them.

How to verify

Run ./dev/test ./sandbox/... ./tools/... ./mcp/... ./netguard/... ./internal/credential/... ./secret/... and go test ./internal/rigor/.... To confirm no code changed, strip comments from each changed file at the base and at the head, run both through go/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.go allowlist entry for these packages is dropped because the gate now passes without it. Windows token SIDs, status codes (0xC0000142), seccomp, openat2 and ACL facts are kept in full, so createWriteRestrictedToken and CleanStaleProfiles stay long. GOOS=linux go vet needs CGO_ENABLED=0 on a Windows host; Linux, Windows and macOS vet pass.

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

codecov Bot commented Nov 15, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 50.00000% with 1 line in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
mcp/client.go 0.00% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

@ion-alpha-dev
ion-alpha-dev merged commit 413afb9 into main Nov 15, 2026
33 of 34 checks passed
@ion-alpha-dev
ion-alpha-dev deleted the docs/comments-sandbox-tools branch November 15, 2026 09: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