强大的代码编档工具—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

 

 

如果是使用Doxywizard图形化前端的用户，则只需要点一下工具条或者菜单中的Run选项即可生成文档。需要注意的是，Doxygen可以直接生成的文档格式只有HTML、Latex、Man Page和RTF四种，其它文件格式需要通过第三方工具进行进一步转换，但通常这一转换过程也非常容易，因为Doxygen会为这些第三方工具生成所需的配置或项目文件，下表给出了完整的Doxygen支持的其它几种文档格式以及转换工具：

 

间接文档格式	基于	第三方工具	项目文件
Postscript	LateX	Ghostscript	Makefile
Pdf	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;  /*    */

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。这是一个著名的开放源码图形绘制软件，广泛地应用于各种软件相关图形绘制，它的官方主页是：

http://www.research.att.com/sw/tools/graphviz/

 

本文转自

http://www.zaoxue.com/article/tech-44836.htm