开发文档生成工具--Doxygen

Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。

1简介

Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞泰坦尼克号同样的辛苦。大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。

对于未归档的源文件，也可以通过配置Doxygen来提取代码结构。或者借助自动生成的包含依赖图（includedependency graphs）、继承图（inheritance diagram）以及协作图（collaborationdiagram）来可视化文档之间的关系。Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML和Unixman page等。

一个好的程序设计师，在写程序时，都会在适当的地方加上合适的批注。如果，能够在撰写批注时，稍微符合某种格式，接着就可以透过一个工具程序依据程序结构及您的批注产生出漂亮的文件。这将令许多工作繁重的程序设计师有时间多喝几杯咖啡。

Doxygen 就是这样的一个工具。在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文件了。因此，Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文件。

2程序语言

* C/C++

* Java

* Objective-C

* Python

* IDL (Corba, Microsoft及KDE-DCOP类型)

* Fortran

* VHDL

* PHP

* C#

3文件格式

* HTML

* XML

* LaTeX

* RTF (MS-Word)

* PostScript

* Unix Man Page

而其中还可衍生出不少其它格式。如有了LaTeX 文件后，就可以透过一些工具产生出PS或是PDF档案。

在多国语言的支持方面，Doxygen 目前可支持的约有2,30种。自Doxygen 1.2.16开始支持繁体中文(这正是小弟做的好事)。所以在目前一些Open Source 的程序文档管理器中，Doxygen 算是相当完整的一套。在程序语言处理上面，Doxygen也算是少数在Borland C++Builder 的语法下还能够正常运作的工具之一（若非如此，小弟也不会推荐它）。

本文的目的是希望在经过仔细阅读本文之后能够给大家一个概略性的了解。以便可以很容易的上手使用Doxygen。至于Doxygen本身的详细使用，各位可以参考随着Doxygen 所附的文件。实际上，Doxygen 自己的使用手册就是使用Doxygen 产生的。您可以看到他实际上能够产生远比Reference Book更复杂的文件。

4安装

Doxygen 的安装可说十分的简单，本文仅介绍binary档案的安装，若您有兴趣从source code重新compile起来，请自行查阅参考手册。

首先，请您先至doxygen 的网站上面抓取最新版本的doxygen 回来。目前，只要您是Linux, Solaris, Mac OS X, HP-UX, 甚至是UnixWare，都有compile好的binary版本可以抓取。如果是Windows 95/98/ME/NT/2000/XP，甚至还有Setup的版本可以抓取。所以安装过程可说十分简单。只要给予正确的安装目录，相信一般在安装上是不会遇到什么问题的。

另外，如果您是Linux或是Windows，可以另外抓取Doxygen Wizard的程序。这是一个辅助工具，可以很快的帮您建立一个Doxygen 的组态档案。透过这个组态档案，您就可以很快的将文件产生出来。另外，若没有使用Doxygen Wizard，还是可以使用一般的文字编辑器将这个组态档制作出来。

若安装成功，您应该可以看到doxygen 这个执行文件出现在您的系统中。若是Windows 平台，则可看到在程序集中有Doxygen 这个Folder出现。

5组态

Doxygen 产生文件可以分为三个步骤。一是为Project 建立组态档，二是在程序代码中加上符合Doxygen所定义批注格式。三是使用Doxygen来产生批注。

因此，第一步就是为您的Project 制作Doxygen 的组态档案。这个所谓的组态档案，格式其实与很简单。就是一些Key 与值的设定。每个设定为一行。若第一行开头为"#" 表示该行为批注。Doxygen 会忽略它。每个设定行的格式有两种，分别如下：

TAG = value [value, ...]

及

TAG += value [value, ...]

第一种形式是最常见的，也就是要设定一个TAG (也就是一个Key )，他的值为右边所定义的部分。原则上每个值都是单一的英文字，如果您要定义的值有空格符包含在内，可使用双引号将它括住。如果要定义的值超过一个以上，可使用逗号","予以分隔开来。

如果您要定义的TAG 是属于表列型态的，也就是他会有很多的值分别以逗号隔开。在Doxygen 组态档中允许您在不同的地方重复定义。只是后面的定义应使用上面所说的第二种形式。此种形式会将前后两个定义的值合并在一起。

知道这个基本格式后，剩下就是根据各个TAG 的意义来进行设定。关于TAG 的定义很多，此处我们仅针对必要用到的TAG 进行说明，剩下的部分请自行翻阅使用说明。

由于Doxygen 的TAG 还算不少，为了方便使用，Doxygen 自身提供了一个方便的选项，可以帮您建立一份空白的Doxygen档案(Doxygen 是Doxygen 预设的组态档名)。

> doxygen Doxygen

透过这个命令，您可以得到一个Doxygen 档案，接下来就可使用一般的文字编辑器来进行编辑。

