From 6a6bccaefae5aec28b65e12e7dd6e3243ed847a2 Mon Sep 17 00:00:00 2001 From: jackymao Date: Mon, 26 Sep 2022 18:00:34 +0800 Subject: [PATCH] complete documentation tests --- .../1.rustdoc/rustdoc.md" | 4 +- .../unit_tests.md" | 2 + .../config.json" | 4 +- .../documentation_tests.json" | 7 ++ .../documentation_tests.md" | 106 ++++++++++++++++++ .../integration_tests.md" | 1 + 6 files changed, 121 insertions(+), 3 deletions(-) create mode 100644 "data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/documentation_tests.json" create mode 100644 "data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/documentation_tests.md" diff --git "a/data/1.rust\345\210\235\351\230\266/3.\346\226\207\346\241\243/1.rustdoc/rustdoc.md" "b/data/1.rust\345\210\235\351\230\266/3.\346\226\207\346\241\243/1.rustdoc/rustdoc.md" index 32ae51f..14f979a 100644 --- "a/data/1.rust\345\210\235\351\230\266/3.\346\226\207\346\241\243/1.rustdoc/rustdoc.md" +++ "b/data/1.rust\345\210\235\351\230\266/3.\346\226\207\346\241\243/1.rustdoc/rustdoc.md" @@ -1,6 +1,6 @@ # 文档 -Rust 社区非常重视文档，并提供了各种工具，使得文档形式多样，容易编写。Rust 文档支持 markdown，使用 rustdoc 解析并转换成 HTML，生成漂亮的、可搜索的文档页面。 +Rust 社区非常重视文档，并提供了各种工具，使得文档形式多样，容易编写。Rust 写文档的方式主要和源代码写在一起。Rust 文档支持 markdown，使用 rustdoc 解析并转换成 HTML，生成漂亮的、可搜索的文档页面。 首先，在每个库或可运行程序的 lib.rs 或 main.rs 文件最头部，会使用 ``` //! ``` 说明库的用途。 @@ -36,7 +36,7 @@ pub mod bar { 如果你需要单独的文档（使用 markdown 编写），而不是写在程序的注释里面，可以使用 [mdbook](https://github.com/rust-lang/mdBook) 这个工具。 -下面的文档测试代码使用有误的是： +下面的文档注释代码使用有误的是： ```rust diff --git "a/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/1.\345\215\225\345\205\203\346\265\213\350\257\225/unit_tests.md" "b/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/1.\345\215\225\345\205\203\346\265\213\350\257\225/unit_tests.md" index d6abff6..4116520 100644 --- "a/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/1.\345\215\225\345\205\203\346\265\213\350\257\225/unit_tests.md" +++ "b/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/1.\345\215\225\345\205\203\346\265\213\350\257\225/unit_tests.md" @@ -28,6 +28,8 @@ mod tests { A +## 选项 + ### A diff --git "a/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/config.json" "b/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/config.json" index ee50564..92aabc4 100644 --- "a/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/config.json" +++ "b/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/config.json" @@ -2,7 +2,9 @@ "node_id": "rust-2b4fef4327ad442fbb15c568f8638c31", "keywords": [], "children": [], - "export": [], + "export": [ + "documentation_tests.json" + ], "keywords_must": [], "keywords_forbid": [] } \ No newline at end of file diff --git "a/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/documentation_tests.json" "b/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/documentation_tests.json" new file mode 100644 index 0000000..ab72225 --- /dev/null +++ "b/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/documentation_tests.json" @@ -0,0 +1,7 @@ +{ + "type": "code_options", + "author": "jackymao_com", + "source": "documentation_tests.md", + "notebook_enable": false, + "exercise_id": "" +} \ No newline at end of file diff --git "a/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/documentation_tests.md" "b/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/documentation_tests.md" new file mode 100644 index 0000000..f61707f --- /dev/null +++ "b/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/2.\346\226\207\346\241\243\346\265\213\350\257\225/documentation_tests.md" @@ -0,0 +1,106 @@ +# 文档测试 + +据 Rust API 指南中的说明，Rust 的文档测试功能，主要的目的是作为练习函数使用的样例代码。同时也便于在代码更新后确保文档中测试代码正常运行。 + +考虑到看文档的人常会直接复制文档中的样例代码去运行，文档测试的代码要写得完善。 + +对写在文档中的代码片断， Rust 会隐式地在其中添加 `fn main()` 和 `extern crate ` 使之能正常编译。如测试样例的 main 函数返回的不是默认的单元类型，就需要明确的写出来完整的函数签名。 + +当文档测试中的代码比较长，不便于显示代码的功能，可以在文档中将部分代码隐藏，就是以 # 号加空格开头，这样可使显示出来的有功能性的代码片断更简洁。但隐藏的代码仍然会在运行测试的时候被编译。 + + +下面的文档测试中，能正确运行的是： + +## 答案 + +A + +```rust +/// 在文档测试中使用隐藏的 `try_main`。 +/// +/// ``` +/// # // 被隐藏的行以 `#` 开始 +/// # fn try_main() -> Result<(), String> { +/// let res = try::try_div(10, 2)?; +/// # Ok(()) // 从 try_main 返回 +/// # } +/// # fn 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) + } +} + +``` + +## 选项 + +### + +B + +```rust +/// # fn main() { +/// let res = try::try_div(10, 2)?; +/// # Ok(()) +/// # } +pub fn try_div(a: i32, b: i32) -> Result { + if b == 0 { + Err(String::from("Divide-by-zero")) + } else { + Ok(a / b) + } +} + +``` + + +### + +C + +```rust +/// fn main() { +/// let res = try::try_div(10, 2)?; +/// Ok(()) +/// } +pub fn try_div(a: i32, b: i32) -> Result { + if b == 0 { + Err(String::from("Divide-by-zero")) + } else { + Ok(a / b) + } +} + +``` + +### + +D + + +```rust +/// 在文档测试中使用隐藏的 `try_main`。 +/// +/// ``` +/// # // 被隐藏的行以 `#` 开始 +/// # fn try_main() { +/// let res = try::try_div(10, 2)?; +/// # Ok(()) // 从 try_main 返回 +/// # } +/// # fn main() -> Result<(), String> { // 开始主函数 +/// # 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) + } +} + +``` \ No newline at end of file diff --git "a/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/3.\351\233\206\346\210\220\346\265\213\350\257\225/integration_tests.md" "b/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/3.\351\233\206\346\210\220\346\265\213\350\257\225/integration_tests.md" index 61185bf..734dfca 100644 --- "a/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/3.\351\233\206\346\210\220\346\265\213\350\257\225/integration_tests.md" +++ "b/data/1.rust\345\210\235\351\230\266/4.\346\265\213\350\257\225/3.\351\233\206\346\210\220\346\265\213\350\257\225/integration_tests.md" @@ -14,6 +14,7 @@ Rust 会对 tests 目录里面的每一个文件当作单独的 crate 来编译, B +## 选项 ### 运行所有测试 -- GitLab