强大的代码编档工具—Doxygen
强大的代码编档工具—Doxygen
作者：涩涩 http://blog.csdn.net/sese
本原创文章不经作者许可，不得转载
Doxygen是什么
Doxygen的词根来源于Document（文档）和Oxygen（氧气），它是一个功能强大、使用方便且支持各种操作系统和编程语言的代码文档生成系统。Doxygen由荷兰人Dimitri van Heesch.开发，并且在GNU公共许可证（GPL）下发布，目前已经成为各主要的Linux发行版的附带组件。众多重量级的软件项目（如KDE，Qt、ACE库等）都选用Doxygen作为其编档工具生成项目文档。
Doxygen最初在Linux下开发，但已经被移植到多个操作系统平台下，包括Unix的各发行版本、MS Windows和Mac OS。Doxygen目前最新的版本是1.3.6，支持的编程语言包括 C++，C，Java，IDL（CORBA和MS风格），对Objective-C， PHP， C#和D语言也有部分支持。
Doxygen的功能
Doxygen的主要功能是分析和抽取按照特定标记格式书写的代码注释（支持的注释格式有Java Doc 1.1, Qt-Doc, and KDOC 格式），生成多种格式的项目文档，目前支持的文档格式如下：
l 以网站形式组织的HTML
l PostScript
l 带超链接的PDF
l XML
l Unix Man Page
l Compressed HTML（CHM）
l Rich Text Format（RTF）
l MS Word
工作流程
Doxygen由配置文件解析器、各种编程语言的文法分析和预处理器、以及各种目标格式文档的生成器组成，它的工作原理如下图所示：
上面的流程图阐释了Doxygen的基本工作原理。Doxygen从配置文件（也叫Doxyfile）中读取工作所需要的所有配置信息。Doxygen的配置文件是纯文本文件，可以用任何文本编辑软件编辑，下面是一个配置文件的部分选项例子（完整配置文件篇幅较长，故从略）：
# Doxyfile 1.3.3
PROJECT_NAME = ACE
OUTPUT_DIRECTORY = .
OUTPUT_LANGUAGE = English
INPUT = docs
ace
ace/os_include
ace/os_include/arpa
ace/os_include/net
ace/os_include/netinet
ace/os_include/sys
FILE_PATTERNS = *.h
*.cpp
*.inl
*.i
*.txt
SOURCE_BROWSER = YES
INLINE_SOURCES = YES
STRIP_CODE_COMMENTS = NO
GENERATE_HTML = YES
HTML_OUTPUT = html/ace
HTML_FILE_EXTENSION = .html
Doxygen的配置文件由若干个配置项组成，每行通常为一个配置项，按照：
ITEM_NAME = VALUE
格式书写，注释行以“#”开头，当配置项内容多于一行时以“\”换行。在配置文件中指定了作为输入的源代码目录文件，生成文档格式、语言，以及其它各种配置选项供用户定制。完整的Doxygen配置文件项目超过200项，用户可以藉此对生成的项目文档进行相当精确的控制。
为了方便用户编写配置文件，Doxygen还专门提供了图形化的配置工具Doxywizard，可以在图形用户界面的平台下使用（X-Window，MS Windows等），大大简化了配置文件的工作量，Doxywizard的界面如下所示：
在生成了配置文件之后（不论是使用Doxywizard还是手动编写），只需在命令行简单的执行如下命令即可开始生成项目文档：
$doxygen <config file name>
如果是使用Doxywizard图形化前端的用户，则只需要点一下工具条或者菜单中的Run选项即可生成文档。需要注意的是，Doxygen可以直接生成的文档格式只有HTML、Latex、Man Page和RTF四种，其它文件格式需要通过第三方工具进行进一步转换，但通常这一转换过程也非常容易，因为Doxygen会为这些第三方工具生成所需的配置或项目文件，下表给出了完整的Doxygen支持的其它几种文档格式以及转换工具：
间接文档格式
基于
第三方工具
项目文件
Postscript
LateX
Ghostscript
Makefile
LateX
Ghostscript
Makefile
CHM
HTML
MS HTML Workshop
hhp
MS Word
RTF
MS Word
值得一提的是，由于Doxygen支持XML格式输出，用户完全可以自己编写额外的处理程序，产生完全定制的项目文档。
为自动编档而注释
代码自动编档技术的目标是，程序员在写程序的同时写下的注释，能够有效地成为规范的文档，从而最大限度地减少文档编写工作量，提高软件生产率。自动编档的原理是，程序员在书写代码注释时，使用符合编程语言注释语法但又有所区别（从而能够为Doxygen识别）的注释标记来注释代码，Doxygen工具在处理代码时执行类似编译的文法分析过程，将那些符合规则的注释和文法分析得到的代码结构（类、方法、变量等文法信息）结合起来，从而形成输出文档。
Doxygen支持多种主流平台或库的注释格式，并有自己的扩展，其实几种注释格式大同小异，如下：
Java-Doc格式：
/**
... text ...
*/
QT-Doc格式：
/*!
... text ...
*/
Doxygen扩展：
(单行)
/// text
(行末)
some-statements; /*<! text */
some-statements; //<! text
另外,在Doxygen注释块中可以使用Doxygen预定义的指令（command）来生成一些特定的文档标记，例如，如下的注释块：
/*!
@param *a 指向加数1的指针
@param *b 指向加数2的指针
@param *c 运算的积
@return 错误代码
@sa COMPMinus
*/
int COMPMultiply(const Complex *a, const Complex *b, Complex *c)
使用@param，@return和@sa分别标记参数、返回和参见的文档块，实际生成的文档如下：
int COMPMultiply (const Complex * a, const Complex * b, Complex * c)
参数:
*a 指向乘数1的指针
*b 指向乘数2的指针
*c 运算的积
返回:
错误代码
参见:
COMPMinus
Doxygen一共定义了100多种不同的命令来控制文档的生成格式，Doxygen还支持直接插入注释中的HTML代码到生成文档中，支持定制文档的页眉、页脚等特征。有兴趣的读者可以参考Doxygen的相关文档了解完整的使用说明。
高级图形特性
Doxygen可以通过Graphviz开源工具的支持来画出各种图形插入文档中，包括文件include关系、对象继承关系等，下面是几个例子（均来自著名的开源C++库ACE）：
文件include关系：
类继承关系：
更为强大的是，Doxygen生成的这些图形支持交互导航功能（在HTML格式下有效），文档用户只需点击即可切换到相应的页面，十分方便，而所有的这些只需要设置下面这几个简单的配置选项即可：
DOT_PATH = #Graphviz路径
DOT_IMAGE_FORMAT = #图片格式，默认是PNG
CLASS_DIAGRAMS = #是否画类图
COLLABORATION_GRAPH = #是否画协作图
UML_LOOK = #使用UML风格
INCLUDE_GRAPH = #include关系
CALL_GRAPH = # 调用图
GRAPHICAL_HIERARCHY = #继承关系图
国际化问题
Doxygen的作者在设计时已经考虑了多语言支持的需要，提供了内建的支持，目前，Doxygen可以在近30种语言下正确地工作，仅需要在配置文件中指出所需的语言类型，例如，如果希望Doxygen生成中文版的文档，只要将配置文件中的OUTPUT_LANGUAGE标签设置为Chinese即可。
但是，值得说明的是，Doxygen生成的LateX文件如果包含了中文，那么编译时候需要有中文宏包的支持，才可以正常的生成中文的ps和pdf文件，更多细节请参阅LateX中文化方面的资料。
了解更多
Doxygen的官方主页是：http://www.stack.nl/~dimitri/doxygen/，从这里可以下载到最新的Doxygen发行版、源代码以及使用文档。
Doxygen使用的画出各种图形的第三方工具是AT&T实验室的Graphviz。这是一个著名的开放源码图形绘制软件，广泛地应用于各种软件相关图形绘制，它的官方主页是：
