documentation-generator

文档生成器

用途

生成以代码而非独立文档为事实来源的文档，避免文档起初准确，随后逐渐过时。输入可以是代码库、模块或 API 规范；输出可以是源代码中的文档注释、生成的参考站点、README、变更日志或图表，也可以是尚未记录文档的内容清单。

与代码并列编写的文档几周内就会偏离代码。由代码派生的文档只有在有人更改签名却不更新注释时才会偏离，而生成器可以检测并报告这种情况。检测正是这里的大部分价值所在；撰写文字反而是简单的部分。

适用场景

• 公共 API 没有参考文档，或重构后文档已经过时
• 公共符号缺少文档注释，工具链会对此发出警告
• 已有 OpenAPI 规范，但没有面向读者的 REST 文档
• 发布版本需要变更日志，且提交遵循约定
• 新贡献者需要 README 或架构概览来熟悉项目

不适用于此技能的场景：

• 与用户共同编写设计文档、提案或规范 → doc-coauthoring
• 查找第三方库的文档 → find-docs
• 对整个项目进行审查，恰好发现了文档缺失 → code-analyzer
• 手工绘制特定图表，而不是从代码派生图表 → draw-io-diagram-generator
• 在不同格式之间转换现有文档 → markitdown

前置条件

1. 要记录什么内容，现有工具链由什么负责？ 从构建文件而非文件扩展名判断——文档工具链会在构建文件中声明；已经有工具链的项目，也已经做出了大部分选择。

构建文件 / 信号	技术栈	参考资料
build.gradle.kts 中包含 kotlin("multiplatform") 或 org.jetbrains.dokka	Kotlin / KMP / CMP	kotlin-kmp.md
pubspec.yaml	Flutter / Dart	flutter-dart.md
Package.swift、*.xcodeproj、*.docc/	Swift（iOS/macOS）	swift-apple.md
Cargo.toml	Rust	rust-cpp.md
CMakeLists.txt、Doxyfile、conanfile.txt	C / C++	rust-cpp.md
openapi.yaml、swagger.json、paths: + components:	REST API 规范	api-specs.md
package.json、pyproject.toml、go.mod	JS/TS、Python、Go	other-languages.md
README、CHANGELOG、图表、带版本的站点	任意 — 跨领域	project-docs.md

加载一份技术栈参考资料；任务需要时，再加载 project-docs.md。全部加载会混淆当前未使用工具链的惯用做法，也会掩盖真正适用的内容。

2. 已有文档是什么样的？ 生成任何内容之前，先阅读现有文档——例如 docs/ 目录、现有 README，或三四个已有文档注释的公共符号。它们的语气、深度、结构和自然语言都已经确定；与之保持一致，比遵循本技能中的任何惯例都重要。生成的页面如果与相邻内容风格迥异，就会被手动重写。应使用现有文档的语言撰写，而不是对话所用的语言——即使用户用匈牙利语提出需求，英文代码库中的文档注释仍应使用英文。

# existing docs, doc config, and the conventions already in use
ls -d docs doc site .docc *.docc 2>/dev/null
find . -maxdepth 2 \( -name 'Doxyfile*' -o -name 'mkdocs.yml' -o -name 'dokka*' \
  -o -name '*.docc' -o -name 'cliff.toml' -o -name 'redocly.yaml' \) -not -path '*/build/*'

3. 代码是否足够稳定，可以编写文档？ 为即将变更的 API 编写文档，会让工作白费两次。如果目标正处于重构中，应说明情况，并提出先记录已经稳定的部分。

工作流

步骤 1：判断读者需要什么

文档失败的原因更多是切入点不对，而不是文笔不好。根据读者是谁、他们想做什么来选择文档类型：

读者的问题	文档类型	基于
“这个函数做什么？”	API 参考	公共符号的文档注释
“如何调用这个端点？”	REST 参考	OpenAPI 规范
“如何开始使用？”	README / 入门指南	软件包元数据 + 一个实际可用的示例
“这些部分如何协同工作？”	架构概览	模块图、分层、关键类型
“有哪些变更？”	更新日志	提交历史
“如何完成 X？”	指南 / 教程	两者都不是——这是撰写的内容，不是生成的内容

最后一行很重要：指南无法从签名推导出来，因为内容的顺序和编写动机都存在于作者脑海中。用户需要指南时，要么向他们收集这些背景信息，要么交给 doc-coauthoring。

步骤 2：找出缺少文档的部分

让工具链来回答，而不是逐个阅读文件：每个技术栈都会对公共符号缺少文档发出警告。技术栈参考文档会列出确切的开关，例如 Rust 中的 #![warn(missing_docs)]、Dart 中的 public_member_api_docs、Doxygen 中的 WARN_IF_UNDOCUMENTED 等。

对缺失项进行优先级排序，而不是按字母顺序罗列：

1. 优先处理公共 API。 调用方看不到的内容，就不需要为他们编写文档。
2. 先处理入口，再处理叶节点。 有人首先实例化的类型，应先添加注释，再处理它的私有辅助项。
3. 先处理不明显的行为，再处理显而易见的行为。 单位、线程、可空性、所有权、错误条件和副作用，才是读者真正想了解的内容。

重复签名含义的注释（例如在 getName() 上写 /** Returns the name. */）只会制造噪声：增加维护成本，却没有提供新信息。跳过这类注释，并说明你跳过了什么以及原因。

步骤 3：编写文档注释

