iru-rust-rustdoc
Audit given Rust items or files (a crate or Cargo workspace — e.g. a command-line tool's `src/lib.rs` modules, a library) for complete rustdoc on every public item — crate/module `//!` docs, a one-sen
SKILL.md.claude/skills/iru-rust-rustdoc/SKILL.md
GitHubRust Rustdoc
Make sure a set of Rust items carry complete, well-formed rustdoc, filling in whatever is missing, then prove the
result through the doc lints, a warnings-as-errors cargo doc build, and the doctests. This skill only adds/completes
doc comments (///, //!) — it does not change behavior, signatures, attributes, use lines, or any non-doc
code. Test code (tests/, #[cfg(test)] mod tests, benches/) and generated code are out of scope; docs
they already have are left as-is. It makes no assumptions about this being any particular repository — discover the
workspace, its conventions and tooling fresh each run.
Step 0 — Survey the workspace
cargo metadata --format-version 1 --no-deps | python3 -c 'import json,sys; m=json.load(sys.stdin); ids=set(m["workspace_members"]); print(m["workspace_root"]); [print(p["name"], [(t["kind"][0], t["src_path"], t["doctest"]) for t in p["targets"]]) for p in m["packages"] if p["id"] in ids]'
- Run everything from the workspace root. Note each member's library root (
kindlib,src_path…/src/lib.rs) and binaries. A target withdoctest: false(every bin, or a lib withdoctest = falsein[lib]) never runs its examples. - Bin-only crates: doc comments in
src/main.rs/src/bin/*.rsare rendered bycargo doconly when no library shares the name, and their code blocks are never compiled or run (cargo test --docon such a package fails withno library targets found, verified). Document a binary's items for readers, but don't write# Examplesthere — put examples on the library items the binary calls. This catalog's CLI scaffold keepsmain.rsthin for this reason. - Tooling:
cargo clippy --versionandcargo doc(rustdoc ships with every toolchain). Clippy missing → the section lints in Step 3 can't run; say so and rely on reading the code plus Step 5's build.
Step 1 — Determine scope
- Argument provided: comma-separated item paths or files/globs.
- Files/globs → expand with
find/ls; keep.rsfiles. - Item paths → resolve to the defining file:
crate::output::Envelope/output::Envelope→ the module file (src/output.rsorsrc/output/mod.rs) of the crate whose library root you're in (with several members, ask or prefer the CLI package), thengrep -n "pub \(struct\|enum\|trait\|fn\|type\|const\|static\|mod\) Envelope"to find the item;<member_crate>::config→ that member'ssrc/config.rs. A module path covers the whole module file; an item path covers that item and its public members (fields, variants, methods, associated items).
- Files/globs → expand with
- No argument: every non-test
.rsfile touched by uncommitted changes plus commits on the current branch not yet on the base branch:
(base branch viagit status --porcelain git diff --name-only <base-branch>...HEAD -- '*.rs' git diff --name-only -- '*.rs'git symbolic-ref refs/remotes/origin/HEAD, elsegit branch -a; ask only if genuinely ambiguous). - Always drop
target/,tests/,benches/,examples/(examples are documentation already),build.rs, generated files (// @generated,include!dOUT_DIRcode) and anything git-ignored — name dropped arguments in the report. Empty scope → say there is nothing to document and stop. - What gets documented (the audit set): what
missing_docschecks — every item reachable from the crate's public API: the crate root (//!inlib.rs), public modules (//!at the top of the module file, or///on thepub modline), and public structs, enums, each variant, eachpubfield, traits and their methods,pubfunctions and methods,pubconsts/statics/type aliases and macros exported with#[macro_export]. Private items andpub(crate)items are out of scope unless the project documents them habitually (look at--document-private-itemsin CI) — never add docs to trait-impl methods (impl Display for X { fn fmt … }): they inherit the trait's docs.
Step 2 — Discover this project's actual documentation bar
- Lints:
[lints.rust]missing_docs,[lints.rustdoc](broken_intra_doc_links,missing_crate_level_docs,private_intra_doc_links,bare_urls),[lints.clippy](pedanticenablesmissing_errors_doc,missing_panics_doc,doc_markdown,must_use_candidate;missing_safety_docis on by default) — in the rootCargo.tomlor[workspace.lints]inherited withlints.workspace = true; also crate-level#![warn(missing_docs)]attributes. The project'sallows are part of the bar (e.g.missing_panics_doc = "allow"). - CI:
RUSTDOCFLAGS: -D warningsoncargo doc(this catalog's workflows set it),--document-private-items,--all-features(feature-gated items are documented only when their feature is on),[package.metadata.docs.rs](all-features,rustdoc-args = ["--cfg", "docsrs"]with#[cfg_attr(docsrs, doc(cfg(...)))]). - House style from 2–3 well-documented files near the scope and any contributor guide (
CLAUDE.md,AGENTS.md,CONTRIBUTING.md): third-person summary ("Returns …", "Parses …" — the std/API-Guidelines style), whether# Examplesis habitual,?in examples with a hidden# Ok::<(), Error>(())line, how errors are named in# Errors. Follow the stricter of stated vs observed.
The convention (rustdoc book + Rust API Guidelines, as used by this catalog's scaffolds):
- First paragraph = one-sentence summary ending in a period; it is what module listings and search show. Then a
blank
///line and optional detail. Markdown throughout; identifiers in backticks (clippy::doc_markdownflags bareCamelCase/snake_casewords). - Intra-doc links for every type, method or module named:
[`Envelope`],[`Envelope::to_json`],[`crate::exit::ExitCode`],[`std::io::Error`]; disambiguate withstruct@/fn@/macro@when names collide. A link to a private item from public docs triggersrustdoc::private_intra_doc_links— link to something public or use plain backticks. # Errors— everypub fnreturningResult: which error variants/kinds and when (Returns [`CliError::Validation`] if `name` is empty or longer than 64 characters.). Read the body for every?,Err(..)and.map_err(..).# Panics— everypub fnthat can panic (unwrap,expect, indexing,assert!,unreachable!, integer overflow in debug): the condition. If the panic is impossible by construction, prefer stating why in an internal comment and let the user decide — never invent a condition.# Safety— everyunsafe fn/unsafe trait: the invariants the caller must uphold. (This catalog's CLI scaffold forbidsunsafe_code, so this is rare.)# Examples— a runnable doctest on the main entry points of the library API (constructors, parsers, the command functions a CLI'smaincalls), using the crate's public path (use democli::output::Envelope;), with?+ a hidden# Ok::<(), democli::Error>(())line instead ofunwrap()where the API returnsResult. Use```no_runfor examples that would touch the network/filesystem/terminal,```ignorenever (it hides rot), and```textfor shell sessions or output samples. Don't add examples to trivial getters.- Crate root:
//!inlib.rswith what the crate provides (for a CLI's library: "Library behind the<bin>command: …"); each public module: a//!line saying what it holds. Enum variants and struct fields get one-line///s.
Step 3 — Audit each in-scope file
Run the doc lints for the whole workspace, forced on, and keep only in-scope findings (-A the rest so the output
stays about docs):
mkdir -p target
cargo clippy --workspace --all-targets --all-features --locked --message-format=json -- \
-A clippy::all -A clippy::pedantic -W missing_docs -W clippy::missing_errors_doc -W clippy::missing_panics_doc \
-W clippy::missing_safety_doc -W clippy::doc_markdown > target/iru-rust-rustdoc-lints.json 2>/dev/null
python3 - target/iru-rust-rustdoc-lints.json 'src/output.rs,src/commands/' <<'PY'
import json
import sys
scope = [s.rstrip("/") for s in sys.argv[2].split(",") if s]
seen = set()
for line in open(sys.argv[1]):
if not line.startswith("{"):
continue
d = json.loads(line)
if d.get("reason") != "compiler-message":
continue
m = d["message"]
sp = [s for s in m["spans"] if s["is_primary"]]
if not sp:
continue
key = ((m.get("code") or {}).get("code"), sp[0]["file_name"], sp[0]["line_start"])
if key in seen or not any(key[1] == s or key[1].startswith(s + "/") for s in scope):
continue
seen.add(key)
print(f"{key[1]}:{key[2]} {key[0]} — {m['message']}")
PY
(Drop --locked when the project has no Cargo.lock.) The -W flags apply to every workspace crate — including
members that don't inherit the lint table, such as xtask — which is why the scope filter matters. Findings name the
item's line: missing_docs ("missing documentation for a function/struct/the crate/a variant/a struct field"),
clippy::missing_errors_doc, clippy::missing_panics_doc, clippy::missing_safety_doc, clippy::doc_markdown.
Then read each in-scope file — lints only prove a doc exists, not that it's right — and for every item in Step 1's
audit set check that the summary actually describes it (not "Greet." for greet), that # Errors lists the errors
the body really returns (compare with every ?/Err), that # Panics matches the panicking calls, that links
resolve to what's meant, and that the docs describe current behavior (git diff/git log -p for the file).
Record each gap: item, kind, what's missing (whole doc vs a section/link/example), file.
Step 4 — Write the missing docs
Before editing, capture the Step 5 build's warnings once (baseline) so new warnings can be told from pre-existing ones.
For every gap, write the doc grounded in the implementation (what is returned and when, which errors/panics, side
effects such as writing to stdout/stderr, files, exit codes for a CLI's command functions) and in the convention from
Step 2, so new docs are indistinguishable from hand-written ones. Apply with the Edit tool: /// immediately above the
item and above any #[derive]/attributes it has (attributes may sit between the doc and the item, but keep the
existing order); //! as the first lines of lib.rs/the module file, after a license header comment if there is
one. Do not modify code, signatures, attributes, use lines, or formatting outside the added docs, and don't reorder
items. Keep lines within the project's max_width (rustfmt doesn't wrap comments by default) — run nothing that
rewrites code; cargo fmt is not this skill's job.
Step 5 — Verify
Write every output as target/iru-rust-rustdoc-* (target/ is gitignored) and delete them at the end
(rm -f target/iru-rust-rustdoc-*).
- Doc lints — re-run Step 3. Every finding in an in-scope file must be gone (one on an item this run didn't touch but that sits in an in-scope file is still a gap — fix it).
- rustdoc build, warnings as errors:
ExitRUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --locked [--all-features] --message-format=json \ > target/iru-rust-rustdoc-doc.json 2>/dev/null; echo "exit=$?"101lists each warning-turned-error as acompiler-message(same parser as Step 3, without the clippy flags):rustdoc::broken_intra_doc_links("unresolved link toNope"),rustdoc::private_intra_doc_links,rustdoc::bare_urls,rustdoc::invalid_codeblock_attributes,rustdoc::unescaped_backticks, and the project's own[lints](missing_docsis enforced by rustdoc too — verified). Mirror CI's flags (--all-features,--document-private-items,--cfg docsrswhen[package.metadata.docs.rs]uses it). Add-W rustdoc::missing_crate_level_docstoRUSTDOCFLAGSwhen the scope includes a crate root. - Doctests:
Every example you wrote must compile and pass (cargo test --workspace --locked --doc [--all-features] > target/iru-rust-rustdoc-doctest.log 2>&1test src/output.rs - output::Envelope (line 12) ... ok). A failing one is fixed in the doc, never by changing code. Packages without a library are skipped by cargo — say "no doctests for bin-only crate<name>".compile_fail/should_panicexamples you add must state why in the prose.
Compare with the Step 4 baseline: any new warning or failure naming an in-scope file was caused by this run — fix and re-run until none remain. Pre-existing problems outside the scope are follow-ups, not this skill's to fix.
Step 6 — Report
Per file in scope: how many public items were already fully documented, the gaps found and filled (name each with its
kind and what was added — "Envelope struct: summary + 3 field docs", "greet::run: # Errors (2 variants) +
# Examples", "crate root: //! docs"), then the verification result — doc lints: clean or what remains; cargo doc with -D warnings: pass, or the open warnings; doctests: N passed / which failed / "none (bin-only)". Name the
convention source, arguments dropped (tests, examples, generated), and pre-existing out-of-scope failures as
follow-ups. Never paste raw tool output or JSON.
Do not fix non-doc lints, change code to make a doc "true", edit Cargo.toml lint tables or CI, edit license
headers, or add/modify tests — those belong to iru-rust-code-quality, the coding skills, and the user.
Verification notes
Verified on 2026-10-16 with Rust 1.99.1 stable (clippy 0.1.99), in $TMPDIR/iru-verify/cli/rust-gates/ (outside this
repository) on a workspace with a democli lib + bin ([lints.rust] missing_docs = "warn", [lints.clippy] pedantic)
and an xtask member:
- The Step 3 command reported
missing_docsfor an undocumentedpub fn(src/lib.rs:23) and for the bin crate root (src/main.rs:1—[lints]applies to bins too),clippy::missing_errors_docfor aResult-returning fn andclippy::missing_panics_docfor a fn callingunwrap(); the-W missing_docsflag also hitxtask/src/main.rs, removed by the scope filter. RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --message-format=jsonexited101withrustdoc::broken_intra_doc_links("unresolved link toNope") andmissing_docsaserror-level messages; without-D warningsthe same two were warnings.- After adding a summary +
# Examplesdoctest, an# Errorssection with an intra-doc link to[`std::num::ParseIntError`], a# Panicssection and the bin's//!line, the lints came back empty,cargo docexited0, andcargo test --docran 2 doctests, both passing. - On a bin-only crate
cargo test --docexited101(no library targets found in package) and a deliberately failing example inmain.rswas never compiled bycargo test. - Not verified:
--document-private-itemsworkspaces,doc(cfg)with--cfg docsrs(nightly feature), scraped examples (nightly), and macro-generated items.
Sources
- irurueta docs: programming-languages/rust/documentation-with-rustdoc.adoc (
///vs//!, one-sentence summary,# Examples/# Errors/# Panics/# Safety, intra-doc links, doctest attributes, rustdoc lints,RUSTDOCFLAGS="-D warnings" cargo doc --no-deps) - irurueta docs: programming-languages/rust/testing-and-benchmarking.adoc (doctests run by
cargo test, combined doctests in edition 2024, bin-only crates can't be imported — logic inlib.rs) - irurueta docs: programming-languages/rust/tooling-clippy-rustfmt-and-rust-analyzer.adoc (
[lints]table, pedantic doc lints) - The rustdoc book; Rust API Guidelines: Documentation (C-CRATE-DOC, C-EXAMPLE, C-FAILURE, C-LINK)