下面将针对几个必要的TAG 进行说明：

PROJECT_NAME Project 的名字，以一个单字为主，多个单字请使用双引号括住。

PROJECT_VERSION

Project的版本号码。

OUTPUT_DIRECTORY

输出路径。产生的文件会放在这个路径之下。如果没有填这个路径，将会以目前所在路径来作为输出路径。

OUTPUT_LANGUAGE

输出语言。预设为English。1.2.16 版后，您可以使用Chinese-Traditional 来输出中文繁体的格式。

INPUT

指定加载或找寻要处理的程序代码档案路径。这边是一个表列式的型态。并且可指定档案及路径。举例来说若您有a.c, b.c, c.c 三个档案。您可使用INPUT = a.c, b.c, c.c 的方式。若您给定一个目录，该目录下面所有档案都会被处理。

FILE_PATTERNS

如果您的INPUT Tag 中指定了目录。您可以透过这个Tag来要求Doxygen在处理时，只针对特定的档案进行动作。例如：您希望对目录下的扩展名为.c, .cpp及.h的档案作处理。您可设定FILE_PATTERNS = *.c, *.cpp, *.h。

RECURSIVE

这是一个布尔值的Tag，只接受YES或NO。当设定为YES时，INPUT所指定目录的所有子目录都会被处理。

EXCLUDE

如果您有某几个特定档案或是目录，不希望经过Doxygen处理。您可在这个Tag中指定。

EXCLUDE_PATTERNS

类似于FILE_PATTERNS的用法，只是这个Tag是供EXCLUDE所使用。

SOURCE_BROWSER

如果设定为YES，则Doxygen会产生出源文件的列表，以供查阅。

INLINE_SOURCES

如果设定为YES ，则程序代码也会被嵌入于说明文件中。

ALPHABETICAL_INDEX

如果设定为YES，则一个依照字母排序的列表会加入在产生的文件中。

GENERATE_HTML

若设定为YES ，就会产生HTML版本的说明文件。HTML文件是Doxygen预设产生的格式之一。

HTML_OUTPUT

HTML文件的输出目录。这是一个相对路径，所以实际的路径为OUTPUT_DIRECTORY加上HTML_OUTPUT。这个设定预设为html。

HTML_FILE_EXTENSION

HTML文件的扩展名。预设为.html。

HTML_HEADER

要使用在每一页HTML文件中的Header。如果没有指定，Doxygen会使用自己预设的Header。

HTML_FOOTER

要使用在每一页HTML文件中的Footer。如果没有指定，Doxygen会使用自己预设的Footer。

HTML_STYLESHEET

您可给定一个CSS 的设定，让HTML的输出结果更完美。

GENERATE_HTMLHELP

如设定为YES，Doxygen会产生一个索引文件。这个索引文件在您需要制作windows 上的HTML格式的HELP档案时会用的上。

GENERATE_TREEVIEW

若设定为YES，Doxygen会帮您产生一个树状结构，在画面左侧。这个树状结构是以JavaScript所写成。所以需要新版的Browser才能正确显示。

TREEVIEW_WIDTH

用来设定树状结构在画面上的宽度。

GENERATE_LATEX

设定为YES 时，会产生LaTeX 的文件。不过您的系统必需要有安装LaTeX 的相关工具。

LATEX_OUTPUT

LaTeX文件的输出目录，与HTML_OUTPUT用法相同，一样是指在OUTPUT_DIRECTORY之下的路径。预设为latex。

LATEX_CMD_NAME

LaTeX程序的命令名称及档案所在。预设为latex。

GENERATE_RTF

若设定为YES ，则会产生RTF 格式的说明档。

RTF_OUTPUT

与HTML_OUTPUT 用法相同，用来指定RTF 输出档案路径。预设为rtf。

GENERATE_MAN

若设定为YES ，则会产生Unix Man Page 格式的说明文件。

MAN_OUTPUT

与HTML_OUTPUT 用法相同，用来指定Man Page的输出目录。预设为man。

GENERATE_XML

若设定为YES ，则会产生XML 格式的说明文件。

ENABLE_PREPROCESSING

若设定为YES ，则Doxygen 会启动C 的前置处理器来处理原始档。

PREDEFINED

可以让您自行定义一些宏。类似于gcc 中的-D选项。

若上面这些基本的Tag 都设定正确，接下来就是将您的Source Code

批注修改成为正确的格式。若您觉得用一般文字编辑器来编辑组态档

很麻烦，建议您可以使用Doxygen Wizard这个工具程序。他可以很快

的建构出您所需要的Doxygen档案。

6使用步骤

由于只是工具的使用，这里不介绍它的原理，直接从使用步骤开始。Doxygen的使用步骤非常简单。主要可以分为：

1）第一次使用需要安装doxygen的程序

2）生成doxygen配置文件

