rustdoc 是什么？

标准的 Rust 发行版附带了一个名为 rustdoc 的工具。它的作用是为 Rust 项目生成文档。从基本层面来说，Rustdoc 接收 crate 根文件或 Markdown 文件作为参数，然后生成 HTML、CSS 和 JavaScript 文件。

基本用法

让我们来尝试一下！使用 Cargo 创建一个新项目

$ cargo new docs --lib
$ cd docs

在 src/lib.rs 中，Cargo 已经生成了一些示例代码。删除它并替换为以下内容

#![allow(unused)]
fn main() {
/// foo is a function
fn foo() {}
}

让我们在代码上运行 rustdoc。为此，我们可以像这样调用它，并传入 crate 根文件的路径

$ rustdoc src/lib.rs

这将创建一个新的目录 doc，其中包含一个网站！在我们的例子中，主页位于 doc/lib/index.html。如果你在 Web 浏览器中打开它，你会看到一个带有搜索栏的页面，顶部显示“Crate lib”，但没有任何内容。

你也可以使用 cargo doc 为整个项目生成文档。参见通过 Cargo 使用 rustdoc。

这里有两个问题：首先，为什么它认为我们的 crate 叫做“lib”？其次，为什么它没有任何内容？

第一个问题是由于 rustdoc 试图提供帮助；像 rustc 一样，它假定我们的 crate 名称就是 crate 根文件的文件名。为了解决这个问题，我们可以传入一个命令行标志

$ rustdoc src/lib.rs --crate-name docs

现在，将生成 doc/docs/index.html，页面显示“Crate docs”。

对于第二个问题，是因为我们的函数 foo 不是公共的；rustdoc 默认只为公共函数生成文档。如果我们修改代码...

#![allow(unused)]
fn main() {
/// foo is a function
pub fn foo() {}
}

... 然后重新运行 rustdoc

$ rustdoc src/lib.rs --crate-name docs

我们现在就有了一些生成的文档。打开 doc/docs/index.html 查看一下！它应该会显示一个指向 foo 函数页面的链接，该页面位于 doc/docs/fn.foo.html。在该页面上，你会看到我们在 crate 文档注释中写入的“foo is a function”。

Cargo 也集成了 rustdoc，使得生成文档更加容易。我们可以不用 rustdoc 命令，而是使用这个

$ cargo doc

如果你想让 cargo 自动打开生成的文档，你可以使用

$ cargo doc --open

在内部，cargo doc 会像这样调用 rustdoc

$ rustdoc --crate-name docs src/lib.rs -o <path>/docs/target/doc -L
dependency=<path>/docs/target/debug/deps

你可以使用 cargo doc --verbose 查看这个过程。

它为我们生成了正确的 --crate-name，并指向了 src/lib.rs。但那些其他参数呢？

-o 控制我们文档的**输**出（**o**utput）。请注意，Cargo 将生成的文档放在 target 下，而不是顶层的 doc 目录。这是 Cargo 项目中生成文件的惯例位置。
-L 标志帮助 rustdoc 找到你的代码依赖的库。如果我们的项目使用了依赖，我们也会获得它们的文档！

/// 语法用于文档化其后面的项。这就是为什么它被称为外部文档。还有另一种语法：//!，它用于文档化其所在内部的项。这被称为内部文档。它通常用于文档化整个 crate，因为它前面没有东西：它是 crate 的根。所以为了文档化整个 crate，你需要使用 //! 语法。例如

#![allow(unused)]
fn main() {
//! This is my first rust crate
}

当在 crate 根中使用时，它文档化它所在的项，也就是 crate 本身。

有关 //! 语法的更多信息，请参阅《Rust 程序设计语言》。

rustdoc 也可以从独立的 Markdown 文件生成 HTML。让我们试一下：创建一个 README.md 文件，内容如下

# Docs

This is a project to test out `rustdoc`.

[Here is a link!](https://rust-lang.net.cn)

## Example

```rust
fn foo() -> i32 {
    1 + 1
}
```

然后对它调用 rustdoc

$ rustdoc README.md

你会在 docs/doc/README.html 中找到一个从 Markdown 内容生成的 HTML 文件。

不幸的是，Cargo 目前不支持独立的 Markdown 文件。

这涵盖了 rustdoc 最简单的用例。本书的其余部分将解释 rustdoc 的所有选项以及如何使用它们。