diff --git a/src/chapter_3/chapter_3_19.md b/src/chapter_3/chapter_3_19.md index a060629..67bdde7 100644 --- a/src/chapter_3/chapter_3_19.md +++ b/src/chapter_3/chapter_3_19.md @@ -27,9 +27,10 @@ pub mod sub; ``` -3.17.2 文档测试 -1. 文档测试 +## 3.19.2 文档测试 +### 1. 文档测试 Rust运行在文档注释中写测试用例,示例如下: +```Rust /// `add` 将两个值相加 /// /// 下面是测试用例 @@ -41,10 +42,13 @@ Rust运行在文档注释中写测试用例,示例如下: pub fn add(left: u32, right: u32) -> u32 { left + right } +``` + 测试用例的内容用一对```包含,上面的代码在运行cargo test时,将会运行注释中的测试用例。 -2. 保留测试,隐藏注释 +### 2. 保留测试,隐藏注释 还可以保留文档测试的功能,但是把测试用例的内容在文档中隐藏起来,示例如下: +```Rust /// `add` 将两个值相加 /// /// 下面是测试用例 @@ -66,28 +70,46 @@ pub fn add(left: u32, right: u32) -> u32 { pub fn add2(left: u32, right: u32) -> Option { Some(left + right) } +``` + 运行cargo test,可以看到运行了用例add::add2,如下: -[图片] + +![注释](../../assets/44.png) + 运行cargo doc --open后,打开add和add2的文档,分别如下: -[图片] -[图片] + +![注释](../../assets/46.png) + +![注释](../../assets/45.png) + + 可以看到add2对应的测试用例的内容在文档中被隐藏了。 -3.17.3 文档注释中的其它技巧 -1. 跳转 -Rust文档注释中还可以进行跳转。在文档注释中用[``]包含的内容,可以对其进行跳转,示例如下: +## 3.19.3 文档注释中的其它技巧 +### 1. 跳转 +Rust文档注释中还可以进行跳转。在文档注释中用```[``]```包含的内容,可以对其进行跳转,示例如下: +```Rust + /// `sub` 返回一个[`Option`]类型 /// 跳转到[`crate::add`] pub fn sub(left: u32, right: u32) -> Option { Some(left - right) } +``` 运行cargo doc --open后,出现如下: -[图片] + +![注释](../../assets/42.png) + 从上图中,点击红色划线部分将分别跳转到标准库的Option和crate::add的位置。 -2. 文档搜索别名 + +### 2. 文档搜索别名 可以在Rust文档中为类型定义搜索别名,以便更好的进行搜索,示例如下: +```Rust #[doc(alias("x"))] pub struct A; +``` + 运行cargo doc --open后,出现如下: -[图片] + +![注释](../../assets/43.png)