Rust Docs Guidelines
Standards to follow when writing Rust documentation.
Guidelines
- Key concepts should be explained only once. All other documentation should use an intra-documentation link to the first explanation.
- Always use an intra-documentation link when mentioning a Rust symbol (type, function, constant, etc.).
- Avoid referring to specific lines or line ranges, as they may change over time. Use line comments if the documentation needs to be attached to a specific code section inside a function/method body.
- Focus on why, not how. In particular, avoid explaining trivial implementation details in line comments.
- Refer to constants using intra-documentation links. Don't hard-code their values in the documentation of other items.
- Intra-documentation links to private items are preferable to duplication. Add
#[allow(rustdoc::private_intra_doc_links)]where relevant.