rustdoc 手册 on 编程那些事儿

01-rustdoc 是什么？

Sat, 01 Aug 2026 07:35:00 +0800

译文 · 基于 The rustdoc book

rustdoc 是什么？

原文链接: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html

标准 Rust 发行版自带一个名为 rustdoc 的工具。它的工作是为 Rust 项目生成文档。从根本上说，rustdoc 接收一个 crate 根或一个 Markdown 文件作为参数，并产出 HTML、CSS 和 JavaScript。

02-命令行参数

Sat, 01 Aug 2026 07:35:00 +0800

译文 · 基于 The rustdoc book

命令行参数

原文链接: https://doc.rust-lang.org/rustdoc/command-line-arguments.html

以下是你可以传给 rustdoc 的参数列表：

`-h`/`--help`：帮助

使用该标志如下：

1
2


$ rustdoc -h
$ rustdoc --help

这会显示 rustdoc 的内置帮助，其中主要是可能的命令行标志列表。

05-rustdoc 专用 lint

Sat, 01 Aug 2026 07:35:00 +0800

译文 · 基于 The rustdoc book

rustdoc 专用 lint

原文链接: https://doc.rust-lang.org/rustdoc/lints.html

rustdoc 提供了一些 lint，帮助你编写和测试文档。你可以像使用其他 lint 一样使用它们：

1
2
3


#![allow(rustdoc::broken_intra_doc_links)] // 允许该 lint，不会报告任何诊断
#![warn(rustdoc::broken_intra_doc_links)] // 若存在损坏的文档内链接则警告
#![deny(rustdoc::broken_intra_doc_links)] // 若存在损坏的文档内链接则报错

注意，除了 missing_docs 之外，这些 lint 仅在运行 rustdoc 时可用，在 rustc 中不可用。

06-抓取示例

Sat, 01 Aug 2026 07:35:00 +0800

译文 · 基于 The rustdoc book

抓取示例

原文链接: https://doc.rust-lang.org/rustdoc/scraped-examples.html

Rustdoc 有一项不稳定特性：可以自动从 Cargo workspace 的 examples/ 目录中抓取被文档化项的用法示例。这些示例会包含在该项目生成的文档中。例如，若你的库中有一个公开函数：

07-高级特性

Sat, 01 Aug 2026 07:35:00 +0800

译文 · 基于 The rustdoc book

高级特性

原文链接: https://doc.rust-lang.org/rustdoc/advanced-features.html

本页列出的特性不属于其他主要分类。

`#[cfg(doc)]`：文档化平台相关或特性相关信息

对于条件编译，Rustdoc 对你的 crate 的处理方式与编译器相同。只有宿主目标上的内容可用（或使用给定的 --target 时该目标上的内容），其余内容会从 crate 中被“过滤掉”。若你的 crate 在不同目标上提供不同内容，而你又希望文档反映所提供的全部项，这就会带来问题。

08-不稳定特性

Sat, 01 Aug 2026 07:35:00 +0800

译文 · 基于 The rustdoc book

不稳定特性

原文链接: https://doc.rust-lang.org/rustdoc/unstable-features.html

Rustdoc 仍在积极开发中，与 Rust 编译器类似，有些功能仅在 nightly 版本中可用。其中一部分是新功能，需要更多测试才能广泛发布；另一部分则与编译器中的不稳定特性绑定。此处若干特性需要匹配的 #![feature(...)] 属性才能启用，因此在不稳定手册（Unstable Book）中有更完整的文档。相关小节会在必要时链接到该手册。

09-已弃用特性

Sat, 01 Aug 2026 07:35:00 +0800

译文 · 基于 The rustdoc book

已弃用特性

原文链接: https://doc.rust-lang.org/rustdoc/deprecated-features.html

Passes

Rustdoc 有一个称为 “passes” 的概念。它们是 rustdoc 在生成最终输出之前对文档执行的变换。

自定义 passes 已弃用。可用的 passes 不视为稳定，可能在任何发行版中变更。

10-参考资料

Sat, 01 Aug 2026 07:35:00 +0800

译文 · 基于 The rustdoc book

参考资料

原文链接: https://doc.rust-lang.org/rustdoc/references.html

网上有许多优秀的 rustdoc 参考资料。若你还知道其他好资源，欢迎提交 pull request！

rustdoc 手册 on 编程那些事儿

01-rustdoc 是什么？

rustdoc 是什么？

02-命令行参数

命令行参数

`-h`/`--help`：帮助

05-rustdoc 专用 lint

rustdoc 专用 lint

06-抓取示例

抓取示例

07-高级特性

高级特性

`#[cfg(doc)]`：文档化平台相关或特性相关信息

08-不稳定特性

不稳定特性

09-已弃用特性

已弃用特性

Passes

10-参考资料

参考资料

官方

社区

rustdoc 手册 on 编程那些事儿

01-rustdoc 是什么？

rustdoc 是什么？

02-命令行参数

命令行参数

-h/--help：帮助

05-rustdoc 专用 lint

rustdoc 专用 lint

06-抓取示例

抓取示例

07-高级特性

高级特性

#[cfg(doc)]：文档化平台相关或特性相关信息

08-不稳定特性

不稳定特性

09-已弃用特性

已弃用特性

Passes

10-参考资料

参考资料

官方

社区

`-h`/`--help`：帮助

`#[cfg(doc)]`：文档化平台相关或特性相关信息