接手一个12万行的Java老项目，没有一行注释，没有一份文档，连README都是三年前的"初始化项目"五个字，你会不会想把前同事从微信里翻出来？

SpringDoc OpenAPI（Java Spring）

Spring Boot项目最省心的选择。加一个依赖，代码里写几个注解（@Operation、@Parameter），启动项目后访问 /swagger-ui.html，所有接口文档自动生成，还能在线调接口。从SpringFox迁移过来的团队注意版本兼容性，Spring Boot 3.x要用SpringDoc 2.x。

FastAPI 自带文档（Python）

FastAPI最大的卖点之一就是自带OpenAPI文档生成。定义路由时写好类型注解和docstring，自动生成Swagger UI和ReDoc两套文档页面，完全零配置。用了Django REST Framework的团队可以用drf-spectacular或者drf-yasg，效果类似。

swaggo/swag（Go）

在handler函数上加注释（格式类似JSDoc），运行swag init生成docs目录，Gin/Echo/Fiber等主流框架都支持。生成的Swagger JSON可以直接被Swagger UI渲染。

swagger-jsdoc（Node.js）

Express/Koa项目在路由文件头部写JSDoc格式的OpenAPI注释，搭配swagger-ui-express就能生成带在线调试功能的文档页。NestJS更简单，框架内置了@nestjs/swagger模块。

JS/TS项目：JSDoc 和 TypeDoc 怎么选

JSDoc：JavaScript项目首选。在函数上面写/** @param {string} name 用户名 */这类注释，运行jsdoc src -r -d docs就能生成一个完整的HTML文档站。支持自定义模板，社区有几十个主题可选。

TypeDoc：TypeScript项目的首选。和JSDoc的区别在于TypeDoc能直接读取TypeScript的类型定义，不需要在注释里重复写类型。比如你的TS函数已经声明了参数类型是string，TypeDoc自动识别，JSDoc还需要你手动写@param {string}。

选型建议：纯JS用JSDoc，TS项目用TypeDoc。如果是JS+TS混用的项目，两个都装也没问题。

Java项目：Javadoc

