Repository navigation
docs: check private-item doc links in CI and fix the 30 that had accumulated - #722
Merged
Merged
Conversation
…mulated `cargo ci-doc` builds docs with `RUSTDOCFLAGS="-D warnings"`, which reads as "every rustdoc warning is an error". It was not: rustdoc only checks intra-doc links on items it actually renders, and without `--document-private-items` that means public items only. A broken link in the doc comment of a private fn, a private field, or a `#[cfg(test)]` helper never reached the linter. Thirty such links had accumulated across the workspace, all invisible to a green docs job. They fall into four kinds: - Symbols needing a path because they are not in scope at the link site (`PipelineError::*`, `EdgeMetrics`, `MAX_ARITY`, `TwoInputHandles`, `SortWorkerPool::phase1_queue_depths`, `PooledBamWriter::new_indexing`). - Associated fns linked bare instead of through `Self::` (`merge_chunks_generic`, `merge_chunks_with_index`). - A symbol that lives in another crate (`read_raw_record`, in `fgumi-raw-bam`). - Prose that rustdoc parses as a reference-style link: byte-layout notation `[len(4)][record(len)]`, index expressions `buffer[0]` and `R1[i]`, and `[`X`](path)` pairs whose explicit target is redundant because the text already resolves. None were reachable defects; the cost was a doc build that quietly under-checked itself, and links that render as literal brackets. Adding the flag to `ci-doc` closes the gap for good, and the whole workspace passes with it. Verified: `RUSTDOCFLAGS="-D warnings" cargo ci-doc` clean workspace-wide, plus ci-fmt / ci-lint / ci-tag-literals / ci-test (7835 tests).
|
Note Reviews pausedUse the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (17)
WalkthroughThe PR expands CI rustdoc coverage to private items and corrects documentation links and formatting across library and command modules. Runtime behavior and public declarations remain unchanged. ChangesRustdoc updates
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
Comment |
Member
Author
|
@coderabbitai pause |
✅ Action performedReviews paused. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main-runall #722 +/- ##
==============================================
Coverage ? 93.99%
==============================================
Files ? 208
Lines ? 119092
Branches ? 0
==============================================
Hits ? 111941
Misses ? 7151
Partials ? 0 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Member
Author
|
@coderabbitai review |
✅ Action performedReview finished.
|
nh13
added a commit
that referenced
this pull request
Aug 7, 2026
…mulated (#722) `cargo ci-doc` builds the workspace docs with `RUSTDOCFLAGS="-D warnings"`, which reads as "every rustdoc warning is an error." It was not. Rustdoc only checks intra-doc links on items it actually renders, and without `--document-private-items` that means public items only -- so a broken link in the doc comment of a private fn, a private field, or a `#[cfg(test)]` helper never reached the linter. Thirty such links had accumulated across the workspace, all of them invisible to a green docs job. This adds the flag to the `ci-doc` alias and fixes every link it surfaces, so the job now checks what its name implies. This is a gap in the check, not a pile of typos. It was found only because a broken link in `crates/fgumi-sort/src/inline.rs` was caught by review on #720 -- CI could not have caught it, and could not catch the other twenty-nine either. Closing the gap is the point; the fixes are the cost of closing it. None of the thirty were reachable defects: the cost was a doc build that quietly under-checked itself, plus links that render as literal brackets instead of hyperlinks. Four kinds: - Not in scope at the link site, so the path was required -- `PipelineError::*`, `EdgeMetrics`, `MAX_ARITY`, `TwoInputHandles`, `SortWorkerPool::phase1_queue_depths`, `PooledBamWriter::new_indexing`. - Associated fns linked bare instead of through `Self::` -- `merge_chunks_generic`, `merge_chunks_with_index`. - A symbol in another crate -- `read_raw_record` lives in `fgumi-raw-bam`, not `fgumi-sort`. - Prose that rustdoc parses as a reference-style link -- byte-layout notation `[len(4)][record(len)]`, index expressions `buffer[0]` and `R1[i]`, and ``[`X`](path)`` pairs whose explicit target is redundant because the link text already resolves. Touches `fgumi-sort`, `fgumi-pipeline-core`, `fgumi-bam-io`, and the main crate. Docs and one cargo alias only -- no functional change. Based on `main-runall` rather than `main` because eight of the fixes are in `fgumi-pipeline-core`, which does not exist on `main`. Three further instances of the same class, in files that #720 introduces, are fixed in #720 itself rather than here.
nh13
added a commit
that referenced
this pull request
Aug 9, 2026
…mulated (#722) `cargo ci-doc` builds the workspace docs with `RUSTDOCFLAGS="-D warnings"`, which reads as "every rustdoc warning is an error." It was not. Rustdoc only checks intra-doc links on items it actually renders, and without `--document-private-items` that means public items only -- so a broken link in the doc comment of a private fn, a private field, or a `#[cfg(test)]` helper never reached the linter. Thirty such links had accumulated across the workspace, all of them invisible to a green docs job. This adds the flag to the `ci-doc` alias and fixes every link it surfaces, so the job now checks what its name implies. This is a gap in the check, not a pile of typos. It was found only because a broken link in `crates/fgumi-sort/src/inline.rs` was caught by review on #720 -- CI could not have caught it, and could not catch the other twenty-nine either. Closing the gap is the point; the fixes are the cost of closing it. None of the thirty were reachable defects: the cost was a doc build that quietly under-checked itself, plus links that render as literal brackets instead of hyperlinks. Four kinds: - Not in scope at the link site, so the path was required -- `PipelineError::*`, `EdgeMetrics`, `MAX_ARITY`, `TwoInputHandles`, `SortWorkerPool::phase1_queue_depths`, `PooledBamWriter::new_indexing`. - Associated fns linked bare instead of through `Self::` -- `merge_chunks_generic`, `merge_chunks_with_index`. - A symbol in another crate -- `read_raw_record` lives in `fgumi-raw-bam`, not `fgumi-sort`. - Prose that rustdoc parses as a reference-style link -- byte-layout notation `[len(4)][record(len)]`, index expressions `buffer[0]` and `R1[i]`, and ``[`X`](path)`` pairs whose explicit target is redundant because the link text already resolves. Touches `fgumi-sort`, `fgumi-pipeline-core`, `fgumi-bam-io`, and the main crate. Docs and one cargo alias only -- no functional change. Based on `main-runall` rather than `main` because eight of the fixes are in `fgumi-pipeline-core`, which does not exist on `main`. Three further instances of the same class, in files that #720 introduces, are fixed in #720 itself rather than here.
nh13
added a commit
that referenced
this pull request
Aug 10, 2026
…mulated (#722) `cargo ci-doc` builds the workspace docs with `RUSTDOCFLAGS="-D warnings"`, which reads as "every rustdoc warning is an error." It was not. Rustdoc only checks intra-doc links on items it actually renders, and without `--document-private-items` that means public items only -- so a broken link in the doc comment of a private fn, a private field, or a `#[cfg(test)]` helper never reached the linter. Thirty such links had accumulated across the workspace, all of them invisible to a green docs job. This adds the flag to the `ci-doc` alias and fixes every link it surfaces, so the job now checks what its name implies. This is a gap in the check, not a pile of typos. It was found only because a broken link in `crates/fgumi-sort/src/inline.rs` was caught by review on #720 -- CI could not have caught it, and could not catch the other twenty-nine either. Closing the gap is the point; the fixes are the cost of closing it. None of the thirty were reachable defects: the cost was a doc build that quietly under-checked itself, plus links that render as literal brackets instead of hyperlinks. Four kinds: - Not in scope at the link site, so the path was required -- `PipelineError::*`, `EdgeMetrics`, `MAX_ARITY`, `TwoInputHandles`, `SortWorkerPool::phase1_queue_depths`, `PooledBamWriter::new_indexing`. - Associated fns linked bare instead of through `Self::` -- `merge_chunks_generic`, `merge_chunks_with_index`. - A symbol in another crate -- `read_raw_record` lives in `fgumi-raw-bam`, not `fgumi-sort`. - Prose that rustdoc parses as a reference-style link -- byte-layout notation `[len(4)][record(len)]`, index expressions `buffer[0]` and `R1[i]`, and ``[`X`](path)`` pairs whose explicit target is redundant because the link text already resolves. Touches `fgumi-sort`, `fgumi-pipeline-core`, `fgumi-bam-io`, and the main crate. Docs and one cargo alias only -- no functional change. Based on `main-runall` rather than `main` because eight of the fixes are in `fgumi-pipeline-core`, which does not exist on `main`. Three further instances of the same class, in files that #720 introduces, are fixed in #720 itself rather than here.
nh13
added a commit
that referenced
this pull request
Aug 10, 2026
`merge_phases.rs` (#706) opens with an intra-doc link to `crate::external::SortPhaseTimer`, but the struct is private to `external`, so the path is not nameable from another module and rustdoc cannot resolve it. Widen it to `pub(crate)` — the narrowest visibility that makes the existing cross-reference valid. No public API change. This surfaced only when #706 was rebased onto this branch: `main`'s `ci-doc` alias does not pass `--document-private-items`, so the broken link is invisible there, while this branch has checked private-item links since #722. The same gap will keep producing this class upstream until `main` adopts the flag.
nh13
added a commit
that referenced
this pull request
Aug 19, 2026
…mulated (#722) `cargo ci-doc` builds the workspace docs with `RUSTDOCFLAGS="-D warnings"`, which reads as "every rustdoc warning is an error." It was not. Rustdoc only checks intra-doc links on items it actually renders, and without `--document-private-items` that means public items only -- so a broken link in the doc comment of a private fn, a private field, or a `#[cfg(test)]` helper never reached the linter. Thirty such links had accumulated across the workspace, all of them invisible to a green docs job. This adds the flag to the `ci-doc` alias and fixes every link it surfaces, so the job now checks what its name implies. This is a gap in the check, not a pile of typos. It was found only because a broken link in `crates/fgumi-sort/src/inline.rs` was caught by review on #720 -- CI could not have caught it, and could not catch the other twenty-nine either. Closing the gap is the point; the fixes are the cost of closing it. None of the thirty were reachable defects: the cost was a doc build that quietly under-checked itself, plus links that render as literal brackets instead of hyperlinks. Four kinds: - Not in scope at the link site, so the path was required -- `PipelineError::*`, `EdgeMetrics`, `MAX_ARITY`, `TwoInputHandles`, `SortWorkerPool::phase1_queue_depths`, `PooledBamWriter::new_indexing`. - Associated fns linked bare instead of through `Self::` -- `merge_chunks_generic`, `merge_chunks_with_index`. - A symbol in another crate -- `read_raw_record` lives in `fgumi-raw-bam`, not `fgumi-sort`. - Prose that rustdoc parses as a reference-style link -- byte-layout notation `[len(4)][record(len)]`, index expressions `buffer[0]` and `R1[i]`, and ``[`X`](path)`` pairs whose explicit target is redundant because the link text already resolves. Touches `fgumi-sort`, `fgumi-pipeline-core`, `fgumi-bam-io`, and the main crate. Docs and one cargo alias only -- no functional change. Based on `main-runall` rather than `main` because eight of the fixes are in `fgumi-pipeline-core`, which does not exist on `main`. Three further instances of the same class, in files that #720 introduces, are fixed in #720 itself rather than here.
nh13
added a commit
that referenced
this pull request
Aug 19, 2026
`merge_phases.rs` (#706) opens with an intra-doc link to `crate::external::SortPhaseTimer`, but the struct is private to `external`, so the path is not nameable from another module and rustdoc cannot resolve it. Widen it to `pub(crate)` — the narrowest visibility that makes the existing cross-reference valid. No public API change. This surfaced only when #706 was rebased onto this branch: `main`'s `ci-doc` alias does not pass `--document-private-items`, so the broken link is invisible there, while this branch has checked private-item links since #722. The same gap will keep producing this class upstream until `main` adopts the flag.
nh13
added a commit
that referenced
this pull request
Aug 19, 2026
…mulated (#722) `cargo ci-doc` builds the workspace docs with `RUSTDOCFLAGS="-D warnings"`, which reads as "every rustdoc warning is an error." It was not. Rustdoc only checks intra-doc links on items it actually renders, and without `--document-private-items` that means public items only -- so a broken link in the doc comment of a private fn, a private field, or a `#[cfg(test)]` helper never reached the linter. Thirty such links had accumulated across the workspace, all of them invisible to a green docs job. This adds the flag to the `ci-doc` alias and fixes every link it surfaces, so the job now checks what its name implies. This is a gap in the check, not a pile of typos. It was found only because a broken link in `crates/fgumi-sort/src/inline.rs` was caught by review on #720 -- CI could not have caught it, and could not catch the other twenty-nine either. Closing the gap is the point; the fixes are the cost of closing it. None of the thirty were reachable defects: the cost was a doc build that quietly under-checked itself, plus links that render as literal brackets instead of hyperlinks. Four kinds: - Not in scope at the link site, so the path was required -- `PipelineError::*`, `EdgeMetrics`, `MAX_ARITY`, `TwoInputHandles`, `SortWorkerPool::phase1_queue_depths`, `PooledBamWriter::new_indexing`. - Associated fns linked bare instead of through `Self::` -- `merge_chunks_generic`, `merge_chunks_with_index`. - A symbol in another crate -- `read_raw_record` lives in `fgumi-raw-bam`, not `fgumi-sort`. - Prose that rustdoc parses as a reference-style link -- byte-layout notation `[len(4)][record(len)]`, index expressions `buffer[0]` and `R1[i]`, and ``[`X`](path)`` pairs whose explicit target is redundant because the link text already resolves. Touches `fgumi-sort`, `fgumi-pipeline-core`, `fgumi-bam-io`, and the main crate. Docs and one cargo alias only -- no functional change. Based on `main-runall` rather than `main` because eight of the fixes are in `fgumi-pipeline-core`, which does not exist on `main`. Three further instances of the same class, in files that #720 introduces, are fixed in #720 itself rather than here.
nh13
added a commit
that referenced
this pull request
Aug 19, 2026
`merge_phases.rs` (#706) opens with an intra-doc link to `crate::external::SortPhaseTimer`, but the struct is private to `external`, so the path is not nameable from another module and rustdoc cannot resolve it. Widen it to `pub(crate)` — the narrowest visibility that makes the existing cross-reference valid. No public API change. This surfaced only when #706 was rebased onto this branch: `main`'s `ci-doc` alias does not pass `--document-private-items`, so the broken link is invisible there, while this branch has checked private-item links since #722. The same gap will keep producing this class upstream until `main` adopts the flag.
nh13
added a commit
that referenced
this pull request
Aug 23, 2026
…mulated (#722) `cargo ci-doc` builds the workspace docs with `RUSTDOCFLAGS="-D warnings"`, which reads as "every rustdoc warning is an error." It was not. Rustdoc only checks intra-doc links on items it actually renders, and without `--document-private-items` that means public items only -- so a broken link in the doc comment of a private fn, a private field, or a `#[cfg(test)]` helper never reached the linter. Thirty such links had accumulated across the workspace, all of them invisible to a green docs job. This adds the flag to the `ci-doc` alias and fixes every link it surfaces, so the job now checks what its name implies. This is a gap in the check, not a pile of typos. It was found only because a broken link in `crates/fgumi-sort/src/inline.rs` was caught by review on #720 -- CI could not have caught it, and could not catch the other twenty-nine either. Closing the gap is the point; the fixes are the cost of closing it. None of the thirty were reachable defects: the cost was a doc build that quietly under-checked itself, plus links that render as literal brackets instead of hyperlinks. Four kinds: - Not in scope at the link site, so the path was required -- `PipelineError::*`, `EdgeMetrics`, `MAX_ARITY`, `TwoInputHandles`, `SortWorkerPool::phase1_queue_depths`, `PooledBamWriter::new_indexing`. - Associated fns linked bare instead of through `Self::` -- `merge_chunks_generic`, `merge_chunks_with_index`. - A symbol in another crate -- `read_raw_record` lives in `fgumi-raw-bam`, not `fgumi-sort`. - Prose that rustdoc parses as a reference-style link -- byte-layout notation `[len(4)][record(len)]`, index expressions `buffer[0]` and `R1[i]`, and ``[`X`](path)`` pairs whose explicit target is redundant because the link text already resolves. Touches `fgumi-sort`, `fgumi-pipeline-core`, `fgumi-bam-io`, and the main crate. Docs and one cargo alias only -- no functional change. Based on `main-runall` rather than `main` because eight of the fixes are in `fgumi-pipeline-core`, which does not exist on `main`. Three further instances of the same class, in files that #720 introduces, are fixed in #720 itself rather than here.
nh13
added a commit
that referenced
this pull request
Aug 23, 2026
`merge_phases.rs` (#706) opens with an intra-doc link to `crate::external::SortPhaseTimer`, but the struct is private to `external`, so the path is not nameable from another module and rustdoc cannot resolve it. Widen it to `pub(crate)` — the narrowest visibility that makes the existing cross-reference valid. No public API change. This surfaced only when #706 was rebased onto this branch: `main`'s `ci-doc` alias does not pass `--document-private-items`, so the broken link is invisible there, while this branch has checked private-item links since #722. The same gap will keep producing this class upstream until `main` adopts the flag.
This branch was previously deployed
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.
What
cargo ci-docbuilds the workspace docs withRUSTDOCFLAGS="-D warnings", which reads as "every rustdoc warning is an error." It was not. Rustdoc only checks intra-doc links on items it actually renders, and without--document-private-itemsthat means public items only — so a broken link in the doc comment of a private fn, a private field, or a#[cfg(test)]helper never reached the linter.Thirty such links had accumulated across the workspace, all of them invisible to a green docs job. This adds the flag to the
ci-docalias and fixes every link it surfaces, so the job now checks what its name implies.Why it matters
This is a gap in the check, not a pile of typos. It was found only because a broken link in
crates/fgumi-sort/src/inline.rswas caught by review on #720 — CI could not have caught it, and could not catch the other twenty-nine either. Closing the gap is the point; the fixes are the cost of closing it.None of the thirty were reachable defects. The cost was a doc build that quietly under-checked itself, plus links that render as literal brackets instead of hyperlinks.
The four kinds
PipelineError::*,EdgeMetrics,MAX_ARITY,TwoInputHandles,SortWorkerPool::phase1_queue_depths,PooledBamWriter::new_indexing.Self::—merge_chunks_generic,merge_chunks_with_index.read_raw_recordlives infgumi-raw-bam, notfgumi-sort.[len(4)][record(len)], index expressionsbuffer[0]andR1[i], and[X](path)pairs whose explicit target is redundant because the link text already resolves.Scope
Touches
fgumi-sort,fgumi-pipeline-core,fgumi-bam-io, and the main crate. Docs and one cargo alias only — no functional change.Based on
main-runallrather thanmainbecause eight of the fixes are infgumi-pipeline-core, which does not exist onmain.Three further instances of the same class, in files that #720 introduces, are fixed in #720 itself rather than here.
Verification
RUSTDOCFLAGS="-D warnings" cargo ci-doc— clean workspace-wide with--document-private-items, which fails on the parent commit.cargo ci-fmt,cargo ci-lint,cargo ci-tag-literals— clean.cargo ci-test— 7835 passed, 30 skipped.Risk: command output changes — none;
unsafechanges — none, andCLAUDE.mdis unchanged; memory bounds, queue capacity, and thread/backpressure policy changes — none.Fix:
cargo ci-docnow checks private items and test helpers with--document-private-items.