The gap
Nothing in CI runs cargo doc. A broken intra-doc link therefore reaches main
and stays there, and the repo relies heavily on intra-doc links — comments name
the guard that pins the behaviour they describe, which is most of what makes them
worth reading (see #308, which repaired 66 dangling citations of the prose kind).
The half that makes this worth a job rather than a habit: a broken link to a
private item produces no rustdoc warning at all, unless
--document-private-items is passed. So the usual "watch the warnings" instinct
does not cover it, and neither does a reviewer's eye reliably.
How it was found, which is the argument for the guard
PR #534 turned WorkspaceId::parts (a method) into parts_of (a free function).
Two doc comments referenced the old name:
workspace_id.rs:24 — module-level //! docs. Warns. The reviewer caught it.workspace_id.rs:495 — docs on the private Parts struct. Silent. Nothing
would ever have reported it.
The first was caught by luck of position; the second was found only because
fixing the first prompted a grep for the same string. Had the rename touched only
private items, both would have shipped.
The one that warned also happened to sit on the sentence that justifies the type's
whole design ("both come out of one parts_of, so a change to where the cuts fall
moves the id and the label together or not at all") — i.e. the link most worth
following was the broken one.
Proposed job
Add cargo doc to CI and gate on unresolved links, not on warnings generally:
RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links" cargo doc --no-deps --workspace --document-private-items
--document-private-items is the load-bearing flag — without it the silent half
stays silent. -D rustdoc::broken_intra_doc_links denies exactly the lint that
matters rather than -D warnings, which brings in unrelated noise.
Measured baseline (as of main after #534): cargo doc -p devlaunch-core
reports 0 unresolved links, so the gate goes in green with nothing to clean up
first. It also emits many public documentation for X links to private item Y
warnings — dozens, a long-standing and deliberate pattern in this repo — which is
precisely why the gate must name the one lint and not deny warnings wholesale.
Worth confirming the count across the whole workspace rather than one crate before
wiring it, and worth checking what --document-private-items adds to the
unresolved count, since that path has never been measured here.
Why it belongs with tonight's other issues
This is the #517 family — a signal that means less than a reader assumes — with an
extra turn: here the check does not exist, and its absence is invisible. A
reader seeing green CI has no way to notice that documentation correctness was
never among the things that green covered. #517 and #529 are about verdicts
ranging over less than their claim; this is a claim with no verdict behind it at
all.
The gap
Nothing in CI runs
cargo doc. A broken intra-doc link therefore reachesmainand stays there, and the repo relies heavily on intra-doc links — comments name
the guard that pins the behaviour they describe, which is most of what makes them
worth reading (see #308, which repaired 66 dangling citations of the prose kind).
The half that makes this worth a job rather than a habit: a broken link to a
private item produces no rustdoc warning at all, unless
--document-private-itemsis passed. So the usual "watch the warnings" instinctdoes not cover it, and neither does a reviewer's eye reliably.
How it was found, which is the argument for the guard
PR #534 turned
WorkspaceId::parts(a method) intoparts_of(a free function).Two doc comments referenced the old name:
workspace_id.rs:24— module-level//!docs. Warns. The reviewer caught it.workspace_id.rs:495— docs on the privatePartsstruct. Silent. Nothingwould ever have reported it.
The first was caught by luck of position; the second was found only because
fixing the first prompted a grep for the same string. Had the rename touched only
private items, both would have shipped.
The one that warned also happened to sit on the sentence that justifies the type's
whole design ("both come out of one
parts_of, so a change to where the cuts fallmoves the id and the label together or not at all") — i.e. the link most worth
following was the broken one.
Proposed job
Add
cargo docto CI and gate on unresolved links, not on warnings generally:RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links" cargo doc --no-deps --workspace --document-private-items--document-private-itemsis the load-bearing flag — without it the silent halfstays silent.
-D rustdoc::broken_intra_doc_linksdenies exactly the lint thatmatters rather than
-D warnings, which brings in unrelated noise.Measured baseline (as of
mainafter #534):cargo doc -p devlaunch-corereports 0 unresolved links, so the gate goes in green with nothing to clean up
first. It also emits many
public documentation for X links to private item Ywarnings — dozens, a long-standing and deliberate pattern in this repo — which is
precisely why the gate must name the one lint and not deny warnings wholesale.
Worth confirming the count across the whole workspace rather than one crate before
wiring it, and worth checking what
--document-private-itemsadds to theunresolved count, since that path has never been measured here.
Why it belongs with tonight's other issues
This is the #517 family — a signal that means less than a reader assumes — with an
extra turn: here the check does not exist, and its absence is invisible. A
reader seeing green CI has no way to notice that documentation correctness was
never among the things that green covered. #517 and #529 are about verdicts
ranging over less than their claim; this is a claim with no verdict behind it at
all.