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.
/// Doubles a number. /// /// ``` /// assert_eq!(mylib::double(4), 8); /// ``` pub fn double(n: i32) -> i32 { n * 2 }
Try it
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
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
uselines 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 forunsafe fn),# Arguments. - Lints such as
rustdoc::broken_intra_doc_linksandmissing_docskeep 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.