3）编码时，按照某种格式编写注释

4）生成对应文档

doxygen的安装非常简单， linux下可以直接下载安装包运行即可，下载源代码编译安装也是比较通用的编译安装命令。请参考其安装文档完成安装。

Doxygen在生成文档时可以定义项目属性以及文档生成过程中的很多选项，使用下面命令能够产生一个缺省的配置文件：

doxygen -g [配置文件名]

可以根据项目的具体需求修改配置文件中对应的项，具体的修改过程在下面介绍。修改过的配置文件可以作为以后项目的模板。

让doxygen自动产生文档，平常的注释风格可不行，需要遵循doxygen自己的格式。具体如何写doxygen认识的注释在第3节详细介绍。

OK，代码编完了，注释也按照格式写好了，最后的文档是如何的哪？非常简单，运行下面的命令，相应的文档就会产生在指定的目录中。

doxygen [配置文件名]

需要注意的是doxygen并不处理所有的注释，doxygen重点关注与程序结构有关的注释，比如：文件、类、结构、函数、变量、宏等注释，而忽略函数内变量、代码等的注释。

7配置文件

doxygen配置文件的格式是也是通常的unix下配置文件的格式：注释'#'开始；tag = value [,value2…]；对于多值的情况可以使用 tag += value [,value2…]。

对doxygen的配置文件的修改分为两类：一种就是输出选项，控制如何解释源代码、如何输出；一种就是项目相关的信息，比如项目名称、源代码目录、输出文档目录等。对于第一种设置好后，通常所有项目可以共用一份配置，而后一种是每个项目必须设置的。下面选择重要的，有可能需要修改的选项进行解释说明，其他选项在配置文件都有详细解释。

TAG 缺省值含义

PROJECT_NAME 项目名称

PROJECT_NUMBER 可以理解为版本信息

OUTPUT_DIRECTORY 输出文件到的目录，相对目录（doxygen运行目录）或者绝对目录

INPUT 代码文件或者代码所在目录，使用空格分割

FILE_PATTERNS *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.idl *.odl 指定INPUT的目录中特定文件，如：*.cpp *.c *.h

RECURSIVE NO 是否递归INPUT中目录的子目录

EXCLUDE 在INPUT目录中需要忽略的子目录

EXCLUDE_PATTERNS 明确指定的在INPUT目录中需要忽略的文件，如：FromOut*.cpp

OUTPUT_LANGUAGE English 生成文档的语言，当前支持2、30种语言，国内用户可以设置为Chinese

USE_WINDOWS_ENCODING YES（win版本）

NO（unix版本）编码格式，默认即可。

EXTRACT_ALL NO 为NO，只解释有doxygen格式注释的代码；为YES，解析所有代码，即使没有注释。类的私有成员和所有的静态项由EXTRACT_PRIVATE和 EXTRACT_STATIC控制

EXTRACT_PRIVATE NO 是否解析类的私有成员

EXTRACT_STATIC NO 是否解析静态项

EXTRACT_LOCAL_CLASSES YES 是否解析源文件（cpp文件）中定义的类

SOURCE_BROWSER NO 如果为YES，源代码文件会被包含在文档中

INLINE_SOURCES NO 如果为YES，函数和类的实现代码被包含在文档中

ALPHABETICAL_INDEX NO 生成一个字母序的列表，有很多类、结构等项时建议设为YES

GENERATE_HTML YES 是否生成HTML格式文档

GENERATE_HTMLHELP NO 是否生成压缩HTML格式文档（.chm）

GENERATE_LATEX YES 是否生成latex格式的文档

GENERATE_RTF NO 是否生成RTF格式的文档

GENERATE_MAN NO 是否生成man格式文档

GENERATE_XML NO 是否生成XML格式文档

8注释

3.1 注释风格

下面是工作量最大部分，安照doxygen格式写注释。通常代码可以附上一个注释块来对代码进行解释，一个注释块由一行或者多行组成。通常一个注释块包括一个简要说明（brief）和一个详细说明（detailed），这两部分都是可选的。可以有多种方式标识出doxygen可识别的注释块。

1）JavaDoc类型的多行注释。

2）QT样式的多行注释。

3） /// …text….

4） //! …text….

简要说明有多种方式标识，这里推荐使用@brief命令强制说明，例如：

以上这些注释格式用来对紧跟其后的代码进行注释。doxygen也允许把注释放到代码后面，具体格式是放一个'<'到注释开始部分。例如：

int var1 ;

int var2; ///< ….text….

注释和代码完全分离，放在其他地方也是允许的，但需要使用特殊的命令加上名称或者声明进行标识，比如：class、struct、union、 enum、fn、var、def、file、namespace、package、interface（这些也就是doxygen关注的注释类型）。这里不推荐使用，建议注释尽量放在代码前后。具体使用方式参见doxygen手册。

