A doc comment is a Rust comment beginning with three slashes (`///`). Attached to an item, it becomes part of the crate’s generated API documentation instead of remaining an ordinary source comment. section 7.1.1
Doc comments support several practical documentation and testing features:
- Describe public items and render their type signatures and explanations in generated documentation. section 7.1.1
- Use Markdown for lists, links, emphasis, and other formatting. section 7.1.1
- Include fenced code examples that compile as separate crates and access only the crate’s public API. section 7.1.1
- Run documentation examples with `cargo test`, alongside ordinary tests. section 7.1.1 section 7.3
Documenting and testing `add`
/// Add together two i32 numbers and return the result of that addition /// ``` /// assert_eq!(testing::add(2, 2), 4); /// ``` pub fn add(x: i32, y: i32) -> i32 { x + y } A passing example validates the documented public API. Incorrect assertions fail, while invalid argument types fail to compile.
