Doxygen详细介绍

1 序言  

   为代码写注释一直是大多数程序员有些困扰的事情。当前程序员都能接受为了程序的可维护性、可读性编码的同时写注释的说法，但对哪些地方应该写注释，注释如何写，写多少等这些问题，不少程序员仍然没有答案。更头痛的是写文档，以及维护文档的问题，开发人员一般能够忍受编写或者改动代码时编写或者修改对应的注释，但以后须要修正相应的文档却比较困难。若是能从注释直接转化成文档，对开发人员无疑是一种福音。而doxygen就能把遵照某种格式的注释自动转化为对应的文档。

    Doxygen是基于GPL的开源项目，是一个很是优秀的文档系统，当前支持在大多数unix（包括Linux），windows家族，Mac系统上运行，彻底支持C++, C, Java, IDL（Corba和Microsoft 家族）语言，部分支持PHP和C#语言，输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。有不少开源项目（如log4cpp和CppUnit）都使用了doxygen文档系统。

    Doxygen 就是这样的一个工具。在您写批注时，稍微按照一些它所制订的规则。接着，他就能够帮您产生出漂亮的文档了。所以，Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二即是利用Doxygen的工具来产生文件。

2  Doxygen及相关工具的下载

（1）Doxygen的最新版本，能够从Doxygen的网站下载。 

（2）Graphviz是一个图形可视化软件。Doxygen使用Graphviz生成各类图形，例如类的继承关系图、合做图，头文件包含关系图等。能够从Graphviz的网站下载Graphviz的最新版本。

 

4     Doxygen配置文件

4.1   生成Doxygen配置文件

 

运行Doxywizard建立配置文件。
能够直接点“Save...”按钮，将保存默认的配置文件，名为Doxyfile，内容是Doxygen的默认设置。Doxyfile是普通文本文件，咱们能够直接打开手动编辑。不过在Doxywizard的界面上填写也很方便，每一个参数都有详细提示。建议用Doxywizard完成第一次设置。之后若是须要调整个别参数，能够直接编辑Doxyfile。

上述Doxywizard界面中提供了生成Doxygen文档的4个步骤，按照上述步骤一步步执行就能够生成漂亮的文档了。

第一步是生成配置文件，提供三种方式，Wizard方式指简约方式，在其中只提供一些重要的参数设置，其他的均为默认值；Expert方式为详细设置方式，经过该选项能够详细地配置Doxygen的各个配置项；最后一种是Load方式，用于导入之前生成的Doxygen配置文件，导入后能够再点击Expert进行修改。

4.2    配置选项含义详解

在上述界面中点击Expert按钮，或者用文本方式打开Doxyfile文件，能够看到Doxygen的参数配置项特别多，各个参数的含义其实也并不难掌握，在Doxygen的帮助手册中有详细的介绍，下面我介绍一些经常使用的参数含义，其他的参数大多能够设置为默认值。

