Skip to content
Tutorials Center
My learning

Topics

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 = "...")].

Rust
/// 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.

Rust Doc comments are attributes

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.

Rust doc attributes that change rendering

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

Rust
/// 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. Add no_run, ignore, should_panic or compile_fail after 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 the rustdoc::broken_intra_doc_links lint.
  • 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_docs lint (#![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.