只要写过一段时间代码你一定经历过这种场面项目做了大半年中间换了两拨人手新同事面对一个几百行的头文件挨个猜函数而你自己翻三个月前的代码也要倒吸一口气。文档不是不想写是手写文档永远追不上代码变更的速度写完的那一刻就已经过时了。Doxygen 就是干这个用的——它是目前最主流的源代码文档自动生成工具支持 C/C、Java、Python、Fortran、C# 等语言你只需要在源码里按规范写注释工具就能把注释抽出来自动生成带完整目录、索引和调用关系图的 HTML 或 PDF 文档。这篇文章是我这些年实际用 Doxygen 的总结不是官方文档的翻译版。我会从“它到底是什么”讲起然后是安装、注释语法、Doxyfile 配置、常见问题排查最后聊聊怎么把 Doxygen 接进团队的工作流。无论你是第一次听说这个名字还是已经用它生成过一版文档但觉得不好看应该都能从中找到有用的东西。1. Doxygen 到底解决了什么问题1.1 先理解“文档为什么总是烂尾”很多人对代码文档有个误解觉得文档烂尾是因为懒。我见过勤快到天天写日志的团队照样维护不了一份像样的接口文档。问题的根源不是态度而是“双份维护”的结构性矛盾代码写一遍文档再写一遍改代码的时候很少有人记得去同步文档。时间一长文档就变成了和代码毫无关系的另一份文件。Doxygen 的解题思路是把这两份东西合并成一份。注释写在代码里文档由工具扫描源码自动生成。函数改了注释就在函数上方跑一次 Doxygen 文档就跟着变了。注释不会被遗忘因为代码评审的时候能看到文档不会过期因为它和代码共用同一个文件生命周期。这套思路并不算新Java 有 JavadocPython 有 Sphinx 搭配 docstring但 Doxygen 在跨语言能力和 C/C 生态上是做得最深的。我最早是被它的调用关系图吸引的——一个几万行的老项目用 Doxygen 一跑每个函数的谁调用了谁、被谁调用全都能画出来这对接手老代码的人来说简直是救命稻草。1.2 它能输出哪些东西Doxygen 最常见的输出是 HTML 文档双击 index.html 就能在浏览器里浏览带侧边栏目录、搜索框、文件列表和类列表。它也能生成 LaTeX 格式再编译成 PDF还能输出 RTF、man page、XML 等格式。比格式更重要的是它自动生成的那些“关系信息”包含文件依赖图一个头文件 include 了哪些文件谁又 include 了它类继承图基类和派生类之间的完整关系调用关系图/被调用关系图每个函数调用了谁、被谁调用成员变量列表结构体和类的字段一览这些图依赖 Graphviz 这个外部工具。第一次用的人经常遇到 HTML 生成了但全是文字没有图十有八九就是没装 Graphviz这个我后面会专门讲。1.3 谁适合用 Doxygen如果你符合下面任意一条Doxygen 就值得你花半天时间试一下你在写 C/C 库需要给调用方一份清晰稳定的接口文档你接手了一个老项目面对几千个函数不知道从哪里看起你维护开源项目GitHub Pages 上的 API 文档想自动更新而不是每次手动改你在带团队希望代码里有个统一、可检索的注释规范我不是说任何项目都该上 Doxygen。一个脚本味很浓、没有明确接口边界的项目或者一个三五个人写完就丢的一次性项目用 Doxygen 的收益确实有限。判断标准很简单你的代码有没有“别人看”和“以后回头看”的需求。2. 三步跑通第一次文档生成2.1 不同系统下的安装方式Doxygen 的安装没什么玄学。Ubuntu/Debian 上一行命令sudo apt install doxygen doxygen-guimacOS 用 Homebrewbrew install doxygenWindows 上可以下载官方安装包也可以走包管理器choco install doxygen需要特别提醒的是如果你想生成调用图CALL_GRAPH 和 CALLER_GRAPH 这两个选项依赖 Graphviz 里的 dot 命令Ubuntu 下要额外装sudo apt install graphvizmacOS 就brew install graphviz。装完可以验证一下doxygen --version dot -V两个命令都有输出说明环境就绪了。2.2 用 doxygen -g 生成配置文件模板Doxygen 不要求你从零写配置。在项目根目录执行doxygen -g Doxyfile它会生成一个内容极其丰富但也很长的配置文件几乎每个参数都有注释说明。我见过有人看到这个文件几百行就直接放弃了其实真正要改的就那么几个。如果你用的是图形界面 Doxywizard也可以直接在界面里点选它会帮你维护同一个 Doxyfile。如果你在服务器上跑批量任务命令行方式更顺手。2.3 第一次运行与基本参数调整我建议第一次跑的时候先做一个最小配置用文本编辑器打开 Doxyfile改这几项PROJECT_NAME My Project OUTPUT_DIRECTORY ./doc INPUT ./src RECURSIVE YES GENERATE_LATEX NO改完保存执行doxygen Doxyfile跑完你会得到 doc/html/index.html用浏览器打开。如果注释里还没写 Doxygen 风格的标记页面会比较空这很正常。你还可以加一个参数让文档先“好看”起来EXTRACT_ALL YES这个参数的意思是代码里没有写文档注释的类、函数、变量也一并提取展示。第一次跑项目的时候建议开先看到全貌后面再关掉逼自己把关键接口注释补起来。2.4 一眼看懂生成目录Doxygen 默认的输出目录结构大致是doc/ ├── html/ ├── latex/ └── xml/html 目录里最重要的就是 index.html。里面分成几个大类项目名下的模块列表类列表、文件列表类的成员索引、函数的全部成员索引文件依赖图和全局调用图如果开了相关选项浏览的时候我习惯先看“类索引”或“文件索引”从顶层往下钻。新接手代码的人重点看“目录 → 类 → 成员函数”这条路就能快速摸清项目结构。3. 注释怎么写才好看且好用3.1 文件头的模块说明Doxygen 能识别几种注释风格。C/C 里最推荐的是/** ... */它和普通块注释的区别是开头多了个星号Doxygen 一看到就知道是文档注释。也可以使用//!或///这种行注释风格。一个完整的文件头注释我通常这样写/** * file math_utils.h * brief 常用的数学计算工具 * author 张三 zhangsanexample.com * date 2025-03-21 */ #ifndef MATH_UTILS_H #define MATH_UTILS_Hfile必须写否则在文件列表里看不到这个文件brief是摘要会显示在文件列表和类列表的概要位置author和date属于元信息看代码历史的时候方便。如果你负责一个库还可以用defgroup把散落的功能模块归类这个后面详细讲。3.2 函数注释的黄金法则函数注释是 Doxygen 里最核心的部分也是最容易写好的。我给自己定的标准是必须写出param和return另外想办法在简短描述里说明这个函数存在的意义。一个合格的函数注释长这样/** * brief 计算两点之间的欧氏距离 * param p1 第一个点的坐标指向包含至少 3 个 double 元素的数组 * param p2 第二个点的坐标指向包含至少 3 个 double 元素的数组 * param dim 坐标维数必须大于 0 * return 两点之间的距离如果 dim 为 0返回 0.0 * warning p1、p2 必须指向有效内存否则行为未定义 */ double distance(const double *p1, const double *p2, int dim);光一个param p1 点的坐标是不合格的。从使用者的角度想他需要知道 p1 指向什么、长度至少是多少、有哪些隐藏约束。注释写得越具体调用方的误会就越少。这就是 Doxygen 文档比手写文档强的地方——它就在代码上方任何一次修改都能被看见。还有一个容易被忽略的命令是see它可以关联到相关函数/** * brief 根据文件名读取配置 * ... * see save_config() */生成的文档里会自动带“参见”链接读者能在相关函数之间跳转。这在梳理复杂模块时特别有用。3.3 类、结构体和成员变量怎么注释面向对象代码的注释重点在类语义和成员函数。类注释写清楚“这个类负责什么怎么用有什么生命周期要求”/** * brief 基于环形缓冲实现的队列 * tparam T 元素类型 * note 线程不安全外部需要加锁 */ template typename T class RingBuffer { public: /** * brief 向队尾写入一个元素 * param item 要写入的元素 * return true 表示成功false 表示缓冲区已满 */ bool Push(const T item); };tparam用于模板参数的说明容易漏值得写上。成员变量的注释用行注释风格比较方便class RingBuffer { private: T *buffer_; /// 底层存储区域由构造函数分配 size_t head_; /// 队头位置读取时移动 size_t tail_; /// 队尾位置写入时移动 };注意///这个斜杠加两个星号的位置它表示“注释跟在变量后面”生成的文档会把这个注释挂在对应成员变量旁边。这种写法对结构体特别友好typedef struct { int x; /// 横坐标 int y; /// 纵坐标 } Point;3.4 分组把散落的接口变成模块项目大了以后单纯按文件组织文档会让人迷失。Doxygen 的defgroup和{ ... }可以自定义模块。比如我有几个文件都跟网络有关我把它们归到一组/** * defgroup network 网络模块 * brief 封装 TCP/UDP 连接逻辑 * { */ int net_connect(const char *host, int port); int net_send(int fd, const void *buf, size_t len); int net_close(int fd); /** } */把{放在defgroup下面告诉 Doxygen在这个括号范围内的注释都属于这个组。生成的 HTML 里“模块”列表就会出现“网络模块”里面聚合了这三个函数。后续再加函数只要放在}之前就行。这个功能最大的价值是打破“一个函数只能属于一个文件”的限制让你按业务域组织接口文档。3.5 Python 等其他语言的注释Doxygen 对 Python 也有较好的支持使用的是 docstring 形式def calculate_rmse(actual, predicted): 计算均方根误差 param actual: 真实值列表 param predicted: 预测值列表 return: 均方根误差值 raise ValueError: 两个列表长度不一致时抛出 Doxygen 会解析 Python 的类、函数和模块结构文档风格与 C/C 保持一致。Java 风格类似 Javadoc也直接适配。这就是 Doxygen 的“跨语言”魅力——一个工具统一多个语言项目的文档。4. 手把手调出适合团队的 Doxyfile4.1 项目信息与路径设定Doxyfile 里第一个值得认真填的参数是PROJECT_BRIEFPROJECT_NAME MyProject PROJECT_BRIEF 高性能网络通信库PROJECT_BRIEF会显示在每个页面的标题区域写清楚一句话就够了不用长篇大论。OUTPUT_DIRECTORY建议统一指向 doc 目录这样生成的内容不会散落到源码树里。还建议加一行CREATE_SUBDIRS YESHTML 文件会分目录存放避免几千个文件堆在一个目录里导致打开变慢。如果你要直接把 docs 发布到 GitHub Pages 或内部 Wiki这个设置也能让文件管理更清晰。4.2 INPUT 与文件过滤不要乱扫INPUT是 Doxygen 扫描的路径。以前我图省事直接把整个仓库根目录塞进去结果它把 build、.git、third_party 全都扫了一遍光解析就跑了十分钟还在文档里生成了一堆毫无意义的内部文件。正确的做法是只喂给它真实的源码目录INPUT src include examples FILE_PATTERNS *.c *.cc *.cxx *.cpp *.h *.hh *.hpp *.inl RECURSIVE YES EXCLUDE_PATTERNS */build/* */third_party/* */.git/*FILE_PATTERNS按语言扩展名筛选EXCLUDE_PATTERNS用通配符排除目录。第三个建议是尽量把 tests 目录也排掉单测代码对接口文档没有贡献还容易污染类列表。这里有个经验值Doxygen 扫描的源码规模控制在 5 万行以内通常几秒到十几秒就能跑完。超过 20 万行就要考虑是不是该给 ext 目录单独生成一份文档了。4.3 EXTRACT 系列参数开多少合适Doxyfile 里 EXTRACT 开头的参数决定了“哪些代码会被提取”。我的建议是分阶段调整项目刚开始铺文档时EXTRACT_ALL YES先把全貌建出来文档整理到一定阶段EXTRACT_ALL NO只展示写了注释的接口对内部实现也值得写文档的稳定库开EXTRACT_PRIVATE YES和EXTRACT_STATIC YES这个系列里还有一个EXTRACT_PACKAGE对 Java 开发者比较重要。但一般不建议在文档成熟后长期开着EXTRACT_ALL否则一堆没注释的成员会让文档看起来像烂尾工程反而不利于团队意识统一。我自己常用的一版是EXTRACT_ALL NO EXTRACT_PRIVATE YES EXTRACT_STATIC YES既要让内部实现可见又要保证面向使用者的文档足够专注干净。4.4 图和链接让文档活起来前面提到依赖图、调用图要靠 Graphviz对应的配置是HAVE_DOT YES CLASS_GRAPH YES INCLUDE_GRAPH YES INCLUDED_BY_GRAPH YES CALL_GRAPH YES CALLER_GRAPH YES这里的每一个“GRAPH”都会增加生成时间。我见过一个大型项目把所有图都打开生成耗时从 5 秒涨到 40 秒。如果文档是每次提交时自动生成的时间成本就需要权衡。我的建议是一个超过 3 万行的项目日常生成只保留CLASS_GRAPH和INCLUDE_GRAPH调用图看具体需要再开或者只在本地跑、不上传到 CI。另外SOURCE_BROWSER YES和REFERENCED_BY_RELATION YES这两个参数也很值得开。前者让文档里能直接浏览源码后者让每个函数文档里列出“被谁调用了”这在阅读理解老代码时非常关键。5. 踩过的坑乱码、缺图、注释不生效5.1 中文乱码问题Doxygen 对 UTF-8 的支持在历代版本里都有过波动。如果你打开 HTML 看到中文变乱码排查顺序是INPUT_ENCODING UTF-8 OUTPUT_LANGUAGE Chinese第一行告诉 Doxygen 源码注释用什么编码读第二行决定界面文字用什么语言。多数情况下这样设置就够了。还有一种是 Windows 下文件夹路径里带中文导致文件读取失败这个要用FULL_PATH_NAMES NO来弱化影响。HTML 头部还需要确认 meta 标签。有时候你把项目名设成中文页面标题乱码但正文正常那是浏览器解析编码问题。可以在HTML_HEADER里自己定制模板或者干脆用HTML_EXTRA_STYLESHEET指定一份 CSS。对多数团队来说最简单稳妥的方案就是保证源码和 Doxyfile 都以 UTF-8 保存。5.2 注释写了却没有进入文档这种情况最常见的原因有三个。一是注释格式不对。Doxygen 只认/** */、///、//!这几类普通的/* */和//会被当成普通注释忽略。检查一下brief前面的星号是不是并排的。二是EXTRACT_ALL设为 NO而某个函数确实没写任何 Doxygen 注释那它就不会出现在文档里。这个符合预期不算 bug。怕的是你把EXTRACT_ALL NO又在网上搜到一篇文章告诉你“注释了但看不见”其实你注释的是结构体里的成员但结构体本身没有文档注释成员也会被带下去。三是INPUT路径不对。Doxygen 不会报错你给了个空目录它就安静地生成一个空文档。我调试时经常用这条命令确认它到底扫描了什么doxygen -x Doxyfile-x会显示所有非默认配置快速确认 INPUT 和 FILE_PATTERNS 是否按预期生效。5.3 HTML 里没有任何图装了 Doxygen 没装 Graphviz是最普遍的原因。前面说过dot -V能验证。装完 Graphviz 后还要确认 Doxyfile 里的HAVE_DOT YES确实设了否则 Doxygen 依然不会调用 dot。如果你的图时有时无多半是某些元素之间的关系没有被 Doxygen 识别。比如调用图要求函数之间有真正的调用关系函数指针、虚函数这类间接调用基本画不出来。这时候不要慌先找个最简单的两个函数看看能不能出图再逐步排查。5.4 生成太慢与文件太多Doxygen 的最大短板是解析速度。老项目动辄几十万行加上模板元编程能把 Doxygen 卡到怀疑人生。我的解决办法分为三层首先严格限定 INPUT 和 EXCLUDE_PATTERNS把第三方库和生成代码全部排除。 其次把HAVE_DOT暂时关掉跑一版纯文本 HTML速度能快一倍以上。需要看关系图时再单独开。 最后如果项目已经大到单次生成超过一分钟可以考虑用PREDEFINED处理条件编译宏减少 Doxygen 解析分支。还有一个隐藏很深的坑有些项目用了大量模板开启TEMPLATE_RELATIONS YES会让文档展示所有模板实例关系速度骤降。不是特别需要就别开。5.5 每次重新生成后浏览器缓存旧页面HTML 更新后浏览器缓存可能导致页面还是旧的。这个不算 Doxygen 的问题但团队协作时经常让人抓狂。CI 生成文档后建议加个时间戳或者在页脚显示生成时间。Doxygen 支持PROJECT_NUMBER可以塞进构建号或 git short SHA这样一眼就能看出文档是哪次提交生成的PROJECT_NUMBER $(VERSION)给每次构建注入版本号文档和代码就能精确对应起来。6. 把 Doxygen 变成团队规范的一部分6.1 三步集成到自动化流程如果只是自己偶尔生成一次Doxygen 的价值会打折扣。真正让文档活着的方式是把它挂到 CI 里每次合并代码都重新生成。第一步准备一个独立的构建脚本比如 scripts/gen_docs.sh#!/bin/bash set -e VERSION$(git rev-parse --short HEAD) sed -i s/PROJECT_NUMBER.*/PROJECT_NUMBER $VERSION/ Doxyfile doxygen Doxyfile第二步把生成的 doc/html 目录发布到内部 Web 服务器或 GitHub Pages。GitHub Actions 里可以用官方自带的 actions-gh-pages或者纯 shell 推到 gh-pages 分支。第三步在 CI 流水线的 PR 检查阶段跑一次 Doxygen只要注释语法有误、配置存在路径问题构建就会失败。这样一来Doxygen 配置本身也成了被测试的对象。这套流程跑通后文档不再是某个人心血来潮手动点出来的产物而是每次代码变更的自动产物。6.2 团队注释规范的几个约定Doxygen 提供了语法但“注释写什么、写到什么程度”需要团队自己定。我参与过的项目里能长期执行的规范往往很轻只有几条对外发布的 API必须有brief、param、return所有头文件必须有文件级注释注明职责和维护人非平凡的私有函数允许只写brief但param至少覆盖所有入参warning和note只在确实有坑时使用不要滥用太重的规范执行不下去“每个函数都必须 50 字说明”这种要求只会逼大家写废话。文档注释应该像代码注释一样讲“为什么”少讲“是什么”。6.3 和老代码并存的处理技巧给历史项目补注释的时候别指望一天把所有文件全补完。我的习惯是分模块推进先挑调用方最多的公共接口比如核心数据结构、网络入口、配置加载这些补完一批就生成一版文档肉眼可见地变完整。如果代码里已经有大量非 Doxygen 格式的注释也不必强行改。Doxygen 提供了JAVADOC_AUTOBRIEF YES它允许你只写第一句普通注释就自动识别为简要描述降低迁移成本。常规注释和 Doxygen 注释混用文档一样能生成只是有些内容不进文档而已。这个过程最怕的是“完美主义”觉得某个文件要一次到位。实际经验是先让文档能跑起来再逐步把接口补完整文档覆盖率会自然上升。6.4 一个够用的团队配置模板直接把下面这段存成团队的 Doxyfile 基线多数项目都能直接用PROJECT_NAME Your Project PROJECT_BRIEF 一句话介绍你的项目 OUTPUT_DIRECTORY doc CREATE_SUBDIRS YES INPUT src include RECURSIVE YES FILE_PATTERNS *.c *.cc *.cpp *.h *.hh *.hpp *.inl EXCLUDE_PATTERNS */build/* */third_party/* */.git/* EXTRACT_ALL NO EXTRACT_PRIVATE YES EXTRACT_STATIC YES GENERATE_HTML YES GENERATE_LATEX NO HTML_OUTPUT html SOURCE_BROWSER YES REFERENCED_BY_RELATION YES ALPHABETICAL_INDEX YES HAVE_DOT YES CLASS_GRAPH YES INCLUDE_GRAPH YES INCLUDED_BY_GRAPH YES CALL_GRAPH NO CALLER_GRAPH NO INPUT_ENCODING UTF-8 OUTPUT_LANGUAGE Chinese这套配置生成速度快文档信息量足够关键关系图都有了而且不依赖任何私有插件换台机器克隆仓库就能跑。从第一次跑通 Doxygen 到现在我最大的感受是文档工具最大的价值不是帮你写文档而是帮你建立一个“注释需要被看见”的反馈循环。注释写得好不好生成出来的文档一目了然哪个模块还缺描述翻两下就能发现。代码总有新旧交替接口总有变动但只要这个循环在文档就不会真正死掉。最后分享一个我很喜欢的小技巧Doxygen 可以识别代码里的\example命令把某个可编译的小示例直接嵌入文档。写库的时候给每个核心接口配一个能跑的 example文档的可读性会有质的提升。这个习惯我从 C 库一直带到现在的 C 项目里新同事上手的速度肉眼可见地变快。