AI 辅助软件工程：代码文档生成

---
name: "Context Variable"
description: "Here is a description of the action."
interaction:  RunPanel
variables:
  "contextVariable": /ContextVariable\.kt/ { cat }
  "psiContextVariable": /PsiContextVariable\.kt/ { cat }
onStreamingEnd: { saveFile("docs/api.md")  }
---

根据如下的代码编写 API 文档：

/file:src/main/java/com/phodal/shire/demo/controller/BlogController.java

JetBrains 示例

private fun renderTask(renderTask: StringBuilder, language: String) {
    val prompt = when (language) {
        "ObjectiveC" -> "Write doxygen."
        "kotlin" -> "Write KDoc."
        "C#" -> "Write C# doc."
        "F#" -> "Write F# doc."
        "go" -> "Write Go Doc."
        "C++" -> "Write doxygen, do not use @file tag."
        "PHP" -> "Write PHPDoc."
        "HTML" -> "Write JSDoc."
        "JAVA" -> "Write javadoc."
        "Ruby" -> "Write RDoc documentation."
        "TypeScript" -> "Write JSDoc."
        "JavaScript" -> "Write JSDoc."
        else -> ""
    }

    if (prompt.isNotEmpty()) {
        renderTask.append(prompt).append('\n')
    }
}

3. AI 在遗留系统代码文档化中的应用

3.1. 遗留系统的定义与文档化挑战

遗留系统是指仍在使用的过时计算软件和/或硬件 17。这些系统虽然仍能满足其最初设计的功能，但通常不允许增长，并且可能缺乏维护或支持，与其他新系统不兼容，存在安全风险，并且运行缓慢 17。许多公司仍在使用遗留系统，因为它们对业务至关重要，迁移成本高昂，或者缺乏迁移所需的知识 18。

遗留系统文档化的主要挑战包括 19：

• 缺乏或过时的文档：许多遗留系统几乎没有最新的文档，知识往往只存在于即将退休的专家脑中 13。这是现代化改造中最关键的挑战之一。
• 代码复杂性与技术债：遗留代码通常是用过时的编程语言（如 COBOL, Fortran）编写的，经过多年累积，充满了技术债，设计选择不佳，难以理解和维护 19。理解 COBOL 系统的难点不在于语言本身，而在于理解系统的物理限制、其与业务逻辑的交互以及大量其他上下文因素 20。
• 嵌入的业务逻辑提取困难：关键的业务逻辑通常深埋在遗留代码中，难以识别、梳理和提取 20。
• 隐藏的依赖关系：系统之间存在许多未记录的相互连接，使得任何更改都充满风险 20。
• 数据迁移与集成：遗留系统包含大量关键数据，通常是非结构化或过时格式，将其迁移到现代系统并确保数据完整性和兼容性非常复杂 19。
• 人才短缺：熟悉遗留系统（如 COBOL）的工程师正在减少，而新一代开发者对这些技术不熟悉，导致知识鸿沟 13。

这些挑战使得理解和现代化遗留系统成为一项艰巨的任务，而准确的文档是成功进行现代化改造的前提。

3.2. AI 技术在理解和记录遗留代码方面的潜力

AI 技术，特别是 LLM 和 NLP，为理解和记录遗留代码提供了巨大潜力，有助于克服上述挑战：

