分享
 
 
 

强大的代码编档工具—Doxygen

王朝other·作者佚名  2006-01-09
窄屏简体版  字體: |||超大  

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

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文件如果包含了中文,那么编译时候需要有中文宏包的支持,才可以正常的生成中文的ps和pdf文件,更多细节请参阅LateX中文化方面的资料。

了解更多

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

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

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

 
 
 
免责声明:本文为网络用户发布,其观点仅代表作者个人观点,与本站无关,本站仅提供信息存储服务。文中陈述内容未经本站证实,其真实性、完整性、及时性本站不作任何保证或承诺,请读者仅作参考,并请自行核实相关内容。
2023年上半年GDP全球前十五强
 百态   2023-10-24
美众议院议长启动对拜登的弹劾调查
 百态   2023-09-13
上海、济南、武汉等多地出现不明坠落物
 探索   2023-09-06
印度或要将国名改为“巴拉特”
 百态   2023-09-06
男子为女友送行,买票不登机被捕
 百态   2023-08-20
手机地震预警功能怎么开?
 干货   2023-08-06
女子4年卖2套房花700多万做美容:不但没变美脸,面部还出现变形
 百态   2023-08-04
住户一楼被水淹 还冲来8头猪
 百态   2023-07-31
女子体内爬出大量瓜子状活虫
 百态   2023-07-25
地球连续35年收到神秘规律性信号,网友:不要回答!
 探索   2023-07-21
全球镓价格本周大涨27%
 探索   2023-07-09
钱都流向了那些不缺钱的人,苦都留给了能吃苦的人
 探索   2023-07-02
倩女手游刀客魅者强控制(强混乱强眩晕强睡眠)和对应控制抗性的关系
 百态   2020-08-20
美国5月9日最新疫情:美国确诊人数突破131万
 百态   2020-05-09
荷兰政府宣布将集体辞职
 干货   2020-04-30
倩女幽魂手游师徒任务情义春秋猜成语答案逍遥观:鹏程万里
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案神机营:射石饮羽
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案昆仑山:拔刀相助
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案天工阁:鬼斧神工
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案丝路古道:单枪匹马
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:与虎谋皮
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:李代桃僵
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:指鹿为马
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案金陵:小鸟依人
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案金陵:千金买邻
 干货   2019-11-12
 
推荐阅读
 
 
 
>>返回首頁<<
 
靜靜地坐在廢墟上,四周的荒凉一望無際,忽然覺得,淒涼也很美
© 2005- 王朝網路 版權所有