Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Tools

rustdoc and doctests

Reference for rustdoc: doc comment syntax, Markdown, intra-doc links, hidden doctest lines, doc attributes like should_panic and no_run, and doc lints.

rustdoc is the compiler's documentation generator. It reads doc comments (/// for the next item, //! for the enclosing one), renders them as Markdown, and produces searchable HTML. It also extracts every Rust code block from the comments and compiles it as a doctest, so examples in your documentation cannot silently go out of date.

Most of the time you reach it through cargo doc and cargo test --doc. This page is a read-only reference; the examples show how doc comments and doctest rules look in real code.

Rust
/// Doubles a number.
///
/// ```
/// assert_eq!(mylib::double(4), 8);
/// ```
pub fn double(n: i32) -> i32 { n * 2 }

Try it

Rust Doc comments with sections and links

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 Doctest hidden lines, mirrored by hand

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

Terminal
rustdoc [options] <file.rs>
cargo doc    # builds docs
cargo test --doc   # runs doctests

Code-block attributes (after the opening fence):

Attribute Meaning
(none) or rust Compile and run; the test fails on panic or non-zero exit.
no_run Compile but do not run (network or file access examples).
ignore Skip entirely (shows in results as ignored).
should_panic The run must panic.
compile_fail Compilation must fail; handy for showing what the borrow checker rejects.
edition2024 Compile with a specific edition.
text Not Rust; never compiled.

Intra-doc links: [Vec], [crate::module::Item], [Self::method], and [text][path].

Usage notes

  • Each doctest is compiled as its own tiny crate that depends on yours, so only public items are reachable and use lines are required.
  • If a block has no fn main, rustdoc wraps the code in one. Lines starting with # are hidden from readers but still compiled.
  • Conventional headings: # Examples, # Panics, # Errors, # Safety (required for unsafe fn), # Arguments.
  • Lints such as rustdoc::broken_intra_doc_links and missing_docs keep documentation honest; deny them in CI.
  • Hide implementation details from the docs with #[doc(hidden)], or inline re-exports with #[doc(inline)].
  • #![doc = include_str!("../README.md")] reuses your README as the crate documentation, and doctests inside it run too.
  • Doctests are slower than unit tests because each links separately; keep them to illustrative examples.