• 自动化业务逻辑提取与文档生成：AI 工具可以通过分析遗留代码库（包括 COBOL、Fortran 等语言）来识别和提取嵌入的业务规则和概念 20。例如，Kodesage 能够自动发现和映射系统中的业务概念 20。DocuWriter.ai 可以从现有 COBOL 代码库生成变量、数据结构和程序逻辑的详细描述 13。
• 代码分析与解释：AI 算法能够分析 COBOL 等遗留代码，并提供其功能的清晰解释，帮助开发者理解代码的目的和流程，而无需深入研究每行语法的细节 13。这对于缺乏原始开发者知识的系统尤为重要 21。
• 简化复杂代码的理解：AI 工具可以将复杂的遗留程序分解为易于管理的部分，帮助开发者掌握整体结构和流程，从而更容易识别和解决问题 13。
• 自然语言处理 (NLP) 的桥梁作用：NLP 技术可以将遗留代码（如 COBOL）转换为人类可读的描述，弥合技术代码和可理解文档之间的差距，这对于新开发人员的入职培训尤其有用 13。
• 交互式代码演练：一些 AI 工具提供分步代码探索功能，突出显示关键部分并演示它们与系统的交互，帮助开发者理解遗留系统的复杂运作方式 13。
• 代码重构建议：基于最佳实践，AI 可以提供改进和重构遗留代码的建议，以实现现代化并提高可维护性 13。
• 处理多种遗留语言：虽然挑战依然存在，但 AI 模型（如 Codex）经过训练后能够理解多种编程语言的语法和语义，包括一些较旧的语言，从而能够生成与上下文相关的文档 4。IBM 的 watsonx Code Assistant for Z 旨在使用生成式 AI 将 COBOL 代码转换为 Java 25。

尽管前景广阔，但 AI 在处理遗留代码时仍面临挑战，例如 AI 生成的代码可能仍然难以维护，或者 AI 可能无法完全理解所有业务规则和未记录的依赖关系 25。此外，遗留系统数据的质量和可访问性问题，以及与遗留架构的集成复杂性，也是 AI 应用的障碍 22。

3.3. AI 驱动的遗留系统文档化案例与工具

一些工具和案例研究展示了 AI 在遗留系统文档化方面的实际应用：

• DocuWriter.ai：该工具提供针对 COBOL 等旧代码语言的 AI 驱动解决方案，能够自动生成文档、分析和解释代码、简化复杂程序，并通过 NLP 将代码转换为人类可读的描述 13。它还提供交互式代码演练和重构建议。
• Kodesage：该平台专注于遗留系统现代化，其关键功能包括智能文档（持续生成和更新系统文档）和自动业务概念发现，旨在帮助理解嵌入在代码中的知识 20。
• IBM watsonx Code Assistant for Z：此工具利用生成式 AI 将 COBOL 代码转换为 Java，旨在加速大型应用程序的现代化。IBM 的方法还包括使用其应用发现和交付智能 (ADDI) 工具进行库存和分析 25。
• Merit Data & Technology 的案例研究：该公司进行了一项 AI 主导的遗留代码转换和迁移项目，将 PERL 抓取器应用程序现代化为 Python。通过架构重新设计和逐个功能的代码转换，并结合提示工程，实现了运营成本降低 30%，开发人员生产力提高 40% 26。
• 学术研究：研究论文《Automating documentation and legacy code modernization: Revitalizing legacy systems with AI》探讨了利用 AI 进行语义代码分析、智能重构和自动测试生成，以将老化代码库转变为文档齐全、可维护的系统 21。

这些工具和案例表明，AI 能够显著减少理解和记录遗留系统所需的时间和精力，提高文档的准确性，并支持现代化工作。通过自动化文档生成和代码分析，AI 帮助组织保留关键的业务知识，降低现代化风险，并提高开发团队的效率。然而，正如一些讨论所指出的，AI 辅助的转换（如 COBOL 到 Java）并非没有挑战，包括确保语义等效性、处理方言差异以及验证生成代码的正确性和可维护性 25。

4. AI 与“活文档”：实现动态与持续的文档更新

4.1. “活文档”的定义、原则与优势

“活文档”（Living Documentation），也被称为动态文档，是一种与软件本身一同演进的工件，确保其始终保持最新并反映最新的可用信息 27。与那些积满灰尘、迅速过时的传统静态手册不同，“活文档”旨在通过自动化工具或在需要时进行更新，与代码更改保持同步 28。

