Doc comments in Rust

/// documents the item below it, and the example in it is a test that runs.

//! Scoring helpers for a tour step.

/// Stars earned for a run, from zero to three.
///
/// # Examples
///
/// ```
/// assert_eq!(stars_for(95.0, 90.0), 3);
/// ```
///
/// # Panics
///
/// Panics if `target` is zero.
pub fn stars_for(tpm: f64, target: f64) -> u8 {
    assert!(target > 0.0, "target must be positive");
    let ratio = tpm / target;
    match ratio {
        r if r >= 1.0 => 3,
        r if r >= 0.8 => 2,
        _ => 1,
    }
}

fn main() {
    println!("{}", stars_for(95.0, 90.0));
    println!("{}", stars_for(60.0, 90.0));
}

How it works

1. /// documents the next item, //! the enclosing one.
2. A fenced example becomes a doc test.
3. # Panics and # Examples are the conventional headings.

Keywords and builtins used here

• f64
• fn
• if
• let
• main
• match
• pub
• stars_for
• u8

The run, in numbers

Lines

27

Characters to type

502

Tokens

109

Three-star pace

105 tpm

At the three-star pace of 105 tokens a minute, this run takes about 62 seconds.

Type this snippet

Step 3 of 3 in Tests & docs, step 6 of 12 in Modules, tests & macros.

← Previous Next →