Rustdoc

Rust API documentation as rendered and navigated by a crate user.

20 items in this guidance cluster.

Tagged guidance

GuideDocumentationExamplesSource TruthMarkdown And Documentationmarkdown-documentationMarkdown and documentation guidance covers lintable Markdown, reader paths, page modes, Rustdoc, examples, references, and reusable guidance style. It favors current behavior, task-first user docs, durable source links, and prose that preserves local voice.

RuleDocumentationSource TruthPublic APIAlign README and Crate RustdocDOCS-ALIGN-README-AND-CRATE-RUSTDOCKeep README and crate-level Rustdoc consistent where users learn setup and supported behavior. Let the pages serve different tasks, but prevent conflicting contracts.RuleDocumentationVerificationExamplesBuild Docs Like Users Read ThemDOCS-BUILD-DOCS-LIKE-USERS-READ-THEMReview rendered Rust documentation, links, cfg behavior, and examples in the modes users see. Match validation depth to the risk of feature, metadata, or public example changes.RuleDocumentationExamplesVerificationMark Noncompiling Examples HonestlyDOCS-MARK-NONCOMPILING-EXAMPLES-HONESTLYLabel examples that are sketches, partial snippets, or intentionally not run. Honest labels keep readers from treating illustrative code as a supported copy-paste contract.

RuleRustDocumentationExamplesAvoid Vague Docs and Generic ExamplesRUST-AVOID-VAGUE-DOCS-AND-GENERIC-EXAMPLESWrite Rustdoc and examples around real caller scenarios, not generic claims of usefulness. Concrete examples expose ownership, errors, features, and lifecycle expectations.RuleRustDocumentationToolingConfigure docs.rsRUST-CONFIGURE-DOCS-RSConfigure docs.rs metadata when features, cfgs, or rustdoc flags affect rendered API docs. Users should see the documentation surface the crate expects to support.RuleRustPublic APIReader LocalityExpose Primary Path from Crate RootRUST-EXPOSE-PRIMARY-PATH-FROM-CRATE-ROOTMake the crate root show the main workflow, types, and import path. Users should not have to infer the intended entry point from private layout details.RuleRustDocumentationLocal ConventionsFormat Docs and Comments ConsistentlyRUST-FORMAT-DOCS-AND-COMMENTS-CONSISTENTLYApply stable formatting to Rustdoc, examples, attributes, and prose comments. Consistent source formatting keeps docs readable and prevents noisy future diffs.RuleRustDocumentationSource TruthKeep Markdown Outside Rustdoc PurposefulRUST-KEEP-MARKDOWN-OUTSIDE-RUSTDOC-PURPOSEFULUse standalone Markdown for architecture, workflow, release, or operational guidance that would make API docs noisy. Choosing the right surface keeps contracts and long-form context current.RuleRustDocumentationExamplesKeep Rustdoc and README Examples AlignedRUST-KEEP-RUSTDOC-AND-README-EXAMPLES-ALIGNEDKeep README, Rustdoc, generated docs, and example directories teaching the same current usage contract. Aligned examples prevent users from guessing which import path or lifecycle is correct.RuleRustDocumentationPublic APITeach Crate From Crate RootRUST-TEACH-CRATE-FROM-CRATE-ROOTUse crate-root docs and exports to teach the crates main concepts, entry points, and common paths. Keep the root focused enough to orient readers without duplicating every item-level contract.RuleRustPublic APIReader LocalityUse Doc Inline For Canonical ReexportsRUST-USE-DOC-INLINE-FOR-CANONICAL-REEXPORTSUse #[doc(inline)] when a re-export should be the canonical place readers encounter an item. Avoid inlining re-exports that would obscure the owning module or create duplicate-looking documentation.RuleRustTestingVerificationValidate Rust Docs As CodeRUST-VALIDATE-RUST-DOCS-AS-CODETreat Rust documentation examples, links, feature assumptions, and generated README content as code that must be checked. Use docs builds, doctests, feature-gated checks, and Markdown lint according to the changed surface.RuleRustDocumentationPublic APIWrite Public Docs For Caller TasksRUST-WRITE-PUBLIC-DOCS-FOR-CALLER-TASKSWrite public Rustdoc around what callers are trying to decide, do, and rely on. Start with concise behavior and add arguments, failures, lifecycle, features, links, or examples only when they help the task.RuleRustDocumentationPublic APIWrite Rustdoc As API ContractRUST-WRITE-RUSTDOC-AS-API-CONTRACTUse Rustdoc to state caller-facing behavior, invariants, failures, side effects, and compatibility promises. Leave private implementation detail in comments unless it helps maintain the public contract.

RuleTestingExamplesVerificationCover Public Examples with DoctestsTEST-COVER-PUBLIC-EXAMPLES-WITH-DOCTESTSCompile public documentation examples as doctests when they do not need fragile state. Executable examples catch stale guidance, reserving no-run or ignored examples for real limits.

PatternDocumentationLocal ConventionsReviewabilityPrefer 100-Column Prose Wrapprefer-100-column-prose-wrapWrap Markdown prose and Markdown-bearing doc comments around 100 columns as a maintainer readability preference. The exact number is subjective, but it balances source reading, monospace density, review diffs, and common screen sizes better than 80 or 120 columns.PatternRustDocumentationPublic APIRun Rustdoc Quality Passrun-rustdoc-quality-passUse a bounded checklist when raising a Rust crates public documentation. The pass should teach the crate model, document public contracts, place examples where they prove real use, keep documentation layers aligned, and validate Rustdoc as code.

MechanismRustDocumentationVerificationRust Docs Validationrust-docs-validationDoctests, Rustdoc warnings, rendered docs, and docs.rs-style builds prove documentation surfaces the way users will see them. Use this mechanism when examples, public API docs, feature docs, or release-facing documentation changes.

AgentDocumentationReview HandoffSource TruthMarkdown And Docs Agent Instructionsagent-markdown-docs-instructionsCompact documentation instructions for agents editing Markdown, Rustdoc, READMEs, review notes, or adjacent narrative. The snippet focuses on current behavior, local voice, page purpose, drift repair, and markdownlint-compatible formatting.