文档测试

为 Rust 工程编写文档的主要方式是在源代码中写注释。文档注释使用 markdown 语法 书写，支持代码块。Rust 很注重正确性，这些注释中的代码块也会被编译并且用作测试。

  1. /// 第一行是对函数的简短描述。
  2. ///
  3. /// 接下来数行是详细文档。代码块用三个反引号开启，Rust 会隐式地在其中添加
  4. /// `fn main()` 和 `extern crate <cratename>`。比如测试 `doccomments` crate：
  5. ///
  6. ///

/// let result = doccomments::add(2, 3); /// assert_eq!(result, 5); /// ``` pub fn add(a: i32, b: i32) -> i32 { a + b }

/// 文档注释通常可能带有 “Examples”、”Panics” 和 “Failures” 这些部分。 /// /// 下面的函数将两数相除。 /// /// # Examples /// /// /// let result = doccomments::div(10, 2); /// assert_eq!(result, 5); /// /// /// # Panics /// /// 如果第二个参数是 0，函数将会 panic。 /// /// rust,should_panic /// // panics on division by zero /// doccomments::div(10, 0); /// pub fn div(a: i32, b: i32) -> i32 { if b == 0 { panic!(“Divide-by-zero error”); }

  1. a / b

}

  2. 这些测试仍然可以通过 `cargo test` 执行：
  4. ```bash
  5. $ cargo test
  6. running 0 tests
  8. test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
  10.    Doc-tests doccomments
  12. running 3 tests
  13. test src/lib.rs - add (line 7) ... ok
  14. test src/lib.rs - div (line 21) ... ok
  15. test src/lib.rs - div (line 31) ... ok
  17. test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

文档测试的目的

文档测试的主要目的是作为使用函数功能的例子，这是最重要的指导 原则之一。文档测试应当可以作为完整的代码段被直接 使用（很多用户会复制文档中的代码来用，所以例子要写得完善）。但使用 ? 符号会 导致编译失败，因为 main 函数会返回 unit 类型。幸运的是，我们可以在文档中 隐藏几行源代码：你可以写 fn try_main() -> Result<(), ErrorType> 这样的 函数，把它隐藏起来，然后在隐藏的 main 中展开它。听起来很复杂？请看例子：

  1. /// 在文档测试中使用隐藏的 `try_main`。
  2. ///
  3. ///

/// # // 被隐藏的行以 # 开始，但它们仍然会被编译！ /// # fn try_main() -> Result<(), String> { // 隐藏行包围了文档中显示的函数体 /// let res = try::try_div(10, 2)?; /// # Ok(()) // 从 try_main 返回 /// # } /// # fn main() { // 开始主函数，其中将展开 try_main 函数 /// # try_main().unwrap(); // 调用并展开 try_main，这样出错时测试会 panic /// # } pub fn try_div(a: i32, b: i32) -> Result { if b == 0 { Err(String::from(“Divide-by-zero”)) } else { Ok(a / b) } } ```

参见