[!info] 关联笔记

• 所属 MOC：测试与质量 · 学习路线
• 前置概念：测试、Cargo
• 后续概念：公共 API 文档
• 容易混淆：单元测试

Rust 文档测试

这个概念为什么出现

文档会腐。
Rust 把 markdown 代码块当测试跑，迫使公共示例保持可编译。

[!abstract] 一句话理解 /// 文档里的 ``` 示例默认由 cargo test 编译运行；文档即契约的一部分。

最小可运行示例

场景：库函数文档自带可运行示例

/// 计算含税价（10%）。
///
/// # Examples
///
/// ```
/// // 在库 crate 中，doctest 可写成：
/// // use mylib::with_tax;
/// // assert_eq!(with_tax(1000), 1100);
/// assert_eq!(1000 + 1000/10, 1100);
/// ```
fn with_tax(net: u32) -> u32 {
    net + net / 10
}

fn main() {
    println!("{}", with_tax(1000));
}

对真实库：cargo test --doc。

结合场景再看三个关注点

1. 示例应反映真实调用
2. ignore/no_run/should_panic 属性 控制行为
3. 隐藏行 # 可放 setup

核心概念与准确模型

• doctest 默认像独立 crate 用公共 API
• 可 ```rust,ignore
• cargo test --doc 只跑文档测

设计动机

• 防文档撒谎
• 示例即教程
• 与 rustdoc 渲染一体

边界与误区

• 需要网络/密钥的示例要 ignore 并说明
• 二进制项目 doctest 行为差异
• 过长示例不适合塞进签名文档

[!warning] 常见误区：文档示例调用私有项 doctest 以外部用户视角。

工程实践

1. 公共函数至少一短例
2. CI 跑 --doc
3. 复杂教程放 book/examples
4. 失败即修文档或代码

本节总结

• 文档可执行
• cargo test 覆盖
• 公共 API 质量抓手

自测题

1. 为何 doctest 访问不了私有函数？
2. no_run 适用？

参考答案

1. 模拟外部用户。
2. 要展示能编译但不想执行的代码（如启服务器）。

延伸阅读与资料来源

资料	类型	支撑内容
The Book — Doc Comments	官方书	文档
rustdoc book	官方	rustdoc