编程语言

img SeSe

强大的代码编档工具—Doxygen

发表于2004/10/11 15:14:00  6871人阅读

强大的代码编档工具—Doxygen
作者:涩涩 http://blog.csdn.net/sese
本原创文章不经作者许可,不得转载

 

Doxygen是什么

Doxygen的词根来源于Document(文档)和Oxygen(氧气),它是一个功能强大、使用方便且支持各种操作系统和编程语言的代码文档生成系统。Doxygen由荷兰人Dimitri van Heesch.开发,并且在GNU公共许可证(GPL)下发布,目前已经成为各主要的Linux发行版的附带组件。众多重量级的软件项目(如KDEQtACE库等)都选用Doxygen作为其编档工具生成项目文档。

 

Doxygen最初在Linux下开发,但已经被移植到多个操作系统平台下,包括Unix的各发行版本、MS WindowsMac OSDoxygen目前最新的版本是1.3.6,支持的编程语言包括 C++CJavaIDLCORBAMS风格),对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 HTMLCHM

l         Rich Text FormatRTF

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-WindowMS Windows等),大大简化了配置文件的工作量,Doxywizard的界面如下所示:

  

在生成了配置文件之后(不论是使用Doxywizard还是手动编写),只需在命令行简单的执行如下命令即可开始生成项目文档:

 

 

$doxygen <config file name>

 

 

如果是使用Doxywizard图形化前端的用户,则只需要点一下工具条或者菜单中的Run选项即可生成文档。需要注意的是,Doxygen可以直接生成的文档格式只有HTMLLatexMan PageRTF四种,其它文件格式需要通过第三方工具进行进一步转换,但通常这一转换过程也非常容易,因为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;  /*<! 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文件如果包含了中文,那么编译时候需要有中文宏包的支持,才可以正常的生成中文的pspdf文件,更多细节请参阅LateX中文化方面的资料。

了解更多

 

Doxygen的官方主页是:http://www.stack.nl/~dimitri/doxygen/,从这里可以下载到最新的Doxygen发行版、源代码以及使用文档。

 

Doxygen使用的画出各种图形的第三方工具是AT&T实验室的Graphviz。这是一个著名的开放源码图形绘制软件,广泛地应用于各种软件相关图形绘制,它的官方主页是:

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

 

阅读全文
0 0

相关文章推荐

img
取 消
img