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 可以在生成文档后自动打开文档。

Last moify: 2022-12-04 15:11:33
Build time:2025-07-18 09:41:42
Powered By asphinx