Chinaunix首页 | 论坛 | 博客
  • 博客访问: 1524123
  • 博文数量: 226
  • 博客积分: 3997
  • 博客等级: 少校
  • 技术积分: 2369
  • 用 户 组: 普通用户
  • 注册时间: 2010-06-19 17:26
个人简介

Never save something for a special occasion. Every day in your life is a special occasion.

文章分类

全部博文(226)

文章存档

2018年(5)

2017年(11)

2016年(1)

2015年(17)

2014年(14)

2013年(30)

2012年(5)

2011年(52)

2010年(107)

分类:

2013-07-25 15:15:09

作者:

作者简介


车皓阳,您可以通过和作者取得联系。

正文


如果您这次还没来得及使用老式的Help Workshop为您的Web应用构建文档系统的话,那么,何不尝试一下Doxygen,需知"The proof of the pudding lies in the eating"。

Doxygen是什么?


Doxygen 是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,完全支持C、C++、Java、Objective-C和IDL语言,部分支持PHP、 C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始,生成HTML格式的在线类浏览器,或离线的 LATEX、RTF参考手册。对于未归档的源文件,也可以通过配置Doxygen来提取代码结构。或者借助自动生成的包含依赖图(include dependency graphs)、继承图(inheritance diagram)以及协作图(collaboration diagram)来可视化文档之间的关系。Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML和Unix man page等。

Doxygen在Linux上开发,但也可以在其它的Unix平台下运行。而且,Windows 9x/NT平台下也有对应的可执行版本。

安装Doxygen


首 先,去Doxygen网站上找到最新版本的Doxygen。有二进制或源码两种版本,如果不想重头编译,下载二进制版本安装即可。在Linux下,源码编 译需要perl和Gnu工具flex、bison、make的支持。在Windows下,二进制版本勿需安装,而源码编译所需支持工具较多。我们仅讲述 Linux下的Doxygen的源码编译以及二进制版本安装过程。

编译源码

gunzip doxygen-$VERSION.src.tar.gz
tar xf doxygen-$VERSION.src.tar
sh ./configure,或者configure --platform platform-type
(略去直接使用configure需要平台检测的过程,平台类型在PLATFORMS文件中列出),
configure --with-doxywizard(GUI前端选项)
make,或者make docs(创建HTML格式的手册),make pdf(创建PDF格式的手册)

安装二进制版本

./configure
make install

二进制文件安装目录是/bin,其中 缺省为/usr,可以通过configure的参数--prefix修改其值。使用make install_docs可以把文档和例子安装在目录/doxygen,其中缺省为< prefix>/share/doc/packages,可以通过configure的参数--docdir修改其值。doxygen是bin目录 下的一个命令行程序,它是Doxygen的核心工具,完成文档的转换和生成工作。

Doxygen的处理流程


图1是Doxygen网站上给出的Doxygen处理工具以及它们之间的信息流。

从 图中可以看出,Doxygen可执行程序位于正中,所有的流程都围绕着它进行。左侧图标表示Doxygen的输入可以是源文件,或者是定制的头文件、图 像、注解等。Doxygen图标上部是配置文件,由Doxywizard处理,下部是Tag文件,由Doxytag处理。后面是Doxygen输出文件的 类型,依次是XML、Latex、Man pages、RTF和HTML,可处理类型图标之后是进行进一步转换所需的工具。

图1  Doxygen网站上给出的Doxygen信息流图

配置文件


每 一个Doxygen工程都有一个后缀为.cfg的配置文件,用来保存所有的设置。配置文件的格式与autoexec.bat、config.sys等文件 相似,是由名称/值对组成的ASCII码,会由doxygen命令来解析。为了简化创建和修改配置文件,Doxygen可以在命令行方式下加上参数-g自 动创建模板文件。

doxygen -g

忽略将会生成一个名为Doxyfile的缺省文件,如果已经存在,会被Doxygen改名为.bak。

实 际上,我们根本就不需要用一般的编辑器来编辑配置文件,Doxygen提供了一个辅助工具Doxywizard。Doxywizard是Doxygen的 GUI前台,用户可以能过它来读写配置文件,省却了手工配置的麻烦。基本上,在Doxywizard中可以完成Doxygen的绝大多数工作,而且 Doxygen也可以在由Doxywizard启动,这样就使得整个过程比较连贯。

虽然如此,我们还是要理解常见的各个Tag的含义。在 Doxywizard中,可以看到这些Tag以自明的方式命名,我们大致可以从名称中看出其作用。这些Tag被Doxywizard大致分为几类,其中 HTML到PerlMod是输出文件种类设置,Project是Doxygen工程设置,Build是编译类选项,Messages为出错或异常选项, Input为输入源选项,等等。

图2  Doxywizard

注释


Doxygen规定了进行注释的一些格式,正确的注释才能使Doxygen生成文档。第一个代码条目,都有两种描述:简要描述和详细描述,两者都是可选的。简要描述只有一行,而详细描述则提供更长、更仔细的描述,Doxygen只允许有一个简要描述和详细描述。

在Doxygen中,一般只会处理与程序结构相关的注释,函数内部的注释通常不做处理。对于详细描述来说,有下面几种表示方式。

JavaDoc风格,中间的"*"号可选。
/**
* 注释
*/

Qt风格,中间的"*"号可选。
/*!
* 注释
*/

C++风格的变体,或者最后一个"/"改为"!"也可以。
/// 单行注释
/// 注释
///

更加显著的表示。
///////////////////////////////////////////
/// 注释
///////////////////////////////////////////

简要描述亦有多种表示方式。

在上述注释块中使用\brief命令,详细注释在空行之后开始。
/*! \brief 简要描述
* 继续
*
* 详细注释
*/