3.2 doxygen常用注释格式

通常的选择上面的一、两种注释风格，遇到头文件中各种类型定义，关键变量、宏的定义，在其前或者后使用 @brief 定义其简要说明，空一行后继续写其详细的注释即可。

对函数的注释，是比较常常需要注释的部分。除了定义其简要说明以及详细注释，还可以使用param命令对其各个参数进行注释，使用return命令对返回值进行注释。常见的格式如下：

int func1(int a, int b);

进行设计时，通常有模块的概念，一个模块可能有多个类或者函数组成，完成某个特定功能的代码的集合。如何对这个概念进行注释？doxygen提供了group的概念，生成的模块的注释会单独放在一个模块的页面中。使用下面的格式定义一个group。

code

group中的代码可以有自己的注释。单纯定义一个模块，去除{ 和}命令即可。任何其他代码项（比如类、函数、甚至文件）如果要加入到某个模块，可以在其doxygen注释中使用ingroup命令即可。Group之间使用ingroup命令，可以组成树状关系。

把多个代码项一起添加到某个模块中可以使用addtogroup命令，格式和defgroup相似。

对于某几个功能类似的代码项（比如类、函数、变量）等，如果希望一起添加注释，而又不想提升到模块的概念，可以通过下面的方式：

//@{

code…

//@}

对这种组进行命名可以使用name命令。此时中间代码可以有自己的注释。如：

//@{

code…

//@}

3.3 doxygen常用注释命令

doxygen通过注释命令识别注释中需要特殊处理的注释，比如函数的参数、返回值进行突出显示。上面也提到了一些注释命令（如：brief、param、return、以及group相关的命令），下面对其他一些常用的注释命令进行解释说明。

@exception <exception-object> {exception description} 对一个异常对象进行注释。

@warning {warning message } 一些需要注意的事情

@todo { things to be done } 对将要做的事情进行注释

@see {comment with reference to other items } 一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。

@relates <name> 通常用做把非成员函数的注释文档包含在类的说明文档中。

@since {text} 通常用来说明从什么版本、时间写此部分代码。

@deprecated

@pre { description of the precondition } 用来说明代码项的前提条件。

@post { description of the postcondition } 用来说明代码项之后的使用条件。

@code 在注释中开始说明一段代码，直到@endcode命令。

@endcode 注释中代码段的结束。

到此为止，常用的doxygen的注释格式讨论完毕，我们能够按照一定的格式撰写doxygen认识的注释，并能够使用doxygen方便快捷的生成对应的文档，不过注释中应该写些什么，如何撰写有效的注释可能是困扰开发人员的一个更深层次的问题。

4. 注释的书写

注释应该怎么写，写多还是写少。过多的注释甚至会干扰对代码的阅读。写注释的一个总的原则就是注释应该尽量用来表明作者的意图，至少也应该是对一部分代码的总结，而不应该是对代码的重复或者解释。对代码的重复或者解释的代码，看代码可能更容易理解。反映作者意图的注释解释代码的目的，从解决问题的层次上进行注释，而代码总结性注释则是从问题的解答的层次上进行注释。

避免对单独语句进行注释；

通过注释解释为什么这么做、或者要做什么，使代码的读者可以只阅读注释理解代码；

对读者可能会有疑问的地方进行注释；

对数据定义进行注释，而不是对其使用过程进行注释；

对于难于理解的代码，进行改写，而不要试图通过注释加以说明；

对关键的控制结构进行注释；

对数据和函数的边界、使用前提等进行注释；

9建立文件

当您前面所有的步骤都正确无误执行后，只需要执行下面的命令就可建立出您要的文件了：

> doxygen Doxygen

如果有错误产生，请检查您的Doxygen 组态档设定是否有误，目录的存取权限是否足够。如果输出的结果不正确，请检查您的批注是否符合格式。批注的位置是否正确。举例来说，您不可在说明class的批注与class 本身插入其它的程序代码或宣告。否则Doxygen 就无法将批注与该class对应起来。

如果您使用Doxygen Wizard，可直接使用上面的Run 的按钮或选单项目来制作说明文件。如果是产生HTML文件，在HTML_OUTPUT 所指定的目录中的index.html将是您说明文件的首页。

在中文繁体方面，目前我仅成功制作出HTML与RTF 格式的说明文件。其它格式的过程比较复杂，需要搭配其它工具，有待各位自行尝试。

10版本

2012年12月28日，Doxygen 1.8.3 发布，文档生成工具^[1]

^{来自：http://baike.baidu.com/link?url=DnXmXcDVp_FnUuxsxPk3DIj8iLcdma1rYQ3ntb6cwHaQVP8zx_YPz6CgMNurF3N3vi9muvUk2Qjh5PtoV7iHza}

^{下载地址：http://www.onlinedown.net/soft/117010.htm}