Doc testsConcept

Explanation

A doc test is a fenced code block written inside a documentation comment — /// above an item, or //! at the top of a module or crate — that cargo test compiles and runs as an executable example, in addition to rustdoc rendering it as prose. Nothing special has to be written to opt in: by default, any fenced block inside a /// comment on a public item of a library crate is a doc test, which is what makes doc comments unusual among Rust's documentation tools — they are simultaneously human-facing prose and a regression check.

The mental model worth keeping is that a doc test is really testing the documentation, not just the code: it exists to guarantee that the example a reader sees on docs.rs still compiles and behaves exactly as shown. If a function's behavior changes and nobody updates its doc comment's example, cargo test fails — turning what would otherwise be silently stale documentation into a build failure, which is precisely the gap unit tests and integration tests don't cover, since neither one looks at prose.

Each doc test is compiled as its own tiny standalone program, implicitly wrapped in a fn main() { ... } unless the block already defines one, and linked against the crate's public API exactly like an external caller — which is why a doc test can only reference pub items, the same constraint an integration test has. Annotations placed right after the opening triple backtick change how a block is treated: no_run compiles it but skips execution (useful for examples with real side effects), ignore skips it entirely, and should_panic asserts the example panics rather than returning normally.

Basic usage example

/// Converts a Celsius temperature to Fahrenheit.
///
/// ```
/// assert_eq!(sensors::celsius_to_fahrenheit(0.0), 32.0); // <- this block compiles and runs under `cargo test`
/// ```
pub fn celsius_to_fahrenheit(celsius: f64) -> f64 {
    celsius * 9.0 / 5.0 + 32.0
}

Best practices & deeper information

/// Parses a sensor reading line like `"7,21.5"` into an id and a Celsius value.
///
/// ```
/// # use sensors::SensorReading;
/// let reading = sensors::parse_reading("7,21.5").unwrap();
/// assert_eq!(reading, SensorReading { id: 7, celsius: 21.5 }); // <- what the reader actually sees
/// ```
#[derive(Debug, PartialEq)]
pub struct SensorReading {
    pub id: u32,
    pub celsius: f64,
}

pub fn parse_reading(line: &str) -> Option<SensorReading> {
    let (id, celsius) = line.split_once(',')?;
    Some(SensorReading { id: id.parse().ok()?, celsius: celsius.parse().ok()? })
}

/// Parses a duration string like `"30s"` into whole seconds.
///
/// ```
/// # fn run() -> Result<(), std::num::ParseIntError> {
/// let seconds = config::parse_duration_seconds("30s")?; // <- `?` needs the enclosing fn to return a Result
/// assert_eq!(seconds, 30);
/// # Ok(())
/// # }
/// # run().unwrap();
/// ```
pub fn parse_duration_seconds(input: &str) -> Result<u32, std::num::ParseIntError> {
    input.trim_end_matches('s').parse()
}

/// Divides `total` evenly across `shares`.
///
/// # Panics
///
/// Panics if `shares` is zero.
///
/// ```should_panic
/// sensors::split_evenly(100, 0); // <- doc test asserts this call panics
/// ```
pub fn split_evenly(total: u32, shares: u32) -> u32 {
    if shares == 0 {
        panic!("cannot split into zero shares");
    }
    total / shares
}