修炼AI技能
AI 教程 / AI 编程实战 / AI 生成代码文档：让模型写注释与说明

AI 生成代码文档：让模型写注释与说明

文档往往是工程里最容易被拖延、也最容易被忽略的部分。代码会随需求不断演化，文档却常常停留在最初的版本。好消息是，现代 AI 编码工具已经能够基于代码与上下文，快速产出各类文档初稿。本文聚焦「文档与注释生成」这一具体场景，介绍适合交给 AI 的任务、可复用的生成工作流、常用工具的真实能力，以及必须避开的陷阱。

文档有哪些类型

在动手之前，先分清我们要生成的是哪一类文档，因为不同类型对准确性与读者的要求差别很大：

  • 行内注释：解释某一段逻辑为什么这样写，尤其是非显而易见的取舍。
  • 函数或类 docstring：描述参数、返回值、异常，以及函数的职责边界。
  • 模块 README：告诉使用者如何安装、如何快速开始、API 长什么样。
  • 架构与设计说明：解释模块之间的依赖、关键决策与演进方向。
  • API 文档：对外暴露的接口契约，通常要随版本严格维护。

其中，行内注释、docstring 与 README 是最适合先交给 AI 起草的三类，因为它们高度依赖「代码本身」，模型有充足素材可依据。

哪些文档适合交给 AI

并不是所有文档都该让 AI 起头。下面三类收益最高，也最不容易出错：

第一，根据函数体反推用途来写 docstring。当函数实现已经写好、却缺少说明时，把函数体交给模型，让它归纳参数含义、返回结构与可能抛出的异常，通常能一次得到可用的初稿。

第二，把零散说明汇成 README。团队里常有一些写在聊天记录、issue 或注释里的使用方式，让 AI 把这些碎片按「功能简介、安装、快速开始、API 概览」的结构组织成 README，比从空白页写起省力得多。

第三，为旧代码补注释。遗留代码往往没有说明，模型可以逐段阅读并给出「这段代码在做什么」的注释，帮助你先理解、再决定是否保留。

反过来，涉及产品定位、商业取舍、合规口径的说明，AI 缺少权威信息，不应让它凭空发挥。

一条可复用的生成工作流

要让 AI 写出的文档靠谱，关键不在「会问」，而在「给足上下文并定好约束」。建议按下面三步组织你的提示：

  1. 提供完整文件或相关上下文。只贴一个函数签名，模型很容易猜测实现细节；把函数体、相关类型定义、调用方一并给出，准确率会明显提升。
  2. 指定文档风格。不同团队偏好不同，常见有 Google 风格、NumPy 风格、reST 风格的 docstring，提前写明能避免风格来回返工。
  3. 指定读者。同样是说明一个函数，写给「刚入职的新人」要更铺垫背景，写给「熟悉本模块的调用方」则可以更紧凑，直接讲清契约即可。

一个实用的提示示例：

阅读下面这个文件的完整内容，为其中的 normalize_path 函数写一段 Google 风格的 docstring。
读者是本模块的新同事，请说明参数含义、返回值，以及什么情况下会抛 ValueError。
之后再把整个模块整理成一份 README，包含功能简介、安装方式、一段最小可运行示例和 API 表格。

让文档可运行：示例与签名要对得上

AI 生成文档时最容易犯的一类错误，是「编」出不存在的 API、参数或返回值。模型会基于训练语料中的相似代码「脑补」一个合理但不属于这份代码的签名。因此，产出之后必须人工核对两点：

其一，参数与返回值要与实际函数签名一致。以下面这段 Google 风格 docstring 为例，描述必须严格对应 raw、base 两个参数以及 str 返回值：

def normalize_path(raw: str, base: str = "/"):
    """将用户输入的路径规范化。

    Args:
        raw: 待处理的原始路径字符串，可能包含多余的斜杠或相对段。
        base: 作为基准的根目录，用于解析相对路径，默认根目录。

    Returns:
        规范化后的绝对路径字符串，保证以 base 开头且不含 `.` 或 `..`。

    Raises:
        ValueError: 当 raw 解析后超出 base 范围时抛出。
    """
    ...

其二，示例要能真正跑起来。README 里的最小可运行示例，最好贴出来之前本地实际执行一遍。很多文档错误就藏在「看起来对」的示例里：导入路径写错、函数名拼写不一致、版本差异导致的行为变化，只有跑过才知道。

下面是一份适合让 AI 起草、再由人校对的 README 骨架：

# 项目名

## 功能简介
一句话说明这个模块解决什么问题。

## 安装
使用 pip 从源码安装：pip install -e .

## 快速开始
给出一段最小可运行示例，演示主要函数的调用方式。

## API 概览
用表格列出核心函数及其作用。

## 目录结构
简述关键目录与入口文件的职责。

