docs(transfer): drop restatement comments, tighten test annotations#4590
Merged
Conversation
Sweep the transfer crate to remove echo-the-code comments, decorative
section dividers, and a handful of redundant explanatory notes in tests,
while preserving every upstream-rsync citation, WHY note, and the
existing rustdoc on public items.
Scope: top-level transfer crate sources only. Per-crate cap:
- top-level: lib.rs (no-op), constants.rs, error.rs, flags.rs,
role.rs, failed_directories.rs, temp_guard.rs, temp_cleanup.rs,
compressed_writer.rs, parallel_io.rs
- submodule mods: map_file/mod.rs, pipeline/mod.rs,
transfer_ops/mod.rs
Net: 12 files, -114 lines. No semantic changes. No new clippy allows.
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
transfercrate's top-level sources.// upstream:citation, WHY note (state machine transitions, append-mode offset, fnamecmp inplace logic, etc.), and the existing rustdoc on public items.Scope
The
transfercrate is large (~51K LoC across 170 files), so this PR caps coverage at the top-level files and submodule entry points. Per-submodule deep dives (generator, receiver, pipeline, disk_commit, setup, ack_batcher, map_file, delta_pipeline) can follow as separate PRs.Files touched:
constants.rs,error.rs,flags.rs,role.rs,failed_directories.rs,temp_guard.rs,temp_cleanup.rs,compressed_writer.rs,parallel_io.rsmap_file/mod.rs,pipeline/mod.rs,transfer_ops/mod.rsNet: 12 files, -114 lines (42 insertions, 156 deletions). No semantic changes. No new
#[allow(...)].Test plan
cargo fmt --allcargo clippy --workspace --all-targets --all-features --no-deps -- -D warnings