第24章 补充
在软件工程中，有些主题和写程序并没有直接的关联，但它们为你提供了工具和基础设施支持，使得软件对每个人都变得更易用。这些主题包括：
- 文档：通过附带的
rustdoc生成库文档给用户。 - 测试：为库创建测试套件，确保库准确地实现了你想要的功能。
- 基准测试（benchmark）：对功能进行基准测试，保证其运行速度足够快。
文档
用 cargo doc 构建文档到 target/doc。
用 cargo test 运行所有测试（包括文档测试），用 cargo test --doc 仅运行文档测试。
这些命令会恰当地按需调用 rustdoc（以及 rustc）。
文档注释
文档注释对于需要文档的大型项目来说非常重要。当运行 rustdoc，文档注释就会编译成文档。它们使用 /// 标记，并支持 Markdown。
#![crate_name = "doc"]
/// 这里给出一个“人”的表示
pub struct Person {
/// 一个人必须有名字（不管 Juliet 多讨厌她自己的名字）。
name: String,
}
impl Person {
/// 返回具有指定名字的一个人
///
/// # 参数
///
/// * `name` - 字符串切片，代表人的名字
///
/// # 示例
///
/// ```
/// // 在文档注释中，你可以书写代码块
/// // 如果向 `rustdoc` 传递 --test 参数，它还会帮你测试注释文档中的代码！
/// use doc::Person;
/// let person = Person::new("name");
/// ```
pub fn new(name: &str) -> Person {
Person {
name: name.to_string(),
}
}
/// 给一个友好的问候！
/// 对被叫到的 `Person` 说 "Hello, [name]" 。
pub fn hello(& self) {
println!("Hello, {}!", self.name);
}
}
fn main() {
let john = Person::new("John");
john.hello();
}
要运行测试，首先将代码构建为库，然后告诉 rustdoc 在哪里找到库，这样它就可以使每个文档中的程序链接到库：
$ rustc doc.rs --crate-type lib
$ rustdoc --test --extern doc="libdoc.rlib" doc.rs
文档属性
下面是一些使用 rustdoc 时最常使用的 #[doc] 属性的例子。
inline
用于内联文档，而不是链接到单独的页面。
#[doc(inline)]
pub use bar::Bar;
/// bar 的文档
mod bar {
/// Bar 的文档
pub struct Bar;
}
no_inline
用于防止链接到单独的页面或其他位置。
// 来自 libcore/prelude 的例子
#[doc(no_inline)]
pub use crate::mem::drop;
hidden
使用此属性来告诉 rustdoc 不要包含此项到文档中：
// 来自 futures-rs 库的例子
#[doc(hidden)]
pub use self::async_await::*;
对文档来说，rustdoc 被社区广泛采用。标准库文档也是用它生成的。
参见:
- The Rust Book: Making Useful Documentation Comments
- The rustdoc Book
- The Reference: Doc comments
- RFC 1574: API Documentation Conventions
- RFC 1946: Relative links to other items from doc comments (intra-rustdoc links)
- Is there any documentation style guide for comments? (reddit)
Playpen
Rust Playpen 是一个在线运行 Rust 代码的网络接口。现在该项目通常称为 Rust Playground。
在 mdbook 使用
在 mdbook 中，你可以让示例代码运行和编辑。
fn main() { println!("Hello World!"); }
这使读者既可以运行你的代码示例，也可以对其进行修改和调整。此处的关键是将单词添加 editable 到代码块中，并用逗号分隔。
```rust,editable
//...将你的代码写在这里
```
此外，如果想要 mdbook 在构建和测试时跳过该代码，则可以添加 ignore。
```rust,editable,ignore
//...将你的代码写在这里
```
在文档中使用
可能你已经在某些 Rust 官方文档中注意到了一个名为 “Run” 的按钮，该按钮在 Rust Playground 的新选项卡中打开了代码示例。如果使用名为的 html_playground_url 的 #[doc] 属性，则启用此功能。