Rust / 系统课时

编写文档注释

编写文档注释

文档注释用于把公共接口的用途、参数约束和示例直接写进源码,并由 Rust 工具链生成 API 文档。本课将完成一个带可执行示例的公共函数,并用文档测试验证示例始终可用。

学习目标

  • 区分 /// 与 //! 的使用位置
  • 为公共接口编写清晰的说明和示例
  • 使用 cargo test --doc 验证文档代码

文档注释的两种位置

/// 用于说明紧随其后的函数、结构体、枚举、模块或常量,适合描述某个公共项。//! 用于说明当前模块或整个 crate,通常放在 lib.rs、main.rs 或模块文件顶部。

普通注释 // 只服务于阅读源码,不会进入生成的 API 文档。公共接口应优先使用文档注释,并说明调用者真正需要知道的行为,而不是逐行复述实现。

编写可执行示例

下面是一个完整的库代码示例。项目包名使用 doc-demo,在 Rust 代码中对应 crate 名 doc_demo。将内容保存为 src/lib.rs。

rust
//! 提供简单整数运算的示例库。

/// 返回两个整数之和。
///
/// # Examples
///
/// ```
/// use doc_demo::add;
///
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(left: i32, right: i32) -> i32 {
    left + right
}

预期结果:

text
库成功编译后公开 add 函数;生成的 API 页面显示函数说明与 Examples 示例。

文档代码块没有标记 ignore 时,会被 Rust 当作独立测试编译并运行。示例必须包含调用所需的导入和断言,这样读者复制后可以直接验证结果。

常用约定与边界

文档中的小节名称不是强制语法,但 Rust 社区通常使用 # Examples、# Panics、# Errors 和 # Safety。函数可能触发 panic! 时说明触发条件;返回 Result 时解释错误场景;公开 unsafe 接口时必须写明调用者要维护的安全约束。

文档示例应展示最典型的正确用法。需要隐藏初始化代码时,可在代码行前加 # ,该行仍参与编译,但生成页面默认不展示。除非示例确实无法运行,否则不要使用 ignore 跳过测试。

验证文档测试

在项目根目录执行以下命令:

bash
cargo test --doc

预期输出:

text
   Doc-tests doc_demo

running 1 test
test src/lib.rs - add (line <LINE>) ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in <TIME>

<LINE> 和 <TIME> 会随源码位置与机器性能变化。若示例中的导入、类型或断言错误,命令会直接失败,因此文档示例也能随代码持续回归。

本课总结

  • /// 描述单个公共项,//! 描述模块或 crate
  • 文档示例应包含必要导入和可验证断言
  • cargo test --doc 能防止文档与真实 API 脱节

下一课预告

下一课将使用 Cargo 生成完整 API 文档、在浏览器中打开页面,并检查文档测试结果。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

编写文档注释

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通