Rust Reference ยท Attributes
The #[doc] attribute and doc comments
Reference for Rust documentation: /// and //! doc comments, the #[doc] attribute forms, hidden items, doc tests, intra-doc links and Markdown sections.
Documentation in Rust is part of the code. A comment that starts with /// documents the item that follows it, and //! documents the item that contains it (usually a module or crate). Both are Markdown, and cargo doc (which runs rustdoc) turns them into a browsable HTML site.
Under the hood, /// text is shorthand for the attribute #[doc = " text"]. The attribute form is useful for generating docs from macros, and for rustdoc settings such as #[doc(hidden)] and #[doc(alias = "...")].
/// Adds two numbers. /// /// ``` /// assert_eq!(add(1, 2), 3); /// ``` pub fn add(a: i32, b: i32) -> i32 { a + b }
Try it
Documentation is processed by rustdoc, not by the program, so these examples show the source forms and prove they compile and run normally.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
/// Outer doc comment: documents the next item. //! Inner doc comment: documents the enclosing item. /** Block form (rarely used). */ #[doc = "text"] #[doc(hidden)] #[doc(alias = "name")] #![doc(html_root_url = "...")]
| Form | Meaning |
|---|---|
/// |
Documents the following item |
//! |
Documents the enclosing module or crate; must come first |
#[doc = "..."] |
The attribute that doc comments expand to |
#[doc(hidden)] |
Hide the item from generated docs (it stays public) |
#[doc(alias = "x")] |
Extra search term for the item |
#[doc(inline)] / #[doc(no_inline)] |
Control how re-exports are shown |
Common section headings by convention: # Examples, # Panics, # Errors, # Safety (required reading for unsafe functions) and # Arguments.
Edge cases:
- A
///comment with nothing after it (at the end of a block) is an error: doc comments must attach to something. - Four slashes (
////) is an ordinary comment, not a doc comment. - Code blocks in docs are compiled and run as doc tests by
cargo test. Addno_run,ignore,should_panicorcompile_failafter the fence to change that.
Usage notes
- Intra-doc links. Write
[Vec]or[crate::module::Item]and rustdoc turns it into a link, checked by therustdoc::broken_intra_doc_linkslint. - Hide setup lines. In a doc test, start a line with
#to compile it but hide it from the rendered page. - First line = summary. Make it one short sentence; it appears in listings and search results.
- Document public API first. The
missing_docslint (#![warn(missing_docs)]) reminds you of items without docs. - Macros. Use
#[doc = concat!(...)]or#[doc = include_str!("../README.md")]to reuse text. - Private items are only documented with
cargo doc --document-private-items.
Related
- Lint attributes,
#[test],#[deprecated] - Lessons: Comments and docs, Testing