“活文档”的关键原则包括 29：

• 真实性 (Actual)：文档反映软件的当前状态。
• 可靠性 (Reliable)：呈现的信息值得信赖且准确。
• 最少工作量 (Minimal work to produce)：旨在减少创建和维护文档所需的工作。
• 协作性 (Collaborative)：由不同团队成员共同编写。
• 富有洞察力 (Insightful)：提供对系统行为的有价值的理解。

“活文档”在软件开发中的主要优势有 28：

• 清晰的理解：帮助团队内外的每个人（包括利益相关者）清楚地了解系统如何工作。
• 简化入职：使新团队成员更容易快速了解系统。
• 减少误解，改善沟通：提供当前可靠的信息，有助于最大限度地减少误解并加强团队沟通。
• 可执行规范：当文档与自动化测试相关联时，它可以作为一种可执行规范，展示系统的预期行为。
• 突出异常和未使用的功能：可以揭示系统中的异常情况以及不再使用的特性和方法。

4.2. AI 如何赋能“活文档”的创建与维护

AI 技术通过多种方式赋能“活文档”的创建和维护，确保文档与代码的持续同步和相关性：

• 自动化内容生成与更新：AI 工具能够分析代码结构、注释和变更，自动生成或更新文档内容 5。例如，当代码发生更改时，AI 可以自动更新相关的 API 文档、代码注释或 README 文件 2。GitHub Copilot 能够根据代码上下文生成文档字符串 2。DocuWriter.ai 宣称其自动代码文档能够实现持续的代码文档刷新，确保文档不会过时 31。
• 与版本控制系统 (VCS) 和 CI/CD 集成：许多 AI 文档工具与 Git 等版本控制系统以及 CI/CD 流水线集成，实现文档的实时同步 5。
  • 当代码提交或合并拉取请求 (Pull Request) 时，AI 工具可以自动触发文档更新 35。例如，aise.chat 的 describe 工具可以扫描 PR 的代码更改并生成描述 35。
  • Swimm 等平台通过与 Git 集成，将文档视为代码的一部分，确保文档随代码演进 9。
  • Mintlify 也通过 Git 集成实现文档的自动更新 33。
• 行为驱动开发 (BDD) 与测试用例即文档：“活文档”的一个重要实践源于 BDD，其中测试用例（通常用 Gherkin 等自然语言编写）本身就作为文档 29。AI 正在改变 BDD 的实践方式：
  • 自然语言理解消除胶水代码：现代 LLM 可以解释自然语言并理解意图，将纯英文的 BDD 场景直接转换为测试操作，无需为每个场景编写明确的步骤定义（胶水代码）48。
  • AI 辅助场景生成：AI 可以根据基本场景自动建议相关的错误条件、边缘案例、不同用户类型和备选路径的场景 48。
  • 测试即文档的自动化：Testomat.io 等工具支持 BDD 方法，允许从测试用例生成“活文档”，并在测试发生变化时实时更新文档 29。虽然 Testomat.io 本身未明确提及 AI 功能 29，但其理念与 AI 驱动的“活文档”高度契合。
• 实时代码分析与反馈：AI 工具可以在集成开发环境 (IDE) 中提供实时代码分析和文档建议 11。例如，Codacy 与 IDE 和 AI 助手集成，提供实时的安全和质量反馈，确保代码（包括 AI 生成的代码）符合标准，这间接有助于维护高质量的、与代码一致的“活文档”基础 36。
• 处理多样化的文档类型：AI 不仅限于生成代码注释，还能辅助创建和维护更广泛的软件文档，如架构图、用户指南和 API 参考 2。AI 可以分析代码库、设计规范甚至用户故事，以生成这些类型的文档 5。例如，Amazon Q Developer 可以生成 README 文件和可视化架构图 1。

通过这些机制，AI 正在将文档从静态的、滞后的产物转变为动态的、与开发过程紧密集成的“活”资源，从而提高文档的准确性、相关性和实用性。

