Doxygen代码文档生成教程与实用技巧

最近整理老项目，发现代码里注释写得挺全，但想给别人看的时候还得翻源文件，特别费劲。后来同事推荐了Doxygen，试了一下，直接把注释转成了网页版的文档，看着跟官方手册似的。这篇就把我折腾Doxygen代码文档生成的整个过程记下来，包括怎么装、怎么配、注释怎么写，还有中文乱码这种坑，尽量说人话，新手也能跟着做。

先装Doxygen，再搞个辅助工具

Windows下直接去官网下安装包，一路下一步就行。Mac用brew，Linux用apt-get，命令都差不多。装完之后你会在开始菜单看到Doxygen GUI，那个是图形化配置工具，对不熟悉命令行的人挺友好。

但光装Doxygen还不够，生成文档后默认界面比较朴素。我建议顺手装个Graphviz，这玩意儿能画类图、函数调用关系图。不装也能出文档，就是少了图，看着不够直观。另外如果你项目里用了中文注释，记得把源码文件保存成UTF-8，不然生成的HTML里全是乱码，这个后面细说。

注释别乱写，按Doxygen的规矩来

Doxygen不是随便什么注释都能认的。它有一套自己的标记，比如@brief写简短说明，@param写参数，@return写返回值。刚开始我觉得麻烦，后来发现写习惯了反而清晰，因为格式固定，看代码的时候一眼就能找到关键信息。

举个简单的例子，一个函数上面这么写：

/**
* @brief 计算两个整数的和
* @param a 第一个加数
* @param b 第二个加数
* @return 两数之和
*/

这样Doxygen就能抓取到，生成文档时自动排版。注意@brief后面跟一句话就行，别写太长，详细说明可以另起一段。我一开始把所有东西都塞进@brief，结果文档里挤成一团，后来拆开才顺眼。

图形化配置，点几下就出文档

打开Doxygen GUI，第一步选项目目录，就是你的源码文件夹。第二步切换到Expert模式，里面选项很多，但新手只需要关注几个地方。在Project标签里填项目名、版本号、输出语言，语言一定选Chinese，不然界面是英文的。在Output标签里选输出格式，一般勾HTML就够了，想生成PDF还得装LaTeX，太折腾，不推荐。

在Input标签里把源码目录加进去，文件扩展名根据你的语言填，比如C++就填.cpp .h。然后Build标签里有个EXTRACT_ALL，勾上它，不然没有注释的函数不会出现在文档里。都设置好之后点Run，等进度条走完，去输出目录打开index.html，文档就出来了。

我第一次跑的时候忘了勾EXTRACT_ALL，结果文档里只有几个类，函数全不见了，还以为软件坏了。后来才发现是这个选项的问题，勾上就正常了。

中文乱码和路径问题，这两个坑最常见

中文乱码基本是编码问题。Doxygen默认按UTF-8读源码，如果你的文件是GBK编码，注释里的中文就会变成问号或者方块。解决办法要么把源码转成UTF-8，要么在配置里改INPUT_ENCODING为GBK。我建议直接转UTF-8，一劳永逸，现在编辑器都支持。

另一个坑是输出路径带中文或空格。Doxygen有时候会报错，说找不到文件。尽量把项目放在纯英文路径下，比如D:\projects\mycode这种，别放在桌面上，桌面路径里带用户名，有时候也有问题。

还有个小技巧，如果项目很大，生成一次要好久，可以在配置里把GENERATE_LATEX关掉，只生成HTML，速度快很多。平时改注释后重新生成，也就几秒钟的事。

总的来说，Doxygen代码文档生成这件事，装好工具、按规范写注释、配置里注意编码和路径，基本就能跑通。生成出来的文档可以直接丢到内网或者GitHub Pages上，别人查起来方便，自己也省得写Word。花半小时折腾一次，后面一直受益，挺值的。