Rust从入门到实战系列一百五十七：将 crate 发布到 Crates.io

ch14-02-publishing-to-crates-io.md commit 7ddc28cfe0bfa6c531a6475c7fa41dfa66e8943c
我们曾经在项目中使用 crates.io 上的包作为依赖，不过你也可以通过发布自己的包来向他人分享代码。
crates.io 用来分发包的源代码，所以它主要托管开源代码。
Rust 和 Cargo 有一些帮助他人更方便找到和使用你发布的包的功能。我们将介绍一些这样的功能，接
着讲到如何发布一个包。
编写有用的文档注释
准确的包文档有助于其他用户理解如何以及何时使用他们，所以花一些时间编写文档是值得的。第三章
中我们讨论了如何使用两斜杠 ∕∕ 注释 Rust 代码。Rust 也有特定的用于文档的注释类型，通常被称为 文
档注释（documentation comments），他们会生成 HTML 文档。这些 HTML 展示公有 API 文档注释的内
容，他们意在让对库感兴趣的程序员理解如何 使用这个 crate，而不是它是如何被 实现的。
文档注释使用三斜杠 ∕∕∕ 而不是两斜杆以支持 Markdown 注解来格式化文本。文档注释就位于需要文档
的项的之前。示例 14-1 展示了一个 my_crate crate 中 add_one 函数的文档注释，
文件名: src∕lib.rs
/// Adds one to the number given.
///
/// # Examples
///
/// /// let arg = 5; /// let answer = my_crate::add_one(arg); /// /// assert_eq!(6, answer); ///
pub fn add_one(x: i32) -> i32 {
x + 1
}
示例 14-1：一个函数的文档注释
这里，我们提供了一个 add_one 函数工作的描述，接着开始了一个标题为 Examples 的部分，和展示如
何使用 add_one 函数的代码。可以运行 cargo doc 来生成这个文档注释的 HTML 文档。这个命令运行
由 Rust 分发的工具 rustdoc 并将生成的 HTML 文档放入 target∕doc 目录。
为了方便起见，运行 cargo doc −−open 会构建当前 crate 文档（同时还有所有 crate 依赖的文档）的
HTML 并在浏览器中打开。导航到 add_one 函数将会发现文档注释的文本是如何渲染的，如图 14-1 所示：
常用（文档注释）部分
示例 14-1 中使用了 # Examples Markdown 标题在 HTML 中创建了一个以 ”Examples” 为标题的部分。
其他一些 crate 作者经常在文档注释中使用的部分有：
• Panics：这个函数可能会 panic! 的场景。并不希望程序崩溃的函数调用者应该确保他们不会在这
些情况下调用此函数。
• Errors：如果这个函数返回 Result，此部分描述可能会出现何种错误以及什么情况会造成这些错
误，这有助于调用者编写代码来采用不同的方式处理不同的错误。
• Safety：如果这个函数使用 unsafe 代码（这会在第十九章讨论），这一部分应该会涉及到期望函
数调用者支持的确保 unsafe 块中代码正常工作的不变条件（invariants）。
大部分文档注释不需要所有这些部分，不过这是一个提醒你检查调用你代码的人有兴趣了解的内容的列
表。
文档注释作为测试
在文档注释中增加示例代码块是一个清楚的表明如何使用库的方法，这么做还有一个额外的好处：
cargo test 也会像测试那样运行文档中的示例代码！没有什么比有例子的文档更好的了，但最糟糕的莫
过于写完文档后改动了代码，而导致例子不能正常工作。尝试 cargo test 运行像示例 14-1 中 add_one
函数的文档；应该在测试结果中看到像这样的部分：
Doc-tests my_crate
running 1 test
test src/lib.rs - add_one (line 5) … ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in
现在尝试改变函数或例子来使例子中的 assert_eq! 产生 panic。再次运行 cargo test，你将会看到文档
测试捕获到了例子与代码不再同步！