什么是 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。如果您在网络浏览器中打开它，您将看到一个带有搜索栏的页面，顶部显示“Crate lib”，但没有内容。

您还可以使用 cargo doc 为整个项目生成文档。请参阅使用 rustdoc 与 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”。

使用 rustdoc 与 Cargo

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 本身。

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

使用独立的 Markdown 文件

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

# Docs

This is a project to test out `rustdoc`.

[Here is a link!](https://www.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 的所有选项以及如何使用它们。

rustdoc 书籍