大语言模型辅助代码文档生成
随着大语言模型的广泛应用，LLM辅助进行代码文档生成在业界已逐渐成为趋势。代码文档的生成是软件开发中的一个关键环节，直接影响到代码的可读性、维护性以及团队协作的效率。传统的文档编写往往需要大量的时间和精力，同时依赖于开发人员的表达能力以及对项目的理解程度。这种模式既耗时，又容易产生疏漏。将大语言模型应用于代码文档生成领域，能够显著提升文档的生成效率和准确性。
一、RepoAgent: An LLM-Powered Open-Source Framework for Repository-level Code Documentation Generation
RepoAgent由清华大学、中国人民大学和西门子的研究团队提出，旨在使用大语言模型生成和维护仓库级别的文档。传统的文档生成方法主要针对独立代码片段的摘要，导致文档内容片段化且抽象，难以体现代码语义，并且缺乏代码示例和自动更新机制。RepoAgent通过三大核心功能解决这些问题：
1. 全局结构分析模块
在生成高质量、上下文关联的文档之前，需要对代码库的整体结构进行理解。为此，RepoAgent的全局结构分析模块负责解析代码库的文件结构、类和函数的关系、代码片段的层次结构等。主要功能如下：
（1）项目树构建：首先排除非Python文件，然后对代码库中的Python文件使用抽象语法树进行解析，提取出类、函数等代码对象的信息（如类型、名称、代码片段等）。这些信息被组织成一个“项目树”的结构，项目树的根节点表示整个代码库，文件夹和Python文件分别作为中间和叶子节点。每个文件节点包含类和函数节点，形成具有语义层级关系的项目树。
（2）引用关系解析：RepoAgent进一步分析代码中函数和类的引用关系，将这些引用关系作为上下文信息帮助模型更好地理解代码语义。项目树中的叶子节点被扩展为一个有向无环图（DAG）。通过这种方式，RepoAgent可以将调用的上下文信息整合到文档生成中，使文档内容更具指导性和一致性。
2. 文档生成模块
文档生成模块负责利用已解析的代码库信息生成文档内容。该模块采用一种精心设计的prompt模板，以确保生成的文档结构完整、信息丰富。文档的结构包括以下几个部分：
功能描述：对代码对象的功能进行概述，帮助开发者迅速理解代码的作用。 参数说明：列出所有相关参数及其描述，提供关于输入输出的详细信息。 代码描述：对代码逻辑进行深入解析，涵盖代码在全局上下文中的角色和与其他代码对象的关系。 使用注意事项：提供代码使用中的注意事项，指出可能的误用，优化建议等。 示例：在代码生成返回值的情况下，提供代码示例和期望的输出，便于开发者的理解。
在具体生成过程中，RepoAgent以项目树中的代码对象为节点，按拓扑顺序从下往上生成文档。每个节点在生成文档时，可以调用其子节点的文档信息（例如方法对类、类对模块）以形成上下文关联。最后，生成的文档会被格式化成Markdown格式，供GitBook等文档工具渲染成图形界面，方便阅读和导航。
3. 文档更新模块
文档更新模块通过使用Git钩子，实时检测代码的更改，并自动更新对应的文档，以确保代码和文档的同步。文档更新的触发条件包括以下几种情况：（1）代码修改：当源代码发生变化时，对应的文档将自动更新。（2）引用关系变更：如果代码对象的引用关系改变，例如函数之间的调用关系发生调整，RepoAgent会更新相关对象的文档内容。（3）代码对象新增或移除：当有新的代码对象添加到项目中或从项目中移除时，RepoAgent会更新项目树并重新生成文档。
文档更新过程是自动化的，无需人工干预，保持了开发流程的连贯性。每次代码变更和文档更新后，更新结果会提交到代码库中，确保开发团队在使用的文档始终是最新的。
4. 实验
在RepoAgent的实验部分，研究人员对九个Python代码库（包括unoconv、simdjson、greenlet、code2flow、AutoGen、AutoGPT、ChatDev、MemGPT和MetaGPT）进行了测试，目的是评估不同大语言模型（LLM）在识别函数参数方面的准确性。使用的模型包括Llama-2-7b、Llama-2-70b、gpt-3.5-turbo和gpt-4-0125。
实验设置旨在观察不同模型作为RepoAgent的后端时，能否准确识别和记录代码中的参数信息，以便生成高质量的文档。各模型在不同代码库上的表现不同，总体上GPT系列模型在参数识别准确性上优于Llama系列模型。
二、gDoc: Automatic Generation of Structured API Documentation
gDoc是由阿里巴巴集团开发的用于生成和维护结构化API文档的自动化系统。它旨在解决API文档生成中的诸多挑战，包括手动更新文档、不一致性、以及对不常用API的支持不足等。传统的文档生成方法通常难以提供一致且完整的API文档，特别是对于复杂的API生态系统。gDoc通过三大核心模块实现了这一目标：
1. 基于搜索的文档生成模块
gDoc系统的核心是一个基于搜索的生成模块，用于在多个API之间共享文档信息，从而提高一致性和生成效率。gDoc观察到在不同API中存在大量重复的参数和描述（如下图所示，在SendSms和AddSmsSign函数中重复出现SignName参数），因此gDoc提出了重复性参数的描述推荐策略。当新API文档生成时，如果系统检测到相同参数存在于其他API中，它会从已有的描述库中推荐相同的参数描述，从而提高文档的一致性和生成效率。
2. 基于Seq2Seq模型的翻译生成模块
在参数描述不能直接从已有文档中获得时，gDoc采用Seq2Seq模型（基于M6模型）来自动生成文档内容。这个翻译模型将API文档生成过程视作自然语言翻译任务。
该模块将API的信息（如参数名、类型等）作为输入，通过Seq2Seq模型生成对应的自然语言描述，从而填补已有文档中缺失的部分。gDoc使用M6模型，这是一个具有多模态预训练的Seq2Seq模型。由于该模型具备强大的自然语言生成能力，gDoc能够生成适用于各种API的详细参数描述，即使是缺乏历史数据支持的API，也能在模型的支持下生成高质量文档。
3. 参数示例生成模块
参数示例是API文档的重要组成部分，gDoc通过分析真实的API请求日志，自动生成有代表性的参数示例，从而使文档内容更加全面。此模块采用了两阶段的Mapper-Reducer方法：
Mapper阶段：特征提取：在Mapper阶段，gDoc从API请求日志中提取出参数值的常见特征，并将这些特征进行抽象。 Reducer阶段：模式压缩：在Reducer阶段，将抽象出的特征进行压缩，形成通用的参数模式，例如，将常见的数值和字符组合抽象为“X_d”（字母+数字的模式），并保留高频使用的值作为推荐示例。
4. 实验部分
gDoc通过在阿里云平台上的部署，评估了系统的文档生成效果。
实验结果如上图所示，实验评估包括以下几部分：
整体接受率评估：在近10周的部署测试中，gDoc的API文档生成结果接受率稳定在80%以上，显示出生成文档的实用性和准确性。 基于搜索的生成模块评估：基于搜索的生成模块有约90%的接受率。这表明在API之间共享参数描述和使用历史数据时，生成的文档更为可靠。 基于翻译生成的模块评估：Seq2Seq翻译模型生成的文档接受率超过70%，证明了在缺乏历史数据支持的情况下，该模型依然能够生成可接受的文档内容。
三、总结
本文从如何利用大语言模型辅助代码文档生成的角度出发，介绍了两个工作：RepoAgent和 gDoc。RepoAgent聚焦于仓库级代码文档生成，通过全局结构分析和上下文关联生成技术，优化了代码文档的一致性和更新效率；gDoc则从结构化文档生成角度出发，结合基于搜索和Seq2Seq翻译的生成模块，提升了API文档的质量与可用性。这些研究表明，LLMs在未来代码文档生成和维护中具有巨大的潜力。
