How to Write Doc Tests That Also Serve as Examples

Write doc tests by adding /// comments above your function containing executable code, then run mdbook test to verify them. This approach uses the rustdoc tool to compile and execute the examples as tests, ensuring your documentation stays accurate.

/// Adds two numbers.
///
/// # Examples
///
/// ```
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
fn add(a: i32, b: i32) -> i32 {
    a + b
}

Run the tests with:

mdbook test

Doc tests are code examples written directly in your documentation comments that automatically run as tests. They matter because they prove your examples work and catch bugs when you change your code. Think of it like a recipe that automatically checks if the ingredients and steps actually make the dish before you publish it.