常用工具与真实能力

不同工具在「文档生成」上的能力形态不一，下面只陈述已确认的部分。

GitHub Copilot

GitHub 官方文档说明，Copilot 可以分析你正在编写的代码，并生成描述代码行为的注释（comment suggestions）。在 Visual Studio 17.14 Preview 2 及更高版本中，该能力对 C# 与 C++ 提供注释建议：在目标代码前输入语言对应的注释起始符（如 ///），等待建议出现，按 Tab 接受、Alt+/ 修改、Esc 拒绝。这是官方明确记载的能力，标注为已核验。

更广义的 docstring 触发方式（例如在 JavaScript 或 TypeScript 中输入 /** 让 Copilot 补全 JSDoc）在社区与旧文档中常见，但当前官方文档的重点落在 C#/C++ 的注释建议上，对其他语言的具体形式标注为待核实。

Cursor

Cursor 通过 @ 符号把上下文注入对话，这对文档生成很有用。常用的有 @Files（引用整个文件）、@Folders（引用目录）、@Code（引用某段代码）、@Codebase（在整个代码库中做语义检索）、@Docs（引用外部文档）、@Git 与 @Web。生成文档时，你可以用 @Files 指向目标文件，再要求它生成 docstring 或 README，模型看到的就是你指定的真实内容，而不是自己猜测。该 @ 上下文机制在官方文档与社区说明中一致，能力本身标注为已核验；不过具体符号集合在不同版本间有过调整，细微差异标注为待核实。

Claude Code

Claude Code 的官方文档明确提到，它可以编写发布说明（release notes），可以调度在 PR 合并后同步文档（syncing docs），并可通过 Model Context Protocol（MCP）读取外部设计文档（如 Google Drive 中的设计稿）。用自然语言描述需求，它就能跨多个文件编辑并生成 README 或 docstring，还能借助 CLAUDE.md 设定文档规范与风格约束。官方文档未将「专门生成 README/docstring 的命令」单独列出，因此这一用法属于可行的提示路径，标注为待核实。

必须避开的陷阱

即便工具再顺手，下面三个坑仍然常见，需要人把关：

第一，AI 会编造不存在的 API 或参数。模型倾向于补全一个「合理」的接口，而这个接口可能并不存在于你的代码或依赖里。凡是文档里出现的函数名、参数名、异常类型，都应对照源码逐一确认。

第二，文档与代码不同步。AI 生成的是某一时刻的快照，代码一旦改动，文档就会过时。把文档纳入评审与 CI 检查，比事后补救更省心。

第三，过度冗余的噪声。模型有时会写出「本函数用于执行函数功能」这类同义反复，或把显而易见的代码逐行翻译一遍。好的文档讲清「为什么」与「契约」，而不是复述「是什么」。

与文档即代码和自动化文档生成的关系

「文档即代码」（Docs as Code）主张用与代码相同的流程管理文档：版本化、评审、自动化构建。AI 生成的草稿正好可以落进这一流程——它产出的是待评审的文本，而非最终结论。

更进一步，当 docstring 写得规范，就可以接上基于 docstring 的自动化文档生成工具。以 Python 生态的 Sphinx 为例，配合 autodoc 扩展，它能直接从 docstring 抽取内容生成 API 文档站点，无需手工维护重复说明。也就是说，AI 负责把 docstring 写清楚，Sphinx 负责把它变成可发布的文档，两者互补：前者降低书写成本，后者保证与代码同源、减少漂移。

小结

AI 非常适合承担文档的「初稿起草」工作：反推 docstring、汇总 README、为旧代码补注释，都能显著降低成本。关键做法是给足上下文、指定风格与读者，并在交付前人工核对签名与示例的真实可用性。GitHub Copilot、Cursor、Claude Code 都提供了可验证的文档相关能力，但没有哪个工具能替代人对准确性的最终把关。把 AI 产出接入文档即代码与自动化生成流程，才能让文档随代码一起保持健康。

参考与延伸阅读

  • GitHub Docs：在 IDE 中获取 Copilot 代码建议（含注释建议 comment suggestions，C#/C++）——已核验
  • GitHub Docs：GitHub Copilot 概览与文档生成相关说明——已核验（注释建议能力）、待核实（其他语言 docstring 触发形式）
  • Cursor Docs：上下文与 @ 符号（@Files、@Codebase、@Docs 等）官方说明——已核验（上下文注入能力）、待核实（具体符号集随版本变化）
  • Claude Code Docs：概览（release notes、syncing docs、MCP 读取设计文档）——已核验
  • Claude Code Docs：常见工作流与最佳实践（README/docstring 生成的提示路径）——待核实
  • Sphinx 官方文档：autodoc 基于 docstring 生成 API 文档——已核验（作为自动化文档生成工具的事实说明）
本文累计阅读 — 次