Rust 有三种注释:
//
用于代码注释。/**/
用于块注释。///
和//!
用于文档注释。/*/
用于文档块注释
文档注释可以使用 markdown 语法。此外,被注释的代码还需要是 pub 的。
包注释需要放在 lib.rs 的最上方。
如果不希望一些内容出现在生成的文档中,可以使用:
/// ```
/// # // 使用 # 开头的行会在文档中被隐藏起来,但是依然会在文档测试中运行
/// # fn try_main() -> Result<(), String> {
/// let res = world_hello::compute::try_div(10, 0)?;
/// # Ok(()) // returning from try_main
/// # }
/// # fn main() {
/// # try_main().unwrap();
/// #
/// # }
/// ```
交叉引用
在文档中可以进行交叉引用:
/// `add_one` 返回一个[`Option`]类型
pub fn add_one(x: i32) -> Option<i32> {
Some(x + 1)
}
生成文档
使用 cargo doc
可以生成文档。使用 cargo doc --open
可以在生成文档后自动打开文档。