在源代码中，使用技术栈的标记语法和标签来编写文档——语法和惯用写法见技术栈参考文档。无论使用哪种技术栈，有用的注释都具备以下特点：

• 先说明约定，而不是实现机制。 说明它保证什么，而不是如何实现——实现会变，调用方依赖的是约定。
• 记录签名无法表达的内容：单位、有效范围、可空性、线程／隔离区／Actor 关联性、所有权和生命周期、是否会阻塞、是否具有幂等性。
• 说明调用方必须处理的每种错误路径——抛出的异常、Err 变体、失败的 Future、非零返回值，以及产生这些情况的条件。
• 在工具链支持的情况下提供可编译的示例——rustdoc 文档测试、KDoc @sample、DocC 代码片段、Doxygen @snippet。这些是唯一不会悄然过时的示例，因为它们出错时，CI 会失败。
• 使用链接，不要重复。 每种工具链都有文档内链接；重复说明意味着还要维护另一份内容，确保它始终正确。

面向这样的调用方来写：他们面前已经有函数签名，却仍有疑问。

第 4 步：生成并检查输出

运行生成器并查看警告——失效链接、未记录的符号和无法解析的引用，正是这项技能要捕捉的偏差。命令请参阅技术栈参考。

每次都值得做的两项检查：

• 示例能否编译并运行？ 如果工具链支持文档测试，就运行这些测试。无法编译的示例比没有示例更糟。
• 链接能否正常解析？ 文档内链接失效通常意味着符号已重命名，但相关引用没有更新——这是偏差信号，不只是格式问题。

如果未安装生成器或无法运行（缺少工具链、npx 无法联网），请在报告中说明，并列出用户应运行的准确命令——未经询问，不要全局安装工具链，也绝不要描述你未生成的输出。即使只交付源代码注释，它们仍然有价值。

精简输出：文档生成器会产生大量内容，因此请筛选警告和错误，不要粘贴完整运行结果。绝不要将生成的网站读回上下文——那是构建输出，待审查的是源代码注释。

第 5 步：报告已记录和未记录的内容

## Documentation added
<files touched, and what each now documents>

## Generated
<command run, output location, and the real result — including warning count>

## Still undocumented
<specific public symbols or endpoints, as `file:line` — with why, where there is a reason>

## Drift found
<docs that contradict the implementation, if any>

偏差部分最值得关注。描述代码已不再具备的行为的注释，比缺少注释更糟，因为人们会相信它。即使修复不在当前范围内，也要报告。

操作

操作	用户意图	输出
comments（默认）	“为这个类／模块编写文档”	以项目标记语言写入源代码的文档注释
reference	“生成 API 文档”、“设置 Dokka／DocC／dartdoc”	配置并运行生成器；生成参考网站或 Markdown
api	“为这个 REST API 编写文档”	根据 OpenAPI 规范编写易读的 REST 文档，并报告规范检查问题
readme	“编写 README”	根据软件包元数据搭建 README 框架，并附上经过验证的可运行示例
changelog	“为此版本生成变更日志”	根据上一个标签以来的提交，生成 Keep a Changelog 格式的条目
architecture	“解释各部分如何协同工作”	根据构建图生成概览文档，并附上 Mermaid 模块／分层图
audit	“文档已经过时”	按优先级列出未记录的符号以及文档与实现之间的偏差；仅在用户要求时修复

关键限制

• 绝不要记录你没有读过的行为。 对扫过一眼的代码写出听起来合理的注释，是一种自信的谎言，而且可能比作者存在得更久。请阅读实现，或主动询问。
• 绝不要虚构 API 接口——代码或规范中不存在的端点、参数、错误代码或配置键。读者对文档的信任通常胜过对代码的信任，因此在这里编造内容代价尤其高。
• 编写文档时不要修改实现代码。 为了清晰而重命名，或“修复”注释揭示的问题，都是独立的更改；请提出建议，不要悄悄加入。
• 除非项目已有此做法，否则不要提交生成的输出——先检查 .gitignore 中是否包含 docs/api/、target/doc/ 或 doc/api/。提交的生成文档在评审时很容易过时。
• 示例中绝不要放入凭据、内部主机名、客户数据或未发布的产品名称。 文档是仓库中传播最广的产物；请使用工具链自带的占位符规范。
• 不要为了给生成的文档腾地方而删除现有文档。 手写文档通常包含生成器无法恢复的上下文——请合并，或提出询问。
• 不要为你无法理解的提交虚构变更日志条目。 按原样将其列在“其他”标题下，让人工进行分类。

参考资料

• kotlin-kmp.md — KDoc 标签、Dokka 设置与任务、KMP 各源集的文档、@sample、expect/actual 文档
• flutter-dart.md — dartdoc 注释、dart doc、宏与模板、pub.dev 元数据、文档 lint
• swift-apple.md — DocC 标记、.docc 目录、主题、教程、swift package generate-documentation、静态托管
• rust-cpp.md — rustdoc、文档测试、文档内链接、docs.rs 元数据；Doxygen、Breathe/Sphinx
• api-specs.md — OpenAPI/Swagger lint、生成参考站点和 Markdown、为已有规范编写文档
• other-languages.md — TSDoc/TypeDoc、Python 文档字符串与 Sphinx/MkDocs、Go 文档注释
• project-docs.md — README 脚手架、常规提交日志、Mermaid 架构图、带版本的文档站点