4.3. AI 驱动的“活文档”工具与实践案例

许多现代 AI 文档工具都体现了“活文档”的理念，通过与开发工作流的紧密集成来确保持续更新：

• Swimm：该平台利用静态分析和生成式 AI 来自动化文档流程，将文档与代码片段耦合，并在代码更改时跟踪和更新文档 9。Swimm 强调其“代码耦合文档”的方法，确保文档始终与代码的当前状态相关联。它与 Git 等版本控制系统集成，使文档成为开发工作流的有机组成部分。
• Mintlify / Mintlify Writer：此工具通过与代码库的 Git 集成自动生成和维护技术文档，确保文档与代码更改同步 33。Mintlify Writer 能够分析代码结构、注释和使用模式来创建全面的文档，并支持通过 IDE 和版本控制系统进行实时更新。
• Apidog：作为一个智能 API 文档工具，Apidog 的一个核心特性是能够自动同步 API 文档与 API 端点的更改 33。这确保了 API 文档始终反映 API 的最新状态，是“活文档”在 API 领域的一个典型应用。
• Documatic：Documatic 利用 AI 扫描整个代码库并自动生成文档，其语义搜索功能使用户能够快速找到特定信息 33。虽然具体细节不多，但其理念与持续从代码变更中生成文档相符。
• GitHub Copilot：虽然主要是一个代码建议工具，但 GitHub Copilot 也能生成文档字符串和解释代码，并且由于其在 IDE 中的实时性，有助于在编码过程中即时创建与代码相关的初步文档元素 30。
• JetBrains AI Assistant：集成在 JetBrains IDE 中，可以即时生成内联文档，分析代码差异并生成提交信息，这些都有助于在开发过程中维护与代码同步的文档片段 56。
• AI 代理 (AI Agents)：Moderne 的 Moddy 等 AI 代理能够处理大规模代码转换，并可以利用提取的数据更新或生成 README 等文档 60。LinearB 讨论的 AI 代理能够持续更新文档、注释和提交信息以响应代码更改 61。这些代理代表了“活文档”维护的更高级自动化形式。
• 架构文档中的 AI 集成：虽然不完全是“活文档”，但像 Glyph Copilot 这样的工具展示了 AI 在 Revit 项目中自动生成立面图、尺寸标注等文档的能力，这预示着 AI 在更广泛的工程和设计文档自动化方面的潜力，这些文档也需要与设计变更保持同步 62。建筑领域的 AI 应用也强调了通过持续捕获现场图像来创建项目数字存储库，实现实时进度监控和文档记录 63。

这些工具和实践的核心思想是将文档的创建和维护深度嵌入到软件开发和部署的自动化流程中，利用 AI 的分析和生成能力，使文档能够真正地“活”起来，与快速变化的代码库保持一致。这不仅提高了文档的质量和可靠性，也极大地减轻了开发者的文档负担。

5. 主流 AI 代码文档工具概览与比较

AI 代码文档工具市场正在迅速发展，涌现出众多具有不同特性和侧重点的解决方案。本节将概述一些主流工具，并进行比较分析。

5.1. 代表性 AI 代码文档工具介绍

以下是一些在 AI 代码文档生成领域具有代表性的工具：