DOXYFILE_ENCODING	Doxygen文件的编码方式，默认为UTF-8，若但愿支持中文，最好设置为 GB2312
PROJECT_NAME	Project 的名字，以一个单词为主，多个单词请使用双引号括住。
PROJECT_VERSION	Project的版本号码。
OUTPUT_DIRECTORY	输出路径。产生的文件会放在这个路径之下。若是没有填这个路径，将会以目前所在路径做为输出路径。
OUTPUT_LANGUAGE	输出语言, 默认为English 。
EXTRACT_ALL	为NO，只解释有doxygen格式注释的代码；为YES，解析全部代码，即便没有注释
EXTRACT_PRIVATE	是否解析类的私有成员
EXTRACT_STATIC	是否解析静态项
EXTRACT_LOCAL_CLASSES	是否解析源文件（cpp文件）中定义的类
INPUT	指定加载或找寻要处理的程序代码文件路径。这边是一个表列式的型态。而且可指定档案及路径。
FILE_PATTERNS	若是您的INPUT Tag 中指定了目录。您能够透过这个Tag来要求Doxygen在处理时，只针对特定的档案进行动做。例如：您但愿对目录下的扩展名为.c, .cpp及.h的档案做处理。您可设定FILE_PATTERNS = *.c, *.cpp, *.h。
RECURSIVE	这是一个布尔值的Tag，只接受YES或NO。当设定为YES时，INPUT所指定目录的全部子目录都会被处理.
EXCLUDE	若是您有某几个特定档案或是目录，不但愿通过Doxygen处理。您可在这个Tag中指定。
EXCLUDE_PATTERNS	相似于FILE_PATTERNS的用法，只是这个Tag是供EXCLUDE所使用。
SOURCE_BROWSER	若是设定为YES，则Doxygen会产生出源文件的列表，以供查阅。
INLINE_SOURCES	若是设定为YES ，则函数和类的实现代码被包含在文档中
ALPHABETICAL_INDEX	若是设定为YES，则一个依照字母排序的列表会加入在产生的文件中。（有不少类、结构等项时建议设为YES）
GENERATE_HTML	若设定为YES ，就会产生HTML版本的说明文件。HTML文件是Doxygen预设产生的格式之一。
HTML_OUTPUT	HTML文件的输出目录。这是一个相对路径，因此实际的路径为OUTPUT_DIRECTORY加上HTML_OUTPUT。这个设定预设为html。
GENERATE_HTMLHELP	是否生成压缩HTML格式文档（.chm）
HTML_FILE_EXTENSION	HTML文件的扩展名。预设为.html。
HTML_HEADER	要使用在每一页HTML文件中的Header。若是没有指定，Doxygen会使用本身预设的Header。
HTML_FOOTER	要使用在每一页HTML文件中的Footer。若是没有指定，Doxygen会使用本身预设的Footer。
HTML_STYLESHEET	您可给定一个CSS 的设定，让HTML的输出结果更完美。
GENERATE_HTMLHELP	如设定为YES，Doxygen会产生一个索引文件。这个索引文件在您须要制做windows 上的HTML格式的HELP档案时会用的上。
GENERATE_TREEVIEW	若设定为YES，Doxygen会帮您产生一个树状结构，在画面左侧。这个树状结构是以JavaScript所写成。因此须要新版的Browser才能正确显示。
TREEVIEW_WIDTH	用来设定树状结构在画面上的宽度。
GENERATE_LATEX	设定为YES 时，会产生LaTeX 的文件。不过您的系统必须要有安装LaTeX 的相关工具。
LATEX_OUTPUT	LaTeX文件的输出目录，与HTML_OUTPUT用法相同，同样是指在OUTPUT_DIRECTORY之下的路径。预设为latex。
LATEX_CMD_NAME	LaTeX程序的命令名称及档案所在。预设为latex。
GENERATE_RTF	若设定为YES ，则会产生RTF 格式的说明档。
RTF_OUTPUT	与HTML_OUTPUT 用法相同，用来指定RTF 输出档案路径。预设为rtf。
GENERATE_MAN	若设定为YES ，则会产生Unix Man Page 格式的说明文件。
MAN_OUTPUT	与HTML_OUTPUT 用法相同，用来指定Man Page的输出目录。预设为man。
GENERATE_XML	若设定为YES ，则会产生XML 格式的说明文件。
ENABLE_PREPROCESSING	若设定为YES ，则Doxygen 会激活C 的前置处理器来处理原始档。
PREDEFINED	可让您自行定义一些宏。相似于gcc 中的-D选项。
CLASS_DIAGRAMS	这个标记用来生成类继承层次结构图。要想生成更好的视图，能够从 Graphviz 下载站点 下载 dot 工具。Doxyfile 中的如下标记用来生成图表：
HAVE_DOT	若是这个标记设置为 Yes，doxygen 就使用 dot 工具生成更强大的图形，好比帮助理解类成员及其数据结构的协做图。注意，若是这个标记设置为 Yes，<CLASS_DIAGRAMS> 标记就无效了
CLASS_GRAPH	若是 <HAVE_DOT> 标记和这个标记同时设置为 Yes，就使用 dot 生成继承层次结构图
GRAPHICAL_HIERARCHY	设置为YES时，将会绘制一个图形表示的类图结构

 

 

上面的表格只是描述了一些经常使用的配置，须要更加详细的信息请参考Doxygen的帮助手册。

结束语

 

免费学习更多精品课程，登陆乐搏学院官网http://h.learnbo.cn/

或关注咱们的官方微博微信，还有更多惊喜哦~

 

 

 

本文出自 “Jhuster的专栏” 博客