什么是 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 为整个项目生成文档。请参阅将 rustdoc 与 Cargo 结合使用。

这有两个问题：首先，为什么它认为我们的 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 控制我们文档的输出。请注意，Cargo 不是放在顶层 doc 目录中，而是将生成的文档放在 target 下。这是 Cargo 项目中生成文件的习惯用法。
-L 标志帮助 rustdoc 找到您的代码所依赖的依赖项。如果我们的项目使用了依赖项，我们也会获得它们的文档！

/// 语法用于记录它后面的项。这就是为什么它被称为外部文档。还有另一种语法：//!，它用于记录它所在的项。它被称为内部文档。它通常用于记录整个 crate，因为它前面没有任何内容：它是 crate 的根。因此，为了记录整个 crate，您需要使用 //! 语法。例如

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

当在 crate 根目录中使用时，它会记录它所在的项，即 crate 本身。

有关 //! 语法的更多信息，请参阅本书。

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 的所有选项以及如何使用它们。