• Swimm：一个专注于帮助组织理解其代码的平台，利用静态分析和生成式 AI 自动生成文档，并将其与代码耦合以保持同步 9。Swimm 强调“代码耦合文档”，支持创建和维护与特定代码段相关的文档，并在代码更改时提示更新。它支持多种集成，包括主流 IDE（VS Code, JetBrains）和版本控制系统（GitHub, GitLab, Bitbucket, Azure DevOps）41。
• DocuWriter.ai：自称为“排名第一的 AI 代码文档工具”，提供从源代码自动生成技术文档、API 文档（Swagger 兼容）、代码注释、DocBlock、UML 图和测试套件的功能 31。它声称支持所有编程语言，并提供与 Git 仓库和 VS Code 的集成。
• Mintlify / Mintlify Writer：一个 AI 驱动的文档平台，可以从代码库和注释自动生成文档，并通过 Git 集成保持文档的实时更新 32。它提供 AI 聊天、编辑建议和自动翻译功能，并支持 Markdown。Mintlify Writer 能够分析代码结构、注释和使用模式来创建全面的文档 44。
• Amazon Q Developer (前身为 CodeWhisperer)：亚马逊的生成式 AI 助手，提供代码建议、安全扫描，并能自动生成 README 文件和可视化图表（如类图、用例图、序列图）来说明系统架构 1。它与多种 IDE（JetBrains, VS Code, Visual Studio, Eclipse）集成，并支持多种编程语言。
• GitHub Copilot：一个 AI 配对程序员，提供代码建议、解释代码、生成文档字符串和总结拉取请求 2。它支持多种语言，并集成到 VS Code、JetBrains IDE 等多种环境中。
• JetBrains AI Assistant：深度集成到 JetBrains IDE 中，提供代码生成、提交信息生成、内联文档生成等功能 44。它利用 JetBrains 自家的 LLM (Mellum) 以及其他知名 LLM 提供商的模型。
• Apidog：一个智能 API 文档工具，能够从 OpenAPI/Swagger 定义或原始端点自动生成清晰、交互式的 API 文档，并能与 API 更改自动同步 33。它还提供 API 测试和团队协作功能。
• Codacy：虽然主要是一个代码质量和安全平台，但其“AI Guardrails”功能通过与 IDE 和 AI 编码助手集成，对 AI 生成的代码进行实时扫描和自动修复，确保代码符合质量和安全标准 36。它还提供 MCP 服务器，允许通过提示查询代码库的质量指标，这些信息对维护高质量文档至关重要。
• Documatic：利用 AI 扫描代码库并自动生成文档，具有强大的语义搜索功能，使用户能够快速定位特定函数或逻辑 33。
• 其他值得关注的工具：
  • 传统生成器 (部分集成 AI 或作为 AI 工具的补充)：Doxygen 5, Sphinx 5。
  • AI 辅助编码与文档工具：Cody (Sourcegraph) 12, Tabnine 30, Scribe 32, Cline 69, Cursor 32, Windsurf 66, Qodo 32。
  • 专注于特定文档类型或功能的 AI 工具：DeepWiki (将 GitHub 仓库转换为 Wiki 式文档) 84, Documenter (AI 驱动，分析代码库生成文档) 5。

5.2. 比较分析：特性、AI 机制、支持语言、集成与用例

为了更好地理解这些工具之间的差异和共性，下表对部分代表性 AI 代码文档工具进行了比较分析。

表 1：主流 AI 代码文档工具比较分析

分析与讨论：

从上表可以看出，AI 代码文档工具在功能、底层技术和集成方式上存在显著差异。

