Skip to content

docs(core): drop restatement comments in tests across core#4598

Merged
oferchen merged 1 commit into
masterfrom
docs/comment-cleanup-core
May 20, 2026
Merged

docs(core): drop restatement comments in tests across core#4598
oferchen merged 1 commit into
masterfrom
docs/comment-cleanup-core

Conversation

@oferchen
Copy link
Copy Markdown
Owner

Summary

Per-crate comment cleanup pass on the core crate, following the same precedent as PRs #4591 (protocol), #4590 (transfer), #4589 (fast_io), #4584 (filters), #4582 (logging), #4583 (platform), #4587 (matching), #4575 (compress).

The core crate was already in good shape thanks to its #![deny(missing_docs)] policy:

  • All public types, traits, functions, and re-exports carry rustdoc (verified by the crate-level deny).
  • Production code is dominated by upstream cites (main.c, options.c, compat.c, flist.c, rsync.c, clientserver.c, util1.c, log.c) and WHY notes covering iconv apply hook ordering, INC_RECURSE gating, local-copy progress assumptions, transport-selection rationale, and shell quoting rules - all preserved.
  • The signal/ subtree was excluded from this pass per the BR-10b precedent (PR fix(core): move sigaction unsafe out of core into fast_io #4571); its docs are already accurate.

Net change: 69 lines removed, 1 added across 12 files. Removals target:

  • Test-section header banners (// Tests for X) that simply prefix a group of #[test] functions whose names already describe the subject.
  • Comments that restate the next line of code or the immediately following assertion message verbatim.
  • A handful of stray "comment that says what the variable is" annotations in test helpers.

Scope coverage

Walked the entire crates/core/src/ tree except signal/ (excluded per task scope). No scope cap applied - the crate was already clean enough that the full walk fit comfortably within one PR.

Test plan

  • cargo fmt --all -- --check
  • cargo clippy --workspace --all-targets --all-features --no-deps -- -D warnings
  • CI matrix (fmt+clippy, nextest, Windows, macOS, Linux musl)

Removes test-section header banners ("Tests for X"), comments that
restate the next line or assertion message, and a handful of phrasing
duplicates in tests. Preserves every upstream cite, WHY note explaining
non-obvious invariants (iconv apply hook ordering, INC_RECURSE gating,
local-copy progress assumptions, sparse fallback semantics), and the
existing safety attributions. No semantic changes.
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label May 20, 2026
@oferchen oferchen merged commit e56069a into master May 20, 2026
55 checks passed
@oferchen oferchen deleted the docs/comment-cleanup-core branch May 20, 2026 20:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant