rust-documentation

Rust 文档

将文档视为可执行的接口。将 API 参考紧贴代码，将概念和操作指南放在合适的手册或仓库文档中，并确保示例通过受支持 API 的编译。

范围与分流

此技能适用于 rustdoc 注释、crate 和模块文档、doctest、文档内链接、README 生成、mdBook、docs.rs 配置、链接检查、拼写检查和文档发布门禁。

将通用测试架构分流到 rust-testing，公共 API 兼容性分流到 rust-code-review，Cargo 元数据和发布分流到 rust-cargo-build，API 形态和 trait 设计决策分流到 rust-api-design，非 Rust 办公文档格式分流到对应的文档技能。此技能负责记录现有内容；rust-api-design 决定 API 应该是什么样。

工作流

1. 确定读者和文档载体

盘点公共 crate、二进制文件、功能、目标平台、示例、README、手册、生成的参考文档和托管输出。为每种载体确定受众和负责人：

载体	主要用途
crate 和模块文档	入门路径、架构、功能和平台概览
条目文档	契约、错误、panic、安全性、示例、复杂度
Doctest 和示例	可执行用法和兼容性证明
README	项目发现、安装、最简快速入门、支持政策
mdBook	教程、概念、操作、迁移、长篇指南
docs.rs	按版本发布公共 API

除非明确指定权威来源，否则避免在不同载体中重复相同的文字说明。

2. 记录契约

对于每个公共 API，只记录适用的部分：

• 条目执行的操作和重要语义；
• 带断言和实际导入语句的 # Examples；
• 针对每种重要失败类型的 # Errors；
• 可能发生 panic 的条件，对应 # Panics；
• unsafe API 对调用者的要求，对应 # Safety；
• 取消、阻塞、分配、复杂度、平台、功能和 MSRV 约束。

优先使用文档内链接，例如 [`Client::send`]，而不是脆弱的手写 URL。在 crate 边界启用失效链接检查：

#![deny(rustdoc::broken_intra_doc_links)]

有意决定是否采用 missing_docs；在确定哪些公共兼容性表面需要文档之前，不要全局启用它。

Rust API Guidelines — 文档规则

Rust API Guidelines 定义了五条文档规则（C-DOC、C-DOC-COMMENT、C-META、C-EXAMPLE、C-LINK），高质量 crate 应当满足这些规则。将其作为所有公共 crate 文档的验收标准。完整的理由、反模式和示例见 API Guidelines — Documentation；本节是分流摘要。

C-DOC — 为所有条目编写文档

每个公共条目（函数、结构体、枚举、trait、模块等）都应带有文档注释。使用 missing_docs lint 进行机械检查：

// src/lib.rs
#![deny(missing_docs)]

有意确定范围。在 crate 根目录使用 #![deny(missing_docs)] 是最严格的策略；如果某些表面（封闭模块、生成代码、刻意保持不稳定的 API）需要豁免，应在尽可能小的条目上设置 #[allow(missing_docs)]，并记录原因。

C-DOC-COMMENT — /// 与 //!

• /// 为下一个条目编写文档（函数、结构体、字段、其下方按名称声明的模块）。
• //! 为当前模块或 crate编写文档（放在文件顶部，或模块体内）。
• 两者都会渲染 Markdown，并支持文档内链接 [Foo]。

在 src/lib.rs 顶部以及任何需要概览的模块根部使用 //!；为每个需要文档的条目使用 ///。

C-META — Crate 级文档必须涵盖要点

src/lib.rs 必须以 //! 文档开头，涵盖以下内容：

• 说明 crate 的用途，并链接到用法示例；
• 介绍如何开始使用（链接到设置／集成文档或快速入门）；
• 说明各项功能标志及其启用的功能；
• 最低支持的 Rust 版本（MSRV）；
• 许可证，通常为双重许可 MIT OR Apache-2.0。

运行 cargo doc --no-deps -p <crate>，并检查 crate 的首页是否是独立完整的概览，而不只是模块列表。

C-EXAMPLE — 使用 # Examples 编写可运行示例

每个公开项都应有一个 # Examples 部分。示例应能编译并作为 doctest 运行。准确选择代码围栏属性：

• 无属性——编译并运行；
• ```no_run——编译但跳过执行（网络、文件、硬件）；
• ```ignore——完全跳过，并说明原因；
• ```compile_fail——仅用于 proc-macro crate，展示会被拒绝的输入。

不要用 no_run 掩饰有问题的示例；如果工作流需要文件或凭据，请将其移到 examples/，并将其作为真实目标进行测试。

C-LINK — 文档内链接

使用 [ItemType] 和 [ItemType::method] 语法，以便 rustdoc 解析目标并跟踪重命名。切勿手动编写同一 crate 中类型的路径。在 crate 边界启用断链检查：

#![deny(rustdoc::broken_intra_doc_links)]

有关完整示例、反模式、lint 矩阵和各规则的验证命令，请阅读 API Guidelines — Documentation。

3. 编写可执行示例

对小型公开 API 契约使用 doctest，对完整工作流使用 examples/ crate。准确标记代码围栏：

• 普通 Rust 代码围栏会编译并运行；
• no_run 用于编译需要不可用外部效果的代码；
• compile_fail 用于证明某种用法会被拒绝，而不锁定完整诊断信息；
• ignore 是最后手段，且必须说明原因。

运行：

cargo test --workspace --doc --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps

编写 API 文档时，请阅读 rustdoc and Doctests。

4. 使用 mdBook 编写长篇指南

对于会让 API 文档过于臃肿的教程、架构、运维和迁移材料，请使用 mdBook。将 SUMMARY.md 作为明确的导航约定。使用 mdbook test 测试 Rust 代码示例，在 CI 中构建，并检查内部和外部链接。请阅读 mdBook and Project Guides。

5. 为版本化发布做好准备

检查软件包元数据、docs.rs 目标和功能配置、README 链接、仓库 URL、许可证、示例以及隐藏／私有 API。使用锁定的依赖关系图以及受支持的 MSRV／当前稳定版验证文档，不要只依赖作者的机器。

未经授权，不得发布、修改托管文档或启用外部分析功能。请阅读 Documentation Release Quality。

质量门禁

cargo fmt --all --check
cargo test --workspace --doc --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps
mdbook test path/to/book
mdbook build path/to/book
lychee README.md docs book/src
typos README.md docs book/src src

仅运行项目中已有或获准安装的工具。在 CI 中固定非 Rust 文档工具的版本，不要在仅检查的任务中悄悄改写文本。

完成标准

• 为每类受众提供清晰的入口，避免出现相互冲突的唯一事实来源。
• 在适用时，记录公开错误、panic、安全性、功能、目标平台和兼容性。
• 编译并运行有代表性的文档示例。
• 检出损坏的文档内链接和仓库链接。
• 构建预期发布的相同功能和目标平台文档。
• 明确记录跳过的外部、平台或托管验证。

资源

• rustdoc and Doctests
• mdBook and Project Guides
• Documentation Release Quality
• API Guidelines — Documentation
• Execution Scenarios
• examples/golden-docs/：一个可编译的 crate，启用了文档内链接和 doctest 检查。

上游来源

• The rustdoc Book
• Rustdoc 文档测试
• Cargo 文档
• mdBook
• docs.rs 元数据
• Rust API 指南 — 文档

数据隐私

此技能不会收集、存储或传输用户数据。发布前，请检查示例、生成的源代码链接、构建日志和托管分析数据，确保其中不包含机密信息或专有路径。