docs: reformat the document

YangFong · YangFong · commit 6ccc5d1abd39 · 2022-02-04T19:57:30.000+08:00
diff --git a/src/how-to-read-rustdoc.md b/src/how-to-read-rustdoc.md
@@ -4,35 +4,33 @@ Rustdoc 的 HTML 文件包含了有用的跳转入口，便于用户跳转理解
 
 ## 结构
 
-`rustdoc`的输出包含三部分，左侧是整个页面的快速导航，展示了当前条目的上下文信息。页面的右侧大版面由顶部的搜索和下面的文档页面主体组成。
+`rustdoc` 的输出包含三部分，左侧是整个页面的快速导航，展示了当前条目的上下文信息。页面的右侧大版面由顶部的搜索和下面的文档页面主体组成。
 
 ## Item 文档
 
 屏幕的主要区域展示的是 item 的文档。
 
 顶端是一览信息：
-- item 的类型和名称，比如 "Struct `std::time::Duration`",
-- 复制 crate 路径的按钮
-- 展开和收起 item 顶层文档的按钮 (`[+]` or `[-]`),
-- 如果 [configured](the-doc-attribute.html#html_no_source), 并且可以展示（如果文档创建通过 `cargo doc --no-deps` 源码可能是无效的），
-  会有源码的连接 (`[src]`),
-- 如果 item 是标准库，会展示 item 稳定的版本
+
+- item 的类型和名称，比如 "Struct `std::time::Duration`"；
+- 复制 crate 路径的按钮；
+- 展开和收起 item 顶层文档的按钮 (`[+]` or `[-]`)；
+- 如果 [configured](the-doc-attribute.html#html_no_source), 并且可以展示（如果文档创建通过 `cargo doc --no-deps` 源码可能是无效的），会有源码的连接 (`[src]`)；
+- 如果 item 是标准库，会展示 item 稳定的版本。
 
 下面是 item 的主要文档，包括函数签名，Rust 类型的 fields 列表或者 variants。最后页面列出关联的函数以及 trait 实现，包括 `rustdoc` 知道的自动和空白实现。
 
 ### 导航
 
-subheadings， variants，fields 和文档中很多元素都是锚，可以被链接，这是可以准确传递你表达的好方法。当悬停或给定键盘焦点时，印刷符号"§" 出现在带有锚点的行旁边。
+subheadings，variants，fields 和文档中很多元素都是锚，可以被链接，这是可以准确传递你表达的好方法。当悬停或给定键盘焦点时，印刷符号 "§" 出现在带有锚点的行旁边。
 
 ## 导航栏
 
-比如，当查看 crate 根文档的时候，会展示所有的 crate 文档的 modules，structs，traits，functions，macros 的快速链接。
-顶部，在当前 crate 名称和版本旁边或者当前 item 旁边展示 [configurable logo](the-doc-attribute.html#html_logo_url)。
+比如，当查看 crate 根文档的时候，会展示所有的 crate 文档的 modules，structs，traits，functions，macros 的快速链接。顶部，在当前 crate 名称和版本旁边或者当前 item 旁边展示 [configurable logo](the-doc-attribute.html#html_logo_url)。
 
 ## 主题选择和搜索栏
 
-当在支持 JavaScript 的浏览器中打开 `rustdoc` 的输出时，页面顶部会出现一个接口，左侧是主题选择（一个画笔图标），搜索栏，帮助提示和配置按钮
-【译者注：主题选择已经在配置设置中】
+当在支持 JavaScript 的浏览器中打开 `rustdoc` 的输出时，页面顶部会出现一个接口，左侧是主题选择（一个画笔图标），搜索栏，帮助提示和配置按钮。【译者注：主题选择已经在配置设置中】
 
 ### 主题选择
 
@@ -46,12 +44,12 @@ subheadings， variants，fields 和文档中很多元素都是锚，可以被
 
 还有两种结果，按照参数搜索，展示函数参数中类型的匹配结果，按返回值搜索，展示函数返回值类型的搜索结构。这两种搜索结果在你不知道函数名称，但是知道你想要的类型时非常有用。
 
-当在搜索栏输入时，可以通过冒号前缀来限制搜索结果的类型（比如`mod:`）
+当在搜索栏输入时，可以通过冒号前缀来限制搜索结果的类型（比如 `mod:`）
 
 ### 快捷键
 
-按下`S`焦点会移动到搜索框，按下`?`会展示帮助界面，其中包括所有快捷键以及说明。按下`T`焦点移动到主题选择。【译者注：主题选择通过搜索栏的右侧 setting 按钮唤出】
+按下 `S` 焦点会移动到搜索框，按下 `?` 会展示帮助界面，其中包括所有快捷键以及说明。按下 `T` 焦点移动到主题选择。【译者注：主题选择通过搜索栏的右侧 setting 按钮唤出】
 
 当焦点在搜索结果时，左右箭头可以切换搜索的 tab，上下箭头可以移动关注的搜索结果。按下回车键可以打开高亮的结果。
 
-当焦点在 item 文档时，加号和减号可以展开收起文档的小结
+当焦点在 item 文档时，加号和减号可以展开收起文档的小结。
diff --git a/src/how-to-write-documentation.md b/src/how-to-write-documentation.md
@@ -1,36 +1,27 @@
 # 如何写文档
 
-好的文档并不自然。存在一些矛盾的目标使得写好文档很困难。即要求对领域很专业又要写出对新手很友好的文档。
-文档因此经常隐去一些细节，或者留给读者一些未解答的问题。
+好的文档并不自然。存在一些矛盾的目标使得写好文档很困难。即要求对领域很专业又要写出对新手很友好的文档。文档因此经常隐去一些细节，或者留给读者一些未解答的问题。
 
 Rust 文档有一些原则指导任何人来写文档，从而每个人都有机会来使用代码。
 
-本章不仅覆盖如何编写文档，还介绍了如何写出**好**文档。尽可能清晰完整非常重要。根据经验：
-你编写的文档越多你的 crate 越好。如果 item 是公共的，就应该有文档。
+本章不仅覆盖如何编写文档，还介绍了如何写出**好**文档。尽可能清晰完整非常重要。根据经验：你编写的文档越多你的 crate 越好。如果 item 是公共的，就应该有文档。
 
 ## 开始
 
-编写 crate 文档首先应该从首页开始。例如 [`hashbrown`] crate 级别的文档总结了这个 crate 的角色是什么，
-说明了使用的详细技术，以及为什么你需要这个 crate。
+编写 crate 文档首先应该从首页开始。例如 [`hashbrown`] crate 级别的文档总结了这个 crate 的角色是什么，说明了使用的详细技术，以及为什么你需要这个 crate。
 
 在介绍了 crate 之后，首页给出使用 crate 的代码示例很重要。在代码例子中展示库如何使用，不要使用裁剪过的代码，
 使得用户可以直接复制粘贴就能运行。
 
-[`futures`] 使用内联注释逐行解释使用 [`Future`] 的复杂性，因为用户接触
-rust 的 [`Future`] 的第一个例子可能就是这个。
+[`futures`] 使用内联注释逐行解释使用 [`Future`] 的复杂性，因为用户接触 rust 的 [`Future`] 的第一个例子可能就是这个。
 
-[`backtrace`] 文档描述了整个使用过程，说明了`Cargo.toml`文件应该如何修改，传递命令行参数
-给编译器，并展示了一个使用 backtrace 的例子。
+[`backtrace`] 文档描述了整个使用过程，说明了 `Cargo.toml` 文件应该如何修改，传递命令行参数给编译器，并展示了一个使用 backtrace 的例子。
 
-最后，首页会成为如何使用 crate 的综合参考，就像 [`regex`]。
-在这个首页，所有的依赖被列出，边缘情况被列出，实际例子被列出。然后首页继续展示如何使用正则表达式，然后还列出了
-crate 的特性。
+最后，首页会成为如何使用 crate 的综合参考，就像 [`regex`]。在这个首页，所有的依赖被列出，边缘情况被列出，实际例子被列出。然后首页继续展示如何使用正则表达式，然后还列出了 crate 的特性。
 
-不要担心你的新 crate 与已经开发一段时间的 crate 比较。要是文档逐步完善，请逐步开始添加介绍，示例和特性。罗马不是
-一天建成的！
+不要担心你的新 crate 与已经开发一段时间的 crate 比较。要是文档逐步完善，请逐步开始添加介绍，示例和特性。罗马不是一天建成的！
 
-`lib.rs` 的第一行开始会是首页，它们与 rustdoc 其他部分不同，要以`//!`开始表明这是模块级别或者 crate 级别的文档。
-这是一个简单的例子：
+`lib.rs` 的第一行开始会是首页，它们与 rustdoc 其他部分不同，要以 `//!` 开始表明这是模块级别或者 crate 级别的文档。这是一个简单的例子：
 
 ```rust,no_run
 //! Fast and easy queue abstraction.
@@ -56,7 +47,7 @@ pub mod easy {
 
 ## 文档组成
 
-无论是 modules, structs, funtions, macros： 代码的公共 API 都应该有文档。很少有人嫌弃文档太多！
+无论是 modules, structs, funtions, macros：代码的公共 API 都应该有文档。很少有人嫌弃文档太多！
 
 每个 item 的文档应该都以下面的结构构成：
 
@@ -76,7 +67,7 @@ pub mod easy {
 让我们看一个来自 [standard library] 的例子，
 [`std::env::args()`][env::args] 函数：
 
-``````markdown
+````markdown
 Returns the arguments which this program was started with (normally passed
 via the command line).
 
@@ -106,25 +97,22 @@ for argument in env::args() {
 ```
 
 [`args_os`]: ./fn.args_os.html
-``````
+````
 
-在第一个空行之间的所有内容都会被用于搜索和模块的简介。比如，上面的`std::enve::args()`函数就会在展示在 [`std::env`] 模块文档中。
-将摘要保持在一行是良好习惯：简介是好文档的目标。
+在第一个空行之间的所有内容都会被用于搜索和模块的简介。比如，上面的 `std::enve::args()` 函数就会在展示在 [`std::env`] 模块文档中。将摘要保持在一行是良好习惯：简介是好文档的目标。
 
-因为类型系统很好定义了函数的参数和返回值类型，所以将其显式写入文档没有好处，
-尤其是`rustdoc`会自动在函数签名中添加指向类型的超链接。
+因为类型系统很好定义了函数的参数和返回值类型，所以将其显式写入文档没有好处，尤其是 `rustdoc` 会自动在函数签名中添加指向类型的超链接。
 
-在上面的例子中，`Panics`小节解释了代码何时可能会意外退出，
-可以帮助读者规避 panic。如果你知道代码的边缘情况，尽可能增加 panic 小节。
+在上面的例子中，`Panics` 小节解释了代码何时可能会意外退出，可以帮助读者规避 panic。如果你知道代码的边缘情况，尽可能增加 panic 小节。
 
 如同你所看到的，它遵循了给出的结构建议：简短描述函数的作用，然后提供了更多信息以及最后提供了代码示例。
 
 ## Markdown
 
-`rustdoc`使用 [CommonMark Markdown specification]。你可能会对它们的网站感兴趣：:
+`rustdoc` 使用 [CommonMark Markdown specification]。你可能会对它们的网站感兴趣：
 
- - [CommonMark quick reference]
- - [current spec]
+- [CommonMark quick reference]
+- [current spec]
 
 补充了标准 CommonMark 语法， `rustdoc` 支持几种扩展：
 
@@ -140,7 +128,7 @@ An example of ~~strikethrough text~~.
 
 > An example of ~~strikethrough text~~.
 
-这使用 [GitHub Strikethrough extension][strikethrough].
+这使用 [GitHub Strikethrough extension][strikethrough]。
 
 ### Footnotes（角标）
 
@@ -157,7 +145,8 @@ This is an example of a footnote[^note].
 
 > This is an example of a footnote[^note].
 >
-> [^note]: This text is the contents of the footnote, which will be rendered
+> [^note]:
+>     This text is the contents of the footnote, which will be rendered
 >     towards the bottom.
 
 角标数字会根据角标位置自动生成。
@@ -175,7 +164,7 @@ This is an example of a footnote[^note].
 这个例子会被渲染成类似这样：
 
 > | Header1 | Header2 |
-> |---------|---------|
+> | ------- | ------- |
 > | abc     | def     |
 
 阅读 [GitHub Tables extension][tables] 的说明获取更多细节。
@@ -201,11 +190,11 @@ This is an example of a footnote[^note].
 
 一些 ASCII 符号可以自动转换为更好看的 Unicode 符号：
 
-| ASCII sequence | Unicode |
-|----------------|---------|
-| `--`           | –       |
-| `---`          | —       |
-| `...`          | …       |
+| ASCII sequence | Unicode                      |
+| -------------- | ---------------------------- |
+| `--`           | –                            |
+| `---`          | —                            |
+| `...`          | …                            |
 | `"`            | “ or ”, depending on context |
 | `'`            | ‘ or ’, depending on context |
 
diff --git a/src/what-is-rustdoc.md b/src/what-is-rustdoc.md
@@ -9,7 +9,7 @@
 > - <a href="https://rustwiki.org/en/rustdoc/" style="color:red;">本站支持文档中英文切换</a>，点击页面右上角语言图标可切换到相同章节的英文页面，**英文版每天都会自动同步一次官方的最新版本**。
 > - 若发现当前页表达错误或帮助我们改进翻译，可点击右上角的编辑按钮打开该页对应源码文件进行编辑和修改，Rust 中文资源的开源组织发展离不开大家，感谢您的支持和帮助！
 
-标准 Rust 版本包含了名为 `rustdoc` 的工具。它的作用是为 Rust 项目生成文档，Rustdoc 接受一个 crate 根目录或者一个 markdown 文件作为参数，生成 HTML，CSS 和 Javascript 文件。
+标准 Rust 版本包含了名为 `rustdoc` 的工具。它的作用是为 Rust 项目生成文档，Rustdoc 接受一个 crate 根目录或者一个 markdown 文件作为参数，生成 HTML，CSS 和 JavaScript 文件。
 
 ## 基本使用
 
@@ -27,26 +27,27 @@ $ cd docs
 fn foo() {}
 ```
 
-然后我们运行 `rustdoc` 。我们可以在 crate 根目录执行下面的命令
+然后我们运行 `rustdoc`。我们可以在 crate 根目录执行下面的命令
 
 ```bash
 $ rustdoc src/lib.rs
 ```
-这会创建一个新目录`doc`，其中是一个网站结构。在我们的例子中，主页面是 `doc/lib/index.html`。如果你使用浏览器打开，可以在 tab 栏看到 "Crate lib"，页面没有内容。
+
+这会创建一个新目录 `doc`，其中是一个网站结构。在我们的例子中，主页面是 `doc/lib/index.html`。如果你使用浏览器打开，可以在 tab 栏看到 "Crate lib"，页面没有内容。
 
 ## 配置 rustdoc
 
 现在有两个问题：第一，为什么我们的包名字是 "lib"？第二，为什么没有任何内容？
 
-第一个问题的原因是因为`rustdoc`试图更好用，像`rustc`就假定我们 crate 的名字就是 crate 根目录文件的名字。为了修复这个问题，可以通过命令行传递参数：
+第一个问题的原因是因为 `rustdoc` 试图更好用，像 `rustc` 就假定我们 crate 的名字就是 crate 根目录文件的名字。为了修复这个问题，可以通过命令行传递参数：
 
 ```bash
 $ rustdoc src/lib.rs --crate-name docs
 ```
 
 现在， `doc/docs/index.html` 文件生成，页面名称为 "Crate docs"。
 
-对于第二个问题，因为我们的函数`foo`不是公共的；`rustdoc`默认只会为公共函数生成文档，如果我们将代码修改为
+对于第二个问题，因为我们的函数 `foo` 不是公共的；`rustdoc` 默认只会为公共函数生成文档，如果我们将代码修改为
 
 ```rust
 /// foo is a function
@@ -59,41 +60,41 @@ pub fn foo() {}
 $ rustdoc src/lib.rs --crate-name docs
 ```
 
-现在我们生成了文档，打开`doc/docs/index.html`，显示了`foo`函数的连接页面，文件位置是`doc/docs/fn.foo.html`。在函数的页面上，你可以看到我们写的注释"foo is a function"。
+现在我们生成了文档，打开 `doc/docs/index.html`，显示了 `foo` 函数的连接页面，文件位置是 `doc/docs/fn.foo.html`。在函数的页面上，你可以看到我们写的注释 "foo is a function"。
 
 ## 通过 Cargo 使用 rustdoc
 
-Cargo 整合了`rustdoc`，使得生成文档更容易。代替`rustdoc`命令，我们可以这样做：
+Cargo 整合了 `rustdoc`，使得生成文档更容易。代替 `rustdoc` 命令，我们可以这样做：
 
 ```bash
 $ cargo doc
 ```
 
-实际上，会这样调用`rustdoc`:
+实际上，会这样调用 `rustdoc`:
 
 ```bash
 $ rustdoc --crate-name docs src/lib.rs -o <path>/docs/target/doc -L
 dependency=<path>/docs/target/debug/deps
 ```
 
-你可以使用`cargo doc --verbose`看到这个过程。
+你可以使用 `cargo doc --verbose` 看到这个过程。
 
-它会自动生成正确的 crate 名称`--crate-name`，同时指向`src/lib.rs`。但是其他的参数表示什么呢？
+它会自动生成正确的 crate 名称 `--crate-name`，同时指向 `src/lib.rs`。但是其他的参数表示什么呢？
 
- - `-o` 控制文档的输出。不使用顶层的`doc` 目录，Cargo 会把生成的文档生成在  `target`。这是 Cargo 项目的惯用生成文件的位置。
- - `-L` 帮助 rustdoc 找到代码的依赖，如果我们的项目有依赖，也会生成依赖的文档。
+- `-o` 控制文档的输出。不使用顶层的 `doc` 目录，Cargo 会把生成的文档生成在 `target`。这是 Cargo 项目的惯用生成文件的位置。
+- `-L` 帮助 rustdoc 找到代码的依赖，如果我们的项目有依赖，也会生成依赖的文档。
 
 ## Outer 和 inner 文档
 
 `///` 语法用来对下面一个 item 生成文档，所以称为 outer 文档。还有语法`//!`，用来生成 item 内部的文档，也叫做 inner 文档，通常用来对整个 crate 生成文档，因为是 crate 的根，没有 item 在前面。所以为了生成整个 crate 的文档，你需要这样用 `//!`：
 
-``` rust
+```rust
 //! This is my first rust crate
 ```
 
 当这样用的时候，会生成 item 内部的文档，也就是 crate 自己。
 
-为了获取更多`//!`的信息，请看 [the Book]( https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#commenting-contained-items)
+为了获取更多 `//!` 的信息，请看 [the Book](https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#commenting-contained-items)
 
 ## 利用单独的 Markdown 文件
 
@@ -121,13 +122,13 @@ fn foo() -> i32 {
 $ rustdoc README.md
 ```
 
-你能发现生成的`docs/doc/README.html`文件。
+你能发现生成的 `docs/doc/README.html` 文件。
 
 不过现在 Cargo 不能这样操作 markdown 文件。
 
 ## 总结
 
-本节涵盖了`rustdoc`的基本使用方法。本书的剩余部分会展示`rustdoc`所有的可选功能，以及如何使用它们。
+本节涵盖了 `rustdoc` 的基本使用方法。本书的剩余部分会展示 `rustdoc` 所有的可选功能，以及如何使用它们。
 
 [website]: https://doc.rust-lang.org/rustdoc/
 [book-cn]: https://rustwiki.org/zh-CN/book/
diff --git a/src/what-to-include.md b/src/what-to-include.md
@@ -35,7 +35,7 @@ warning: 1 warning emitted
 
 作为一个库作者，加入 lint `#![deny(missing_docs)]` 是一个确保项目拥有良好文档的好方法，`#![warn(missing_docs)]` 是通向良好文档的好方法。除了文档，`#![deny(missing_doc_code_examples)]` 确保每个函数有一个使用示例。在我们上面的例子中，添加 crate 级别的 lint 来警告。
 
-下面的章节有更多 lints 的细节 [Lints][rustdoc-lints].
+下面的章节有更多 lints 的细节 [Lints][rustdoc-lints]。
 
 ## 例子
 
@@ -45,17 +45,17 @@ warning: 1 warning emitted
 
 最好不要在例子中使用 `unwrap()`，并且如果错误处理使得例子难以理解应该被隐藏起来。
 
-``````text
+````text
 /// Example
 /// ```rust
 /// let fourtytwo = "42".parse::<u32>()?;
 /// println!("{} + 10 = {}", fourtytwo, fourtytwo+10);
 /// ```
-``````
+````
 
 当 rustdoc wrap 这些到 main 函数中，会编译错误因为 `ParseIntError` trait 没有实现。为了同时帮助读者和测试，这个例子还需要增加些额外代码：
 
-``````text
+````text
 /// Example
 /// ```rust
 /// # main() -> Result<(), std::num::ParseIntError> {
@@ -64,7 +64,7 @@ warning: 1 warning emitted
 /// #     Ok(())
 /// # }
 /// ```
-``````
+````
 
 这两个例子在文档页面是相同的，但是对你 crate 的使用者有一些额外的信息。更多的文档测试内容在接下来的 [文档测试] 章节中。
 
