Rust 代码文档生成

Rust文档注释，生成代码文档，且文档注释中的示例代码块可以通过cargo test测试。

介绍

• /// 注释：生成 HTML 文档（在 target/doc 目录下），如 API 如何使用

  • 支持 Markdown
  • 一般放置在被说明条目之前
  • 常见的章节：
    • # Example 示例
    • # Panics 函数可能发生的 panic 的场景
    • # Errors 若返回 Result，描述可能的错误种类，以及错误条件
    • # Safety 若函数 unsafe 调用，解释函数 unsafe 的原因，以及如何 safe 调用

• //! 注释：为包含注释的项添加文档注释，使用场景：

  • 为 crate root (通常为 src/lib.rs) 添加注释
  • 一个模块内，将 crate 或模块作为一个整体进行注释

• lib.rs 示例

//! # cargoabc
//!
//! `cargoabc` is a test cargo lib for xiexianbin

/// say hello
///
/// # Example
///
/// ```
/// rustabc::say(String::from("x"));
/// ```
pub fn say(name: String) {
  println!("hello {}", name);
}
source repo / download raw

生成文档：

// 生成文档
cargo doc

// 生成文档，并使用浏览器打开文档
cargo doc --open

说明：

• cargo doc 实际运行 rustdoc 工具（Rust 安装自带）
• 文档注释中的示例代码块作为测试：运行 cargo test 时，将文档注释中的示例代码作为测试运行，上述示例测试：

$ cargo test
...
   Doc-tests rustabc

running 1 test
test src/lib.rs - say (line 5) ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.55s