docs(protocol): drop restatement comments in tests#4591
Merged
Conversation
… items Strip a handful of restating comments inside test bodies that echo the next line of code (e.g., "Write file size", "Read it back", "Verify roundtrip", "Verify all data was written", "Read back", "Test with all three bytes", trailing "// Same time"/"// Same UID" tags). Upstream rsync citations, varint/MSG_*/multiplex-frame WHY notes, the multiplex::helpers SAFETY comment, and all rustdoc on public items are preserved unchanged. Files touched: 7. Lines removed: 16. Lines added: 0 (one restatement was collapsed into a one-line note about NDX delta state). No semantic changes; no new #[allow(...)] attributes; the crate already enforces #![deny(missing_docs)] so no additional rustdoc was required.
github-actions
Bot
added
the
documentation
This was referenced May 20, 2026
oferchen
added a commit
that referenced
this pull request
May 20, 2026
… items (#4596) Removes a small set of restatement comments in tests and SSH operand parsing where the line above already echoes the test name or the immediately following code (precedent: PRs #4587, #4589, #4590, #4591). Preserves every upstream-rsync cite (`// upstream: ...`) and every WHY note (SSH child process management, socketpair stderr, watchdog/drain thread invariants, `-oBatchMode=yes` injection rationale, IPv6 zone-id handling, secluded-args quoting). The crate already enforces `#![deny(missing_docs)]`, so all public items carry rustdoc; the only rustdoc edit converts two `///` headers on private test helpers (`create_test_handshake`, `create_test_parts`) into `//` comments, since rustdoc on private items adds no value without WHY content.
3 tasks
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary
Per-crate comment cleanup pass on the
protocolcrate, following the precedent set by PRs #4587 (matching), #4584 (filters), #4582 (logging), #4583 (platform), #4575 (compress).The
protocolcrate is already in a strong state:#![deny(missing_docs)]is in force at the crate root, so every public type/trait/function/method already carries///. Module-level doc comments cite upstreamio.c,flist.c,compat.c, and theMSG_*/ multiplex framing semantics where load-bearing. The single#[allow(unsafe_code)]inmultiplex::helpersand its SAFETY block are preserved verbatim.This follow-up strips a small set of pure restatement comments inside test bodies that simply echo the next line of code:
wire/vectored.rs- two "Verify all data was written" tags above aVec::new()setup.wire/compressed_token/lz4_codec.rs- three "Verify roundtrip" section labels above decoder construction.wire/compressed_token/zstd_codec.rs- two "Verify roundtrip" section labels.codec/mod.rs- "Write file size" / "Read it back" / "Write NDX values" / "Read them back" / "Mix wire and NDX operations" labels around codec round-trip tests. The substantive note about NDX deltas being stateful was kept (rewritten as a single line) because that is the actual reason a fresh codec is constructed on the reader side.flist/flags.rs- "Test with all three bytes" above an inline u32 literal that visibly contains three bytes.flist/write/tests/compression.rs- dropped two restating lines and three trailing// Same time/// Same UID/// Same GIDtags that duplicated the line content. The function-level upstream cite forXMIT_EXTENDED_FLAGS/end-marker collision is preserved at the top of the test.flist/write/tests/hardlink.rs- one "Read back" section label.Scope coverage
crates/protocol/src/end to end.fix/sender-xattr-user-prefix-namespacebranch (BR-3h):crates/protocol/src/xattr/cache.rscrates/protocol/src/xattr/prefix.rscrates/protocol/src/xattr/wire/tests.rscrates/protocol/src/flist/read/tests.rs// upstream: io.c:NNN/// upstream: flist.c:NNN/// upstream: compat.c:NNNcitations, varint/multiplex/version-negotiation WHY notes, INC_RECURSE segment-boundary explainers, and themultiplex::helpersSAFETY block are untouched.Files touched: 7. Comment lines removed: 16. Lines added: 0 (one restatement was rewritten as a one-line NDX-state note).
No semantic changes. No new
#[allow(...)]attributes. No rustdoc additions were necessary (the crate enforcesmissing_docs).Test plan
cargo fmt --all -- --checkcargo clippy --workspace --all-targets --all-features --no-deps -- -D warnings