文档测试
经过测试的示例
文档测试 是 CoddyKit 上的免费 Learn Rust Coding 课时。 这是第 4 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Learn Rust Coding 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Learn Rust Coding 课程共包含 4 节课。
什么是文档测试
文档测试是文档注释中的代码示例，Cargo 会实际编译并运行它们。它们可以确保文档正确且示例能够正常工作。
文档注释中的代码
在 /// 注释中的围栏代码块（三个反引号）内放置示例代码，并置于 # Examples 标题下。默认语言是 Rust。
/// Doubles a number.
///
/// # Examples
///
/// let result = my_crate::double(4);
/// assert_eq!(result, 8);
pub fn double(n: i32) -> i32 {
n * 2
}运行文档测试
文档测试会作为 cargo test 的一部分运行。它们会在 Doc-tests 部分单独报告。
cargo test示例中的断言
示例通常包含断言，这样错误的示例会导致测试失败，而不仅仅是无法编译。
/// Returns the larger of two values.
///
/// # Examples
///
/// assert_eq!(my_crate::max(3, 7), 7);
/// assert_eq!(my_crate::max(9, 2), 9);
pub fn max(a: i32, b: i32) -> i32 {
if a > b { a } else { b }
}隐藏设置代码行
在行首添加 #，即可运行该行，但在渲染后的文档中将其隐藏。这对于导入等样板代码很有用。
/// # Examples
///
/// # use my_crate::Counter;
/// let mut c = Counter::new();
/// c.increment();
/// assert_eq!(c.value(), 1);使用问号的示例
要使用 ? 运算符，请将主体包装在一个隐藏的 main（或辅助函数）中，并使其返回 Result。隐藏行以 # 开头。
/// # Examples
///
/// # fn run() -> Result<(), std::num::ParseIntError> {
/// let n: i32 = "42".parse()?;
/// assert_eq!(n, 42);
/// # Ok(())
/// # }no_run 示例
使用 no_run 注解标记围栏代码块，可以编译该代码，但不执行它——这对于需要网络或文件的示例很方便。
/// Fetches a page (compiled but not executed).
///
/// Annotate the code fence with no_run so it is type-checked only.
pub fn fetch(url: &str) -> String {
format!("contents of {url}")
}ignore 和 should_panic
代码围栏还支持以下注解：
ignore——既不编译也不运行should_panic——预期会引发 paniccompile_fail——预期无法编译
为什么文档测试很重要
文档测试可以同时带来两项好处：
- 始终准确的文档
- 为公共示例免费提供测试覆盖
如果示例失效，测试套件就会失败。
示例中的 crate 名称
文档测试的运行方式就像代码位于 crate 外部，因此请通过 crate 名称（例如 my_crate::func）或 use 导入来引用项目。
围栏代码块与缩进代码块
文档测试接受两种代码块样式：
- 使用三个反引号的围栏代码块，可使用
no_run等注解 - 缩进代码块（四个空格），本示例使用的就是这种形式
在实际代码中，围栏代码块更常见。
快速检查
文档测试代码块中，以 # 开头的行有什么作用？
回顾
您学习了文档测试：
///块中的代码会由cargo test编译并运行- 使用断言验证行为
#会将设置代码行从渲染后的文档中隐藏- 注解：
no_run、ignore、should_panic、compile_fail - 它们会自动确保示例保持正确
常见问题解答
「文档测试」课时是免费的吗？
是的 — 「文档测试」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Learn Rust Coding 课程的其余内容，请升级到 CoddyKit PRO。 Learn Rust Coding 课程共包含 4 节课。
「文档测试」这节课中我会学到什么？
经过测试的示例 你通过在浏览器中直接运行的动手代码来练习 Learn Rust Coding，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 Learn Rust Coding 需要有经验吗？
无需任何先前经验。CoddyKit 上的 Learn Rust Coding 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 4 节课，共 4 节。
「文档测试」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 Learn Rust Coding 课中编写并运行代码吗？
能。每节 Learn Rust Coding 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。