• AI 机制：许多工具，如 GitHub Copilot、Amazon Q Developer 和 JetBrains AI Assistant，主要依赖大型语言模型 (LLM) 进行代码理解和文本生成。而 Swimm 则强调其结合了静态代码分析与生成式 AI，以实现更深层次的代码理解和更准确的文档-代码耦合 9。DocuWriter.ai 也声称使用 AI 算法和 NLP 10。
• 文档类型：覆盖范围从基本的代码注释和 DocString（例如 GitHub Copilot, JetBrains AI Assistant），到完整的 README 文件和 API 文档（例如 Amazon Q Developer, Apidog, Mintlify），再到更深度的代码库概览和架构图（例如 Swimm, Amazon Q Developer），甚至 UML 图和测试用件（例如 DocuWriter.ai）。
• 遗留系统支持：DocuWriter.ai 和 Swimm 在处理遗留代码（如 COBOL）方面显示出特定优势 9。许多通用工具虽然声称支持多种语言，但其在复杂、文档稀疏的遗留系统上的表现仍有待验证。
• 活文档实现：对于“活文档”，与版本控制系统 (Git) 和 CI/CD 流水线的紧密集成是关键。Swimm 和 Mintlify 在这方面表现突出，它们的设计理念就是让文档与代码同步演进 9。Apidog 专注于 API 文档的实时同步 33。其他 IDE 集成工具（如 Copilot, JetBrains AI）则通过在编码过程中提供实时辅助来间接支持“活文档”的某些方面。
• 语言支持：DocuWriter.ai 和 GitHub Copilot 等工具声称支持广泛的编程语言 31。其他工具可能对特定语言或语言类型（如 API 描述语言）有更好的优化。
• 集成：IDE 插件（VS Code, JetBrains 是主流）和与 GitHub 等平台的直接集成是提高开发者采用率的关键因素 11。

当前 AI 代码文档工具领域呈现出多样化和快速迭代的特点。开发者在选择工具时，需要仔细评估其具体的 AI 能力、所支持的文档类型、对特定编程语言（尤其是遗留语言）的覆盖程度、与现有开发工作流的集成便捷性，以及其在实现和维护“活文档”方面的实际效果。没有一个工具是万能的，最佳选择取决于项目的具体需求和团队的偏好。

5.3. 开源与商业工具：采用考量

在选择 AI 代码文档工具时，组织和开发者还需要在开源和商业解决方案之间进行权衡。

• 开源工具：
  • 代表：Docsify 51, Docusaurus 51, Sphinx 5, DocsGPT 85。
  • 优势：通常免费，具有高度可定制性，并受益于社区支持和贡献。用户可以根据自己的特定需求修改和扩展这些工具。
  • 劣势：可能需要更多的设置、配置和维护工作。与商业工具相比，其 AI 功能可能不那么先进或用户体验可能不够完善。获取企业级支持可能较为困难。
• 商业工具：
  • 代表：Swimm, DocuWriter.ai, Mintlify, GitHub Copilot, Amazon Q Developer, JetBrains AI Assistant, Apidog 等。
  • 优势：通常提供更精致的用户体验、更高级的 AI 功能、专门的客户支持、更便捷的集成以及针对企业用户的特性（如安全性和合规性）。
  • 劣势：需要付费，可能存在供应商锁定的风险。定价模式多样，从按用户按月收费到基于使用量的计费 31。

采用考量因素：

• 预算：开源工具在初始成本上具有明显优势。商业工具则需要评估其订阅费用与预期收益。
• 团队规模与专业知识：小型团队或具有较强技术能力的团队可能更倾向于可定制的开源解决方案。大型企业或对易用性要求较高的团队可能更青睐功能完善的商业工具。
• 特定功能需求：例如，对特定遗留语言的支持（如 DocuWriter.ai 对 COBOL 的支持 13）、强大的“活文档”能力（如 Swimm 38）、或专门的 API 文档功能（如 Apidog 33）可能会成为决定性因素。
• 集成需求：工具与现有 IDE、版本控制系统、CI/CD 流水线和项目管理工具的集成能力至关重要。
• 安全与隐私：特别是对于处理敏感代码或专有信息的组织，基于云的 AI 工具的数据安全和隐私政策需要仔细审查 71。部分工具（如 Swimm）提供本地部署或使用自有 LLM 的选项以增强安全性 41。
• 知识产权：需要关注 AI 模型训练数据的来源及其对生成内容的潜在影响，以避免无意的知识产权侵权 71。

选择合适的 AI 代码文档工具是一个需要综合考虑技术特性、业务需求、团队能力和成本效益的决策过程。随着技术的不断成熟，开源和商业工具的功能界限可能会逐渐模糊，但核心的评估标准将保持不变。