Rust Programming By Example

Code blocks

The code we write in doc-comments must be inserted between two pairs of ```. Usually, the code blocks are written under an Examples header. Let's see an example using all of these syntactic elements for a function that convert bytes to uppercase:

/// Convert a sequence of bytes to uppercase.
///
/// # Examples
///
/// ```
/// let mut data = b"test";
/// to_uppercase(&mut data);
/// ```
fn to_uppercase(data: &mut [u8]) {
    for byte in data {
        if *byte >= 'a' as u8 && *byte <= 'z' as u8 {
            *byte -= 32;
        }
    }
}

Here, we start with a short description of the function. Then, we show a code example.

It's recommended to add comments in the code if needed, to help users understand it more easily, so don't hesitate to add some!