How to Write Good Documentation for Rust Crates

Write good Rust crate documentation by using rustdoc comments to generate API docs and mdbook to build user guides. Add /// comments above public items for API documentation and create a book.toml file to configure the book structure.

[package]
name = "my_crate"
version = "0.1.0"
edition = "2024"

[dependencies]

/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

[book]
title = "My Crate Guide"
authors = ["Your Name"]

[output.html]

cargo doc --open
mdbook build

1. Add /// comments above public functions, structs, and modules to describe their purpose and usage.
2. Create a book.toml file in the root directory to define the book title, authors, and output settings.
3. Run cargo doc --open to generate and view the API documentation in your browser.
4. Run mdbook build to compile the user guide from markdown files in the src directory.

Good documentation helps users understand how to use your code without reading the source. Think of it like a recipe book: the API docs are the ingredient list, and the user guide is the step-by-step instructions. You write comments in your code and markdown files, then use tools to turn them into a website.