JAVADOC_AUTOBRIEF设置为YES后,在JavaDoc风格的注释中,第一个点号之前的内容被自动设置为简要描述。
对于多行C++变体,这个选项亦会起到相同的作用。
/** 简要描述.详细描述
* 注释
*/


C++变体风格。
/// 简要描述
/* 详细描述 */

命令


Doxygen支持的指令非常多,主要作用是控制输出文档的排版格式。命令以"\"或"@"号开始。

一些命令可以有多个参数,一些命令只有一个参数。参数周围的括号使用是有含义的:

  • <>号表示参数是单个词。
  • ()号表示参数一直会到行尾。
  • {}号表示参数会扩展到下一段落。
  • []号表示参数是可选的。

下面章节中也涉及到一些命令的使用,其它的命令可以查阅Doxygen用户手册。

列表


Doxygen有许多方法可以创建项目列表。

使用"-"在每行开始之前打头,使用"."可以结束一个列表,开始新的段落。使用这种方法要严格对齐。
/**
* - 表项一
* - 子项一
* - 子项二
* .
* .
*/

在文档块中使用HTML命令。这种方法不需要严格对齐。
/*!
*

    *
  • 表项一
    *

      *
    1. 子项一
      *
    2. 子项二
      *

    *
  • 表项二
    *

*/

分组


Doxygen有两种分组机制。第一种 是全局地为每一个组创建一个网页,此时分组被称为"module";第二种是用于复合实体中的成员列表,此时分组被称为"member group"。Module是一种把内容在单个网页上分组的方法。分组可以包括files,namespace,classes,functions, variables,enums,typedefs和defines,也可以包含其它分组。复合实体(compound entities)如类、文件、命名空间等可以分布在多个分组中,而成员实体(member)如变量、函数、typedef等只能归属于一个分组。

定义分组的方法是在特殊注释块中使用命令\defgroup和\addtogroup。 defgroup的格式如下:

\defgroup <唯一标识名> (中间可以有空格的标题)

两次使用同一标识名,在doxygen解析的时候会出现错误。命令addtogroup与defgroup不同的地方在于,如果使用了同一标识,则会在改组中加入新的项,如果标识不重复,则会创建分组。addtogroup中的标题是可选的。

声明分组之后,如果要使某个实体归属某一分组,需要使用ingroup命令。避免在每个成员之前都使用ingroup命令,可以将member用@封装起来。

/**
* \ingroup A
*/
extern int VarInA;

/**
* \defgroup IntVariables Global integer variables
*/
/*@{*/

/** an integer variable */
extern int IntegerVariable;

/*@}*/

....

/**
* \defgroup Variables Global variables
*/
/*@{*/

/** a variable in group A */
int VarInA;

int IntegerVariable;

/*@}*/


上面这些命令都是有优先级的,doxygen会根据优先级将实体放入具 有最高优先级的分组之中。它们的优先级顺序是:ingroup,defgroup,addtogroup,weakgroup。weakgroup类似一 个低优先级的addtogroup。在.h文件中可以使用高优先级的命令定义层次结构,在.c文件中\weakgroup就不需要准确遵循.h文件中定义 的层次结构。

如果要把不同的类型归入同一分组内,就要使用Member group,它的定义方法如下:

//@{ 
...
//@}
或者
/*@{*/
...
/*@}*/


Member group不可以嵌套。

图表


Doxygen里有内置生成C++类层次图的功能。它使用贝尔实验室开发的graphviz 1.5中的工具"dot"来生成更高级的图表。使用这个工具时,要将配置选项HAVE_DOT设为YES。

  • 当GRAPHICAL_HIERARCHY设置为YES时,将会绘制一个图形表示的类图结构。
  • 当CLASS_GRAPH设置为YES时,会为每个归档的类创建一张图表示其直接或间接的继承关系。
  • 当INCLUDE_GRAPH设置为YES时,会为每个归档文件创建一幅包含依赖图,此功能目前仅有HTML和RTF格式支持。
  • 当COLLABORATION_GRAPH设置为YES时,会为每个归档类或结构绘制基类继承关系图和使用关系图。
  • 当CALL_GRAPH设置为YES时,会为每个函数显示一幅直接或间接调用关系图。

更具体的信息可以参考Doxygen的手册。

公式


Doxygen可以把LaTeX格式的公式输出出来。要在HTML文档里包含公式,需要安装下面的工具:latex(LaTeX编译器)、dvips(将DVI文件转换为PS文件)、gs(将PS文件转换为位图)。

包含公式的方法有两种:

使用\f$命令对表示文本中间的公式,遵循LaTeX格式。
\f$(x_1, y_1)\f$ (x1,y1)


位于独立一行上未编号的公式,应放在命令\f[和\f]之间。
\f[
|I_2|=\left| \psi(t)
\right|
\f]
对应的输出是|I2|=|ψ(t)|。

中文文档


Doxygen支持多种语言,输出中文文档的时候,只需要将配置文件中的OUTPUT_LANGUAGE标签设置为Chinese即可(用Doxywizard修改更方便)。

有一个需要注意的问题是,在Windows下的浏览器浏览中文HTML文档时,英文字母会变得很难看,解决的办法是将doxygen_cn.css下载到本地硬盘,并将配置文件中的HTML_STYLESHEET修改为这个文件的位置。

HTML_STYLESHEET=c:\doxygen\doxygen.css

运行doxygen


在命令行下运行doxygen是很简单的,只需要指定配置文件即可。

doxygen project.cfg

或者,也可以使用Doxywizard在配置完后直接运行doxygen。

图3  doxygen的输出示例

阅读(1138) | 评论(0) | 转发(0) |
给主人留下些什么吧!~~