Java开发者最熟悉的工具，IDEA里写/**回车自动生成模板。Maven/Gradle项目配一个javadoc插件，打包时自动生成文档。Javadoc的问题是默认样式太朴素了，可以搭配Doclava或自定义CSS美化输出。

Python项目：Sphinx + autodoc

Sphinx是Python社区文档的事实标准，Read the Docs就是用Sphinx搭建的。用sphinx-apidoc自动扫描Python包生成rst文件，autodoc扩展从docstring里提取文档。支持Google风格、NumPy风格、reStructuredText三种docstring格式。输出HTML、PDF、ePub都行。

C/C++/多语言项目：Doxygen

老牌工具，支持C/C++、Java、Python、PHP等20多种语言。配置文件里指定源码目录和输出目录，一键生成带类图、调用图、依赖关系图的完整文档。Doxygen最强的是能生成调用关系图和继承关系图（需要安装Graphviz），对于理解大型C++项目结构非常有帮助。

Go项目：godoc

Go语言自带文档工具，不需要安装任何东西。代码里写好注释（Go有严格的注释规范），运行godoc -http=:6060就能在浏览器看文档。Go官方包的文档（pkg.go.dev）就是godoc生成的。Go 1.19以后推荐用go doc命令行查看。

Storybook

支持React、Vue、Angular、Svelte等所有主流框架。写.stories文件定义组件在不同props下的展示状态，Autodocs功能能自动从TypeScript类型和PropTypes生成Props表格。搭配Chromatic可以做视觉回归测试，发布到Chromatic或GitHub Pages就变成一个在线组件文档站。Ant Design、Material UI、Shopify Polaris等大厂的组件文档都是Storybook搭的。

Vue专属：VitePress + Vite-plugin-pages

Vue团队推出的VitePress（VuePress的继任者），搭配vite-plugin-pages自动扫描组件目录生成文档路由。比Storybook更轻，适合中小型Vue项目的组件文档。

方案一：用AI工具反推注释，再跑文档生成器

现在最实用的做法是分两步走：

第一步——AI补注释：把代码文件丢给Claude Code、GitHub Copilot或Cursor，提示词写"给这个文件的所有函数和类添加JSDoc/Javadoc/docstring注释"。AI能读懂代码逻辑，生成的注释质量比想象中高。一个50个函数的文件，大概2-3分钟就能补完注释。

第二步——跑文档工具：注释补完后，再跑前面说的JSDoc/TypeDoc/Sphinx/Doxygen，就能生成完整文档了。

批量处理几百个文件的时候，可以用脚本遍历文件列表，逐个调AI生成注释再保存。也有现成的工具：Mintlify的VS Code插件可以选中代码一键生成注释，CodeBert（微软开源）可以训练后自动补注释，不过需要一定的配置门槛。

方案二：AI全自动生成项目文档（跳过注释这一步）

如果你不需要"注释→文档"这个传统流程，只是想快速产出一份能看懂的文档给新人或自己用，有更直接的办法：

Claude Code / Cursor：直接在项目根目录打开，问它"帮我分析这个项目的整体架构，生成一份README和模块说明文档"。AI会扫描目录结构、读关键文件、梳理依赖关系，然后直接输出Markdown文档。

ProjectDoc-Skill（开源）：GitHub上有个叫ProjectDoc-Skill的项目，专门做"代码→结构化文档"的自动生成。把代码项目丢进去，一键产出需求规格说明、概要设计、详细设计、API文档等标准文档。适合需要交付文档的乙方团队。

一个容易踩的坑：AI生成的注释不要全信。AI能读懂代码逻辑，但读不懂"为什么要这么写"——业务规则、边界条件、历史原因这些需要人补充。建议AI补完注释后，人工过一遍关键函数，把"为什么"加上去。

GitHub Actions 配置思路

以TypeScript项目用TypeDoc生成文档为例，workflow的核心步骤就四步：

1. actions/checkout 拉代码
2. npm ci && npm run docs（docs脚本里执行typedoc命令）
3. peaceiris/actions-gh-pages 把生成的文档目录推到gh-pages分支
4. GitHub Pages自动部署，文档站就上线了

同样的逻辑套到Sphinx、Doxygen、Storybook上完全通用，换个构建命令就行。

零预算个人项目

按语言选原生工具：Java用Javadoc、JS用JSDoc、TS用TypeDoc、Go用godoc、Python用pydoc（命令行就能跑）。部署到GitHub Pages，完全免费。

小团队（3-10人）

API文档用Swagger生态（各语言有对应的Swagger库），前端组件用Storybook，部署到内网或GitHub Pages。AI工具用Copilot（$10/月/人）辅助补注释，性价比最高。

中型团队（10-50人）

CI/CD集成文档生成是底线——代码合并到主干后文档自动更新。Read the Docs托管Python文档、Chromatic托管Storybook、自建Swagger UI页面。制定统一的注释规范（比如统一用TSDoc标准或Google docstring风格），配ESLint/Checkstyle规则检查注释覆盖率。

大型团队（50人以上）

文档即代码（Docs as Code）理念落地：文档和代码在同一个仓库，同一个PR流程，同一个Review机制。多语言项目统一用Doxygen或自建文档平台。AI工具部署到CI流程中——每次提交自动生成/更新API文档，文档过期自动告警。

文档生成不是终点，文档质量才是

自动生成的文档只能告诉你"这个函数叫什么、参数是什么、返回什么"，但不能告诉你"什么时候该用这个函数、和另一个函数有什么区别、有哪些边界条件要注意"。工具生成的是骨架，肉要人填——至少关键模块和对外接口的文档需要人工补充使用场景和注意事项。

注释规范统一比工具选择更重要

团队里五个人写五种风格的注释，文档生成出来就是灾难现场。在引入工具之前，先定好注释规范：JSDoc用哪种tag、Python docstring用Google风格还是NumPy风格、Java用哪些Javadoc tag。可以配ESLint插件（eslint-plugin-jsdoc）或Python的pydocstyle自动检查注释格式。

"文档即代码"的前提是"有人看文档"

花了很大精力搭了文档生成流水线、部署了漂亮的文档站，结果团队里没人看——这才是最常见的结局。文档站上线后要做两件事：①把文档链接放在项目README最显眼的位置；②新人入职第一周的任务之一就是"对照文档读代码，找出文档里和代码不一致的地方"——既让新人快速熟悉项目，又能发现过期文档。