Doxygen工具简单使用

简述

Doxygen是一款非常方便的文档生成工具,以类似JavaDoc风格描述的文档系统,完全支持C、C++、Java等语言,据说也支持python等。用他不仅可以根据注释生成文档,而且还能利用graphviz工具生成类图以及类中的函数调用关系,并且支持html、latex、rtf等格式的输出。

安装

有apt支持,直接$sudo apt install doxygen即可。

编写注释

即使不是刻意采用doxygen工具的标准语法,我们也是可以用doxygen生成文档的,只是他提供的信息可能不是很完整,分类也不是很恰当。不过如果使用了doxygen支持的类javadoc的注释方法,那么生成的文档就会相当好看了。

关于简单的注释规范可以参考这篇文章: 基于Doxygen的C/C++注释原则。由于最近没有什么需求,暂时不研究。

生成文档

最简单的生成文档的方法,就是指定项目目录,输入$doxygen 项目根目录即可在该目录下生成一个html文件夹和latex文件夹,这里面放的就是该项目的文档。不过这样有一个问题,就是doxygen默认不会去递归整个文件树,而是只查找当前目录下的代码,这就很讨厌了,很多情况下只能找到一两个头文件。。。

为了更好的生成文档,doxygen需要首先生成一个配置文件,利用$doxygen -g 命令来生成一个名叫Doxyfile的文件。这个文件里有诸多选项,包括PROJECT_NAME、PROJECT_BRIEF、OUTPUT_DIRECTORY等直观的配置,当然也有很多配置细节,可以参考doxygen使用总结这篇博文。

有了这个Doxyfile,我们就可以在当中找到下面这段配置:

1
2
3
4
5
# The RECURSIVE tag can be used to specify whether or not subdirectories should
# be searched for input files as well.
# The default value is: NO.

RECURSIVE = NO

把这个NO改成YES即可使doxygen递归整个文件树来查找代码。

这样我们就能进行最简单的项目文档的生成了。

样例

下面是对一个叫guisan的项目利用doxygen进行文档生成的结果:







事实上doxygen不仅能自动生成类的属性以及方法的说明,还能画出非常复杂的类之间的继承与聚合等关系图,在分析大型项目的时候还是非常靠谱的。