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