Rustdoc
Rust API documentation as rendered and navigated by a crate user.
20 items in this guidance cluster.
Tagged guidance
Guide item
Documentation rules
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.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.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.
Rust rules
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.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.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.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.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.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.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.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.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.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.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.
Testing rules
Pattern items
Prefer 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.Run 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.