Rust 代码文档生成

发布时间: 更新时间: 总字数:392 阅读时间:1m 作者: IP属地: 分享 复制网址

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);
}

生成文档:

// 生成文档
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
Home Archives Categories Tags Statistics
本文总阅读量 次 本站总访问量 次 本站总访客数