04-如何编写文档 on 编程那些事儿

01-应包含（和排除）什么

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

译文 · 基于 The rustdoc book

原文链接: https://doc.rust-lang.org/rustdoc/write-documentation/what-to-include.html

说项目里的一切都必须有文档很容易，而且往往正确，但怎样做到？又有没有本不该写进文档的东西？

在二进制项目的 src/lib.rs 或 main.rs 文件顶部加入如下属性（attribute）：

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

译文 · 基于 The rustdoc book

原文链接: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html

#[doc] 属性（attribute）让你控制 rustdoc 工作方式的多个方面。

#[doc] 最基本的功能是处理实际的文档文本。也就是说，/// 是 #[doc] 的语法糖（//! 对应 #![doc]）。这意味着下面两者等价：

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

译文 · 基于 The rustdoc book

原文链接: https://doc.rust-lang.org/rustdoc/write-documentation/re-exports.html

先解释什么是重导出。为此用一个例子：我们正在编写一个库（名为 lib），其中一些类型分散在子模块中：

1
2
3
4
5
6


pub mod sub_module1 {
 pub struct Foo;
}
pub mod sub_module2 {
 pub struct AnotherFoo;
}

用户可以这样导入：

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

译文 · 基于 The rustdoc book

原文链接: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html

Rustdoc 能够用项的路径作为链接，直接链接到其他 rustdoc 页面。这称为「文档内链接（intra-doc link）」。

例如，在下面的代码中，所有链接都会指向 Bar 的 rustdoc 页面：

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

译文 · 基于 The rustdoc book

原文链接: https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html

rustdoc 支持把文档示例当作测试执行。这能确保文档中的示例是最新的且可运行。

基本思路如下：

/// # 示例
///
/// ```
/// let x = 5;
/// ```
# fn f() {}

这里，三个反引号开始并结束代码块。若这在名为 foo.rs 的文件中，运行 rustdoc --test foo.rs 会提取该示例，然后作为测试运行。