81 lines
3.5 KiB
Plaintext
81 lines
3.5 KiB
Plaintext
|
{
|
||
|
|
id = "0012",
|
||
|
|
slug = "rust-doc-authoring-pattern",
|
||
|
|
description = "Add Documentation Authoring (Rust) section to .claude/CLAUDE.md and optional pre-commit hooks for rustdoc broken links and crate //! drift detection.",
|
||
|
|
check = {
|
||
|
|
tag = "Grep",
|
||
|
|
pattern = "Documentation Authoring",
|
||
|
|
paths = [".claude/CLAUDE.md"],
|
||
|
|
must_be_empty = false,
|
||
|
|
},
|
||
|
|
instructions = "
|
||
|
|
## 1. Add to .claude/CLAUDE.md
|
||
|
|
|
||
|
|
Insert the following section under '## Key Conventions' (or equivalent conventions block).
|
||
|
|
Create .claude/CLAUDE.md if it does not exist.
|
||
|
|
|
||
|
|
### Documentation Authoring (Rust)
|
||
|
|
|
||
|
|
Three canonical doc layers — each answers a different question:
|
||
|
|
|
||
|
|
Layer | Where | Answers
|
||
|
|
-------------------|------------------|------------------------------------------
|
||
|
|
/// on items | handlers, types | \"what does this item do?\"
|
||
|
|
//! in lib.rs | crate root | \"what does this crate provide as a whole?\"
|
||
|
|
node description | .ontology/ | \"what is this concept in the architecture?\"
|
||
|
|
|
||
|
|
Rules that apply to every .rs file:
|
||
|
|
|
||
|
|
1. /// first line = one standalone sentence. No 'This function/handler/struct...' preamble.
|
||
|
|
This line becomes the API catalog entry, describe features summary, and MCP description.
|
||
|
|
Further lines after a blank /// are detail and do not appear in catalogs.
|
||
|
|
|
||
|
|
2. //! first sentence must be conceptually aligned with the practice node whose
|
||
|
|
artifact_paths[0] points to this crate. Run `ontoref sync diff --docs` to verify.
|
||
|
|
|
||
|
|
3. Omit `description = \"...\"` in #[onto_api] when a /// doc comment exists above the handler.
|
||
|
|
The proc-macro reads /// automatically. Only use explicit description = \"...\" for
|
||
|
|
generated or macro-expanded handlers that cannot carry ///.
|
||
|
|
|
||
|
|
4. //! is mandatory on every lib.rs. Missing //! on a crate with a practice node
|
||
|
|
fails the docs-drift pre-commit check.
|
||
|
|
|
||
|
|
Agent workflow — discovering doc state:
|
||
|
|
ontoref describe workspace # per-crate //! present?, coverage %, drift status
|
||
|
|
ontoref describe features <id> # node description + IMPLEMENTATION VIEW (//! excerpt)
|
||
|
|
ontoref sync diff --docs # explicit drift report before committing
|
||
|
|
|
||
|
|
Registering a new crate as a practice implementation:
|
||
|
|
1. Add/update a Practice node in .ontology/core.ncl with artifact_paths = [\"crates/my-crate/\"]
|
||
|
|
2. Write //! in crates/my-crate/src/lib.rs — first sentence aligned with the node description
|
||
|
|
3. Run `ontoref sync diff --docs` to confirm Jaccard OK
|
||
|
|
4. Run `ontoref generate-mdbook` — a docs/src/crates/my-crate.md page is generated
|
||
|
|
|
||
|
|
|
||
|
|
## 2. Add pre-commit hooks (Rust projects only)
|
||
|
|
|
||
|
|
Skip this step if the project has no Rust crates.
|
||
|
|
|
||
|
|
Add to .pre-commit-config.yaml in the local hooks section (alongside rust-clippy / rust-test):
|
||
|
|
|
||
|
|
- id: docs-links
|
||
|
|
name: Rustdoc broken intra-doc links
|
||
|
|
entry: bash -c 'RUSTDOCFLAGS=\"-D rustdoc::broken-intra-doc-links -D rustdoc::private-intra-doc-links\" cargo doc --no-deps --workspace -q'
|
||
|
|
language: system
|
||
|
|
types: [rust]
|
||
|
|
pass_filenames: false
|
||
|
|
stages: [pre-commit]
|
||
|
|
|
||
|
|
- id: docs-drift
|
||
|
|
name: Crate //! doc drift check
|
||
|
|
entry: bash -c 'nu -c \"use ./reflection/modules/sync.nu; sync diff --docs --fail-on-drift\"'
|
||
|
|
language: system
|
||
|
|
types: [rust]
|
||
|
|
pass_filenames: false
|
||
|
|
stages: [pre-commit]
|
||
|
|
|
||
|
|
docs-drift only fires meaningfully when the project has Practice nodes with artifact_paths
|
||
|
|
pointing to Rust crate directories. If no such nodes exist, the hook exits 0 silently.
|
||
|
|
",
|
||
|
|
}
|