doxygen 5分钟

请用5分钟阅读本文，然后立即投入实践，养成良好的文档习惯，你将节约无数宝贵的屎山打滚时间。

先澄清几个误区：

1. doxygen 不是写文档的：文档还是要自己写，doxygen 是抽取文档并展示、索引的工具

2. 我的屎山项目没文档，doxygen 对我没用：现在是你最需要doxygen 的时候，它可以通过代码解析生成一份超出你预期的基础文档

3. doxygen 会改变我的工作习惯：doxygen 可以和你的git push 动作绑定, 自动完成工作。最多你按照规范格式写注释，这事儿有利无害。
   

doxygen 功能非常多，我只介绍10%最常用的。假设你有一个C++ 工程（doxygen 支持多数主流语言），希望对工程内 src 文件夹内所有头文件和cpp文件生成文档。

初始化配置文件

先进入src 目录，这不是必要的，但这是最自然的。

运行：doxygen -g cpp-template,  生成一个叫 cpp-template 的配置文件。

修改配置文件

按照上一步提示，修改 cpp-template 文件，根据自己的需求订制输出文档的格式、内容。下面是几个主要的配置：

以上内容不言自明，挑出来是因为配置参数太多（260+），这些是我修改过的。

• optimize_output_for_c : 强化对c 、c++ 语言的解析

• optimize_output_for_java: 强化对java、python 等语言解析，比如包和路径的对应

• call_graph, caller_graph: 静态分析函数调用关系, 并生成图形

• dot_path: 图形绘制引擎，这个需要安装 dot/graphviz ， 我的配置在linux 的默认路径，不需要特别配置，这里留空

• planuml_jar_path: 如果需要UML输出，需要告诉doxygen 插件位置，这个插件很多产品都有，我指向了Pycharm :wq
  

生成文档

保存配置后，运行 doxygen cpp-template , 视项目规模和输出内容丰富程度，几秒或者更长时间文档就会生成在当前目录下的 html 文件夹（如果不存在则创建），也可以指定输出位置。

以上就是html 目录内容， 不要在此停留，此时你有2个选择：

1. 打包拿到本地，用浏览器打开 html/index.html 

2. 放到www服务器，如同正常网站一样发布，让团队的人都可以访问到

主页面

类视图

类协作图是dot 自动生成的

函数视图

调用和被调关系是 dot 自动生成的

像老手一样用doxygen

按照上述3个步骤，可以在几分钟内获得一份基础文档。 

为什么说基础呢，这个文档是通过代码解析+原始注释抽取获得的，如果完全没注释或者注释很少，提取的就全部是底层的机器逻辑，从信息上说和你直接看代码没区别，只是它极大加速了这个过程。下面是一些更好使用doxygen 的技巧。

• 按照标准模板注释，可以帮助doxygen 更准确生成文档。零注释是可以的，但是生成的都是底层逻辑。

• 大工程有很多优化配置，比如分多层子目录，缓存设置，调用链长度限制

• 调用latex 生成更本地化的文档， 也可以生成带索引的chm 文件

• 用 pre-commit 将 doxygen 文档刷新和 git 提交绑定，每次文档和代码同步更新

• 将html 链接到服务器 html 目录， 文档-代码-网站同步

• 用include， exclude， suffix 参数精细控制文档范围