LuisLlamas Logo
rust-documentacion-doctests

Documentation in Rust with cargo doc, /// and doc-tests

  • 4 min
  • Beginner

rustdoc is the tool that generates HTML documentation from comments in Rust code.

Rust includes this tool by default. When you install Rust, you already have everything you need to generate a beautiful web page (HTML/CSS) with your project’s documentation. It is the same tool used by the official standard library documentation.

SymbolUseWhere does it go?Does it appear on the web?
//Internal notes for programmersAnywhereNo
///Documentation of an elementJust before the function/structYes
//!Container documentation (module/crate)At the beginning of the fileYes

Documentation comments (///)

So far we have used // for normal comments. These are for you or other developers reading the source code.

To document the public API (for users of your library), we use three slashes: ///. These comments support full Markdown.

/// Adds one to the given number.
///
/// # Examples
///
/// ```
/// let x = 5;
/// let y = my_crate::add_one(x);
///
/// assert_eq!(y, 6);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}
Copied!

Documentation tests

Notice the code block inside the comment above. It looks like a simple Markdown example, right?

In a documentation comment, that Rust block can become a test.

When you run cargo test, Rust doesn’t only run unit tests (src) and integration tests (tests/). It also processes the Rust code blocks in the documentation. We can modify their behavior with attributes like no_run, compile_fail, or ignore.

  • If the example compiles and runs correctly: ✅ The test passes.
  • If you change the add_one function but forget to update the example: 💥 The test fails.

This helps ensure that examples still compile and maintain the expected behavior. The explanatory text can still become outdated, so it also needs review.

Common sections

Although you can write whatever you want in Markdown, the Rust community uses several conventions to organize information with headers (#).

# Examples

Shows how to use the function. When the block participates in doctests, Cargo can check it automatically.

# Panics

If your function can panic (for example, unwrap or division by zero), you must document it here. The user needs to know which inputs to avoid.

/// Divides two numbers.
///
/// # Panics
///
/// Will panic if `b` is 0.
pub fn divide(a: i32, b: i32) -> i32 {
    if b == 0 { panic!("Division by zero"); }
    a / b
}
Copied!

# Errors

If your function returns Result, explain under what circumstances it will return Err and what kind of error it will be.

# Safety

If your function is unsafe, you must explain what conditions the user must guarantee to call it without breaking memory safety.

Documenting the module (//!)

Sometimes you want to document the entire file (the module or the crate), not a specific item. For that, we use the comment with an exclamation mark: //!.

It is usually placed at the first line of src/lib.rs or src/main.rs.

//! # My Math Library
//!
//! `my_lib` is a collection of utilities for doing
//! complex arithmetic in a simple way.
//!
//! ## Basic usage
//! ...

// Normal code starts here
pub mod algebra;
Copied!

Generating the website

To see the final result, simply run:

$ cargo doc --open
Copied!

This command:

  1. Analyzes your code and your comments.
  2. Generates a static website in target/doc.
  3. Opens your default browser displaying the documentation.

And it not only documents your code! It also generates the documentation for all your dependencies.

That is, if you use serde or tokio, you will have their documentation available offline and linked with yours in the same format.

On this page