14.2 文档注释以及发布 crate

14.2.1 crates.io

crates.io 是面向 Rust 编程语言的官方包管理平台，类似于其他语言的包管理器（如 npm 对于 JavaScript，pip 对于 Python）。它的主要作用包括：

托管 Rust 库（crate）： 开发者可以在 crates.io 上发布自己的 Rust 库，其他开发者可以下载并使用这些库。
依赖管理： Rust 的构建工具和包管理器 Cargo 会从 crates.io 下载所需的依赖包，用于简化项目开发。
搜索和发现： 用户可以在 crates.io 上搜索已有的库，找到适合自己项目需求的解决方案。
版本控制和更新： crates.io 支持版本管理，开发者可以上传新版本的库，用户也可以轻松更新依赖。

在第二章的猜数游戏中，我们就使用了 crates.io 中的第三方 rand crate 来获取随机数。我们不仅可以使用他人提供的 crate，也可以发布自己的 crate 到 crates.io 供他人使用。

Rust 和 Cargo 具有使你发布的包更容易被人们找到和使用的功能。接下来我们将讨论其中一些功能，然后解释如何发布包。

14.2.2 文档注释

使用 /// 来写文档注释。文档注释用于生成项目的文档，它不同于 //，// 用于代码的标注，而文档注释说明的是紧跟其后的那个条目（通常是公共 API）。

这种文档是 HTML 文档，支持 Markdown 格式，它会显示公共 API 的文档注释，通常是教读者如何使用 API。

一般文档注释放置在被说明条目之前。

看个例子：

#![allow(unused)]
fn main() {
/// 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
}
}

PS：在 Markdown 中，# 是标题的标记，``` 是代码块的标记。

14.2.3 生成 HTML 文档的命令

在终端中运行 cargo doc 会使用 Rust 自带的 rustdoc 工具来生成文档。它会把生成的文档放在 target/doc 目录下。

cargo doc --open 会生成文档并在网页浏览器中打开结果： my_crate::add_one 的 rustdoc 文档页，含函数签名、说明与 Examples

14.2.4 常用章节

以下是 crate 作者在其文档中常用的一些部分：

# Examples 是示例部分，下面的代码块放示例代码。
# Panics：正在记录的函数可能会出现恐慌的情况。不希望程序出现恐慌的函数调用者应确保在这些情况下不会调用该函数。
# Errors：如果函数返回 Result，则描述可能发生的错误类型以及可能导致返回这些错误的条件对调用者很有帮助，以便他们可以编写代码以不同的方式处理不同类型的错误。
# Safety：如果函数调用 unsafe（以后会讲），应该有一个部分解释为什么该函数不安全，并涵盖该函数期望调用者维护的不变量。

14.2.5 文档注释作为测试

文档注释中的代码块会在执行 cargo test 命令时作为测试来调用，会在测试结果中看到这部分：

   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 0.00s

14.2.6 为包含外层注释的项添加文档注释

//! 将文档添加到外层条目，而不是添加到注释后面的项目。我们通常在 crate 根文件（按照惯例是 src/lib.rs）或模块内部使用这些文档注释来记录 crate 或整个模块：

#![allow(unused)]
fn main() {
//! # My Crate
//!
//! `my_crate` is a collection of utilities to make performing certain
//! calculations more convenient.

/// 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
}
}

这个例子中，添加了描述 my_crate 用途的文档。因为使用的是 //!，所以注释的是包含它的外层条目——也就是 crate 根——而不是注释后面的某个条目。

这时候 HTML 文档也会跟着变化： my_crate 的 rustdoc 文档首页，含 crate 描述与 Functions 列表

Keyboard shortcuts