Writing documentation is a great thing. Showing code in your documentation is even better. However, how can you be sure that the code you're showing is still up to date? That it won't break when users copy/paste it to test it out? Here comes another wonderful feature from Rust: doc tests.
First, any code blocks in documentation comments will be tested by default if they don't have ignore or any non-recognized tag. So, for example:
/// ```ignore /// let x = 12; /// x += 1; /// ```
This block code won't be tested (luckily, because it wouldn't compile!). A few other examples:
/// # Some text
///
/// ```text
/// this is just some text
/// but it's rendered inside a code block
/// nice, right?
/// ```
///
/// # Why not C?
///
/// ```c-language
/// int strlen(const char *s) {
/// char *c = s;
///
/// for (; *c; ++c);
/// return c - s;
/// }
/// ```
///
/// # Or an unknown language?
///
/// ```whatever
/// 010010000110100100100001
/// ```A few other instructions...