docs(rsync_io): drop restatement comments, apply rustdoc to public items#4596
Merged
Conversation
… items 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.
github-actions
Bot
added
the
documentation
4 tasks
oferchen
added a commit
that referenced
this pull request
May 21, 2026
… items (#4648) Follow-up to PR #4596 that scrubs three remaining restatement comments the previous pass missed: - `negotiation/buffer/storage.rs`: two test comments that simply repeated the assertion immediately below them (`// prefix_len should be clamped to buffer length (3)` directly above `assert_eq!(.., 3)`). - `ssh/embedded/auth.rs::effective_username_none_no_env`: the leading comment claimed the test "temporarily clears the env var" but the body immediately explains that doing so is unsafe in a multi-threaded test and the env var is therefore left alone - drop the contradiction and tighten the surviving WHY comment. - `ssh/embedded/auth.rs::auth_methods_ordering`: the lone comment restated the test name. Preserves every upstream-rsync cite (`io.c read_int`/`write_int`, `pipe.c:54-55`, `main.c:620-624`), the SEC-3 leading-dash rejection rationale in `ssh/operand.rs`, the `SshChildHandle` drop/reap zombie prevention notes, the socketpair vs anonymous-pipe fallback rationale, and all watchdog / drain thread invariants.
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
parsing where the line above already echoed the test name or the
immediately following code (precedent: PRs docs(matching): drop restatement comments in optimized_search tests #4587, docs(fast_io): drop restatement comments, apply rustdoc to public items #4589, docs(transfer): drop restatement comments, tighten test annotations #4590, docs(protocol): drop restatement comments in tests #4591).
extract_userIPv6/@rationale comment inssh/operand.rsto explain why the[-before-@ordering matters(zone-id ambiguity), and flattens the redundant nested
else { if ... }into
else if ....///rustdoc headers on private test helpers(
create_test_handshake,create_test_parts) to//comments, sincerustdoc on private items adds no value without WHY content.
// upstream: pipe.c:...,// upstream: io.c read_int/write_int) and every WHY note (SSH childprocess management, socketpair stderr, watchdog/drain thread
invariants,
-oBatchMode=yesinjection rationale, secluded-argsquoting, RFC 5737 unroutable address choice).
Scope
rsync_ioalready enforces#![deny(missing_docs)], so the public APIdocumentation coverage is complete by construction; the comment hygiene
across the crate is already in good shape (97 source files, ~4k
//lines, almost all carrying WHY content - FFI invariants, kernel quirks,
upstream-rsync references, fallback rationale). The targeted cleanup
landed in 9 files for a net -14 lines.
Test plan
cargo fmt --all -- --checkcargo clippy --workspace --all-targets --all-features --no-deps -- -D warningscargo nextest run -p rsync_io --all-features(971 passed)