Repository navigation
Conversation
Module docs cited 18 `../wiki/…` markdown paths across 14 files. No `wiki/` directory has ever existed in the tree or anywhere in git history, and the project has no GitHub wiki. The paths were also mutually inconsistent about depth (`../`, `../../`, `../../../`), and every one sat inside backticks, so none of them ever rendered as a link even where a target might have existed. None of the 14 cited documents exists anywhere, so each pointer is either removed or replaced with a short explanation inline in the file it was meant to send the reader away from. One further citation of the same class, a bare `rocm-cli-unification-working-agreements.md`, was equally unresolvable and is fixed here too. Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
`cargo xtask verify-doc-paths` scans `//!` and `///` lines in tracked `.rs` files for citations of `.md` files and resolves each one against the citing file's own directory or the workspace root, both of which this tree uses. Every violation is reported at once rather than only the first. The check runs in the existing `clippy` CI job. `**/*.md` joins the `rust` path filter so that deleting or renaming a cited markdown file also triggers it, even when the change touches no `.rs` file. URLs and lines outside doc comments are deliberately ignored: ordinary code names `.md` files legitimately in string literals, and flagging those would make the check unusable. Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
`cargo xtask verify-doc-paths` failed on the file that implements it. The scan is line-based, and the test fixtures were multi-line string literals joined with a trailing backslash, so each continuation line began with `//!` or `///` once its indentation was trimmed. Two lines of fixture data — paths chosen precisely because they resolve to nothing — were read as real citations on `doc_paths.rs` itself. Building the fixtures with `concat!` keeps the prefix off the start of a line and leaves what each test asserts untouched. The paths they carry are now neutral placeholders: the check's acceptance criterion is that no `.rs` file in the tree names the directory that motivated it, and a test fixture is no exception. Both unresolvable shapes are still covered, the `../`-prefixed form and the bare filename. A design note records the limitation, since the same shape can bite a doc comment that quotes source or holds a fenced code block. Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
`resolve` joined the candidate onto both the citing file's directory and the workspace root and asked the filesystem, so a `../`-prefixed citation could climb out of the checkout and match a file in a sibling directory. Whether such a directory exists is a property of one machine, not of the tree: the same citation would resolve on the author's disk and dangle in CI, and the shape that motivated this check is exactly the one that escapes. Both candidates are now normalized lexically — `canonicalize` is no use on paths that do not exist — and rejected unless they land inside the workspace root. Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
The module doc said rows are grouped by `(cell, model, backend, concurrency)`. `RollupKey` also holds `tp` and `dtype`, and the field is `engine`, not `backend` — a difference the reader would only find by disbelieving the doc, and one that misstates what Pass^N and Pass@N are computed over. `row_verdict`'s summary is also split into a real first sentence. The paragraph break existed only to satisfy `too_long_first_doc_paragraph`, which left rustdoc showing half a sentence as the item's summary. Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
The module doc said the trial-group key is "every field that defines the run except the trial itself". It is not: `BenchmarkRow` also carries `task`, `prompt_class`, `pp`, `max_num_seqs`, `attention_backend`, `kv_dtype`, `spec`, `input_len`, `output_len` and `cache_mode`, none of which `RollupKey` holds. Two rows that differ only in `input_len` are folded into one trial set, so the sentence promised a guarantee the code does not make. `RollupKey`'s own doc carried the same overreach from further back — "everything that defines the backend config is held fixed" — while `endpoint`, `pp`, `max_num_seqs`, `attention_backend`, `kv_dtype` and `spec` sit in the schema's backend-config block and outside the key. Both now state the key and say plainly what it does not separate. Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
Two doc comments pointed at a line range in another file. Both had already rotted: `agent.rs:59-62` lands on `InferenceParams`' sampling knobs rather than the read-only chat seam it names, and `runner.rs:446-460` on nothing in particular — the `known_services.difference(&disc.seen)` it cites now sits near line 519. A line range is a citation that decays on the next edit above it, which is the same failure this branch is removing elsewhere, so both now name the file and the symbol and leave the reader to grep. Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
`**/*.md` joined the `rust` filter so a deleted or renamed doc file reaches `cargo xtask verify-doc-paths`. dorny/paths-filter matches patterns with picomatch, where a leading `**/` also matches zero directories, so the glob already covers the root-level `MANIFEST.md` entry sitting above it. Keeping both left a rule that can never decide anything, and two comments where one states why markdown is a Rust input at all. Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
`"////foo".strip_prefix("///")` succeeds, so a four-slash separator
banner was scanned like a doc line. rustc treats `////` as an ordinary
comment and rustdoc renders nothing from it, so a file name inside one is
not a citation the reader can follow, and flagging it would fail CI over
text no document ever pointed at.
None exists in the tree today, which is why the gate stayed green. The
design note also records that the block forms `/*! … */` and `/** … */`
are not scanned at all.
Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
Two tests passed for the wrong reason. `ignores_urls_ending_in_md` used only `scheme://host` links, where the scheme's `//` leads the character run and the absolute-path guard rejects the candidate on its own — the URL filter could be deleted and the test would still be green. It now also carries an anchored link, whose fragment puts a bare relative path inside the token, so dropping the whole token is what keeps the line quiet. `flags_every_unresolvable_citation_not_just_the_first` re-implemented the collection loop with an iterator instead of calling the code that does it, so `run()` could have returned at the first miss and the test would not have noticed. The loop moves into `check_source`, which returns the citations checked and a violation line for each miss; the test now covers both the count and the rendered messages, and `run()` keeps its totals. Verified by mutation: neutering the URL filter or capping the collection at one now fails the matching test. A design note records what the URL filter does not cover — a link written without a scheme, and a citation glued to a URL with no space. Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
Mutating each guard in `candidates_in_line` and deleting it showed two that no test noticed. Removing the angle brackets from the placeholder delimiter set left every test green, because the only bracketed fixture (`<name>.md`) has an empty stem and is rejected by the stem check first. Removing the stem check left every test green in turn, because that same fixture is rejected by the delimiter check. Each guard was standing in for the other, so either could have been deleted unnoticed. Add a bracketed name with a real stem, and a bare extension with nothing next to it, so each guard is now the only thing rejecting one case. Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
|
Reviewed the full diff, including the new The checker's design holds up: doc-line-only scanning (skips The replaced doc comments read as genuine explanations where one was warranted (the Elm-style reducer note in CI is green. Looks safe to approve. |
juhovainio
left a comment
There was a problem hiding this comment.
Reviewed the new xtask/src/doc_paths.rs checker as real logic, not just a doc change: the doc-line-only scanning, URL stripping, the two resolution roots (relative-to-file vs. workspace-root), and the workspace-escape guard are all correct, and each tricky case (a citation with no URL scheme, a path that climbs out of the workspace but exists on the author's disk) has a dedicated test. The replaced doc comments read as genuine explanations or clean removals. CI is green. Approving.
nowycondro
left a comment
There was a problem hiding this comment.
🔴 Automated review · pr-review-watcher · a7ad926
Review — no blocking findings
Full review of the whole change.
No ticket named. No runtime behavior changes; the description's claims (18 dead ../wiki/... pointers across 14 files, 3 further citations of the same class, the new cargo xtask verify-doc-paths gate and its scan rules) all match what the review found in the diff — no mismatch.
Blocking
None
Non-blocking
None
Decisions for the author
- Widening the
rustCI path filter to**/*.md— tradeoff. This makes any PR that touches any markdown file anywhere in the repo trigger the fullclippyjob (previously onlyMANIFEST.mddid), which is necessary for soundness — deleting/renaming a cited.mdfile with no.rsfile in the diff must still runverify-doc-paths— but is a real CI-cost increase for prose-only PRs. Already deliberate and documented in the workflow comment; worth confirming the cost is acceptable going forward. - Documented URL-handling limitation in
doc_paths.rs— tradeoff. The module doc itself notes two unhandled shapes: a scheme-bearing link glued with no space to an adjacent real citation (drops both), and a scheme-less barehost/path(not filtered, could misread as a local citation if one ever appeared). Neither shape currently exists in the tree; both are explicitly called out as accepted limitations rather than silently missed. Non-blocking as written.
Positive signals
bench_rollup.rs's rewritten grouping-key doc comment,(cell, model, engine, tp, dtype, concurrency), is byte-for-byte correct against the realRollupKeystruct — and is a genuine accuracy fix, not just dead-link removal: the old wiki-citation text it replaced had named a nonexistentbackendfield and omittedtp/dtype.lib.rs's new "Elm-style reducer" description was checked againststate::State::apply's actual signature and theStateEvent/SideEffecttypes it names — matches exactly.doc_paths.rs's workspace-escape guard uses component-wisePath::starts_withrather than a raw string prefix check, correctly avoiding the classic bug where a sibling directory name sharing a prefix (e.g./root2vs/root) would otherwise wrongly pass containment.- Every guard in the new checker is backed by a test that was independently confirmed (via targeted mutation of each branch) to fail when that specific branch is neutered — including two guards the author's own later commits (
5909e8c8,a7ad9267) found and fixed were previously untested, a rare case of a PR's own history showing self-driven mutation-coverage work. - The
approval.rsdoc-comment edit also removed a second, non-wiki/dangling citation (rocm-cli-unification-working-agreements.md) beyond the PR's stated scope — confirmed that file has never existed in the repo's history — showing good impact-analysis instinct rather than a narrow literal fix.
Deployment notes
None — documentation and a new build-time CI gate only; no runtime behavior changes.
What this covered
Full change reviewed completely (merge-base 03c46b58 … head a7ad9267), split across two independent parallel passes: (1) the new xtask/src/doc_paths.rs checker plus its xtask/src/main.rs and .github/workflows/ci.yml wiring, and (2) all 16 touched crates/rocm-dash-* doc-comment-only files, each read in full at the PR head via git show (never checked out). Both passes independently verified every rewritten doc comment against the real code it describes, checked for orphaned/incomplete edits, and ran mutation-style verification confirming each new test actually depends on the logic it claims to cover. Driver-level checks on top: full commit-message/structure review (11 atomic, Conventional-Commits-compliant commits, each independently verifiable against its own stated rationale), a repository-wide search confirming zero remaining wiki/ references of any kind in any file type, cross-check of the PR description against the diff (no scope mismatch), and a live re-check of PR state immediately before publishing (head commit unchanged, CI fully green, no prior review from this account).
Did not run: a separate history/blame pass beyond what full-file reads and commit-message review already covered (doc_paths.rs is new, so there is no prior history to blame; the edited doc comments were read in full file context). No Rust toolchain was available in the review sandbox, so the checker's logic was independently verified by porting it to Python and executing targeted mutations rather than running cargo test directly — note this is a substitute verification, not identical to running the real suite, though the PR's own CI already ran the genuine cargo test / cargo xtask verify-doc-paths and is green. Not reconciled against any PR discussion or review threads, per scope — only checked that no up-to-date review from this reviewing account already existed at the current head (none found).
juhovainio
left a comment
There was a problem hiding this comment.
$(cat /tmp/review_body.md)
There was a problem hiding this comment.
Blocking: missing docs/architecture.md entry for this new file.
AGENTS.md §5/§6 requires every .rs file under xtask/src to get an inline markdown row in docs/architecture.md "in the same change as the file," enforced by cargo xtask check-architecture-doc in the clippy CI job. I read that checker's source on current origin/main directly: doc_paths.rs falls inside its HAND_KEPT_TREES scope (xtask/src/) with no helper exemption, and docs/architecture.md on current main has no row for it (it would sit alphabetically between demos.rs and e2e.rs, and isn't there).
This PR's own CI passed only because its branch point (merge-base 03c46b58, 2026-09-09) predates this enforcement script existing on main — origin/main has since advanced well past it, and git merge-tree shows this branch is no longer cleanly mergeable regardless (real conflicts in ci.yml, amd_smi.rs, bench_rollup.rs, lib.rs, approval.rs, plus a modify/delete conflict on vllm_log.rs, deleted on main). Whoever rebases this will hit a real clippy-job failure unless a docs/architecture.md row is added for this file in the same change.
Confidence 85 · mechanical · Fix: add the docs/architecture.md row alongside the rebase this branch needs anyway.
There was a problem hiding this comment.
This applies to the guard, which is being dropped; see the closing comment on the PR.
|
Correction to the review above (pullrequestreview-5939042284): a templating error posted that review's body as the literal unexpanded string Review — needs workFull review of the whole change (single-context; see What this covered for why the planned fan-out didn't run). Blocking
Non-blockingNone Decisions for the author
Positive signals
Deployment notesThis branch is roughly two months stale against What this coveredEvery changed file read in full at the PR head ( Did not run as an independent fan-out: the review-code skill calls for splitting this into per-group worker passes, but every 🤖 Automated by an AI agent |
|
Closing this one. The dangling What remains is the Thank you juhovainio for the careful review. The points raised (the missing Happy to revisit if the pattern comes back. The branch is left in place. |
Module-level doc comments across the
rocm-dashcrates sent readers to 18../wiki/…markdown paths in 14 files. Nowiki/directory has ever existedin this repository or anywhere in its history, and the repository has no GitHub
wiki, so none of the 14 cited documents could ever be opened. The paths were
mutually inconsistent about depth (
../,../../,../../../) and all satinside backticks, so none of them ever rendered as a link either.
These pointers sat on the modules carrying the least obvious design — the
state reducer, the metric registry, the benchmark result schema, GPU partition
modes — so the reader was sent away exactly where the explanation was most
needed.
Each pointer is either removed or replaced with a short explanation written in
the file, since none of the cited content exists anywhere to link to instead.
Three further citations of the same class are fixed here as well: a bare
rocm-cli-unification-working-agreements.md, which is equally unresolvable,and two pointers that cited line ranges in other files which had already
drifted onto unrelated code.
To stop the pattern returning,
cargo xtask verify-doc-pathsscans//!and///lines in tracked.rsfiles for.mdcitations and resolves each oneagainst the citing file's directory or the workspace root, reporting every
violation in a single run. It ignores URLs, non-doc-comment lines and
////banner comments so that string literals and build-artifact paths are not
flagged. It is wired into the existing
clippyjob, and**/*.mdwas added tothe
rustpath filter so that deleting a cited markdown file also runs thecheck.
Verification
cargo xtask verify-doc-paths—16 citation(s) across 188 file(s) resolvecitations fails the check and names the file and line; reverting it passes.
must fail a named test — so the unit tests cannot pass for the wrong reason.
cargo fmt --all --check,cargo clippy --workspace --all-targets -- -D warnings,cargo test --workspace --all-targets,cargo test --workspace --doc,hawkeye check,prek run --all-files,python scripts/smoke_local.py— all pass.No acceptance scenario accompanies this change: it alters documentation text
and adds a build-time consistency check, and changes no runtime behaviour. The
new check is covered by unit tests in
xtask/src/doc_paths.rs.tests/e2e-cucumber/expectations.tomlfor the fixed ticket ID and removed/narrowed any now-stale xfail rows.Not applicable — this changes no runtime behaviour, and no xfail rows relate to it.