A doc test automatically compiles and executes an executable Rust example extracted from documentation. Running cargo test discovers these examples as tests, helping keep API documentation working. section 6.11.2
Rust-specific mechanics make documentation examples concise:
- Omit main(); rustdoc preprocesses the example by wrapping it in fn main() { … } and generating test code. section 6.11.2
- Use cargo watch -x doc to regenerate documentation while editing. section 6.11.2
Executable linked-list documentation
A crate-level example imports LinkedList, creates an empty list, and appends chicken, ostrich, antelope, axolotl, and okapi. The example becomes a passing Doc-test when cargo test runs.
