多语言代码文档生成工具总览_注释驱动契约文档与项目文档体系「根据代码生成文档」在工程里通常指三类交付物不要混为一谈类型典型内容常见手段API / 源码参考类、函数、字段、类型签名与说明Javadoc、Doxygen、Sphinx、rustdoc等接口 / 契约文档HTTP 路径、请求体、错误码RPC 消息定义OpenAPI/Swagger、gRPC protobuf项目 / 产品文档背景、架构、部署、快速开始README、MkDocs、Docusaurus等本文是多语言、多工具的总览地图每种栈只给定位、输入形态与选型一句不展开配置与管线细节。JavaJavadoc/Dokka与C/CDoxygen请读仓库内专文其它语言以官方文档为准。阅读提示正文含Mermaid静态站需开启 Mermaid 渲染。目录1. 总览三类文档如何组合2. 注释驱动工具速查按语言3. Java / KotlinJVM4. C / C 及多语言大仓5. Python6. JavaScript / TypeScript7. Go8. Rust9. 契约文档OpenAPI 与 gRPC10. 项目级文档放哪11. 最小可行组合刚起步12. 选型速查13. 延伸阅读与免责声明1. 总览三类文档如何组合人工撰写 站点README / docs/MkDocs / Docusaurus从接口定义OpenAPIprotobuf 插件从源码注释Javadoc / DokkaDoxygenSphinx / pdocTypeDoc / JSDocgodocrustdoc统一文档站点或制品库常见发布形态README.md作入口 →docs/api/放生成的 API 站 →docs/放架构与运维说明CI 里javadoc/doxygen/sphinx-build与站点构建同一流水线产出。共同前提注释驱动类文档正文来自声明上方的约定注释如 Java 的/** */、Rust 的///行内//、普通块注释、方法体内说明通常不会被提取个别工具、插件或定制流水线存在例外以官方说明为准。具体规则因工具而异见各语言专文或官方手册。2. 注释驱动工具速查按语言语言 / 栈主流工具典型输出一句话JavaJavadocHTMLJDK 自带生态默认。Kotlin / 混合 JVMDokkaHTML、Markdown 等Kotlin 官方路线多格式。C/C及多语言DoxygenHTML、LaTeX、XML…功能全、配置重大仓常见。PythonSphinx autodocHTML 等库与科学计算圈最主流。PythonpdocHTML轻量、上手快。JS/TSTypeDocHTMLTS 类型信息友好。JSJSDocHTML传统 JS 项目常见。Gogodoc/pkgsite网页与包路径、注释约定强绑定。RustrustdocHTML语言内置cargo doc。3. Java / KotlinJVM工具适用本篇深度Javadoc纯 Java 或 Java 为主的 API 站仅概括DokkaKotlin、或需Markdown/PDF等多格式仅概括输入类、接口、方法、字段上的/** */及param、return等标签。输出Javadoc 以HTML为主含单文件 HTML等选项其它格式常经Dokka或HTML 后处理。MarkdownDokka 等生成的 Markdown 是结构化 API 说明类/方法/参数表不宜直接当作产品文档或架构说明叙事内容仍放在README / docs/与 §1 三类文档划分一致。项目级说明用README、package-info.java包级模块介绍不要把整篇架构硬塞进某个类。深入阅读仓库内Java_API文档生成全解_从javadoc原理到Dokka选型原理、命令行、Maven/Gradle、Dokka 与 OpenAPI 边界。4. C / C 及多语言大仓Doxygen从带标记的注释与语法信息建符号库可出HTML、LaTeX、Man等可选Graphviz做调用图/类图。也常被用于混合语言仓库的统一 API 站但Doxyfile学习与维护成本较高。深入阅读仓库内Doxygen详解_源码文档生成_Doxyfile注释命令与调用图及渲染管线Doxyfile、注释命令、渲染管线、CI。5. Python工具特点Sphinx autodoc与reStructuredText / MyST结合适合库文档 叙事章节一体站点。pdoc配置少由 docstring 直接生成HTML适合中小项目。pydoc标准库自带适合本地快速查看少作正式对外站点。输入模块、类、函数的docstringGoogle / NumPy / Sphinx 等风格需在团队内统一。官方起点https://www.sphinx-doc.org/、https://pdoc.dev/以当前项目文档为准。6. JavaScript / TypeScript工具特点TypeDoc面向TS 类型与声明生成结构化HTML API。JSDoc传统/** param … */注释 → HTML纯 JS 项目仍常见。前端 monorepo 常把TypeDoc 输出嵌进VitePress / Docusaurus与Playwright E2E、OpenAPI文档并列发布时注意入口页在 README 中写清链接。7. Gogodoc通过go doc、历史godoc.org心智理解「包注释 导出符号注释」即可。pkgsite当前pkg.go.dev背后的文档呈现方式仍依赖包注释package前块注释与导出标识符的注释。特点注释即文档的文化强未导出符号通常不进入对外 API 叙述。8. Rustrustdoccargo doc生成crate文档常用///项前与//!crate/模块级。与docs.rs发布习惯一致内联示例rust代码块可在文档中可运行测试cargo test的 doc test。官方起点https://doc.rust-lang.org/rustdoc/9. 契约文档OpenAPI 与 gRPC与「扫源码注释」不同这类工具以接口定义为源方式源典型场景OpenAPISwaggerYAML/JSON 或框架注解REST/HTTP 服务SpringDoc、FastAPI、NestJS 等可从代码生成或契约先行。gRPC protobuf.protoRPC 服务protoc插件生成HTML/Markdown或接入Buf等工具链。与 Javadoc 的关系Java 服务可同时有JavadocJava API与OpenAPIHTTP 面读者对象不同宜分目录发布勿混在一个导航里让人误以为同一套「类文档」。10. 项目级文档放哪内容建议位置说明项目简介、构建运行README.md仓库首页与文档入口。架构、运维、规范docs/*.md与 API 生成分离。模块 / 包级说明JVMpackage-info.java出现在Javadoc 包页非整站首页。统一站点MkDocs / Docusaurus / GitLab Pages把README、叙事文档、嵌入的 API 子站串成导航。原则注释生成器 代码结构的说明书产品故事与部署由人工维护的 Markdown承担通过链接与 API 站并列发布。11. 最小可行组合刚起步若目标是先有一套能用的文档不必一次上齐 Doxygen、OpenAPI、MkDocs 与多格式输出。可按栈选用最小组合栈最小组合暂不引入可后补JavaREADME.mdJavadoc →docs/api/Dokka 多格式、OpenAPI无对外 HTTP 契约时KotlinREADMEDokka HTML或沿用 Javadoc 流程PDF、独立文档站点PythonREADMEpdoc或Sphinx 单页 autodoc复杂 MyST 多卷手册TypeScriptREADMETypeDoc与 OpenAPI 合并导航有 REST 再拆C/CREADMEDoxygen HTML见专文最小 DoxyfileGraphviz 全量调用图、LaTeX任意服务有对外 HTTP/RPC时再加 OpenAPI 或.proto文档与 API 参考混在同一页落地三步① 在public 导出 API上补约定注释② CI 或本地脚本固定一条生成命令③README里写「如何构建文档」与API 入口链接。12. 选型速查你的情况优先考虑Java 库 / Android SDK APIJavadoc细节见 JVM 专文Kotlin 或多格式文档Dokka见 JVM 专文C/C 或混合语言大仓Doxygen见 Doxygen 专文Python 库 长文档SphinxPython 要快pdocTypeScript 库TypeDocGo 模块包注释 go doc/ pkg 站点习惯Rust craterustdoc / docs.rsHTTP 服务对外契约OpenAPIgRPC 服务protobuf 文档插件只要一张地图本文 对应语言专文 / 官方手册13. 延伸阅读与免责声明13.1 仓库内专文深入Java_API文档生成全解_从javadoc原理到Dokka选型Doxygen详解_源码文档生成_Doxyfile注释命令与调用图及渲染管线13.2 官方入口外部Javadochttps://docs.oracle.com/en/java/javase/选你所用 JDK 版本的Tool Guides → javadocDokkahttps://kotl.in/dokkaDoxygenhttps://www.doxygen.nl/Sphinxhttps://www.sphinx-doc.org/TypeDochttps://typedoc.org/OpenAPIhttps://spec.openapis.org/Rust rustdochttps://doc.rust-lang.org/rustdoc/13.3 免责声明工具版本、默认输出格式与 CLI 子命令随发行版变化生产流水线应锁定工具版本并在 CI 中固定生成命令。建议在 CI 中使用固定版本的工具镜像或lockfile 钉死的 Maven/Gradle/npm 依赖避免主版本升级导致文档结构、锚点链接或主题样式突变。本文不替代各工具官方手册亦不涵盖 IDE 临时导出、商业文档平台等周边方案。