使用Doxygen构建文档系统

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.gztar xf doxygen-$VERSION.src.tarsh 
./configure，
或者configure --platform platform-type
（略去直接使用configure需要平台检测的过程，平台类型在PLATFORMS文件中列出），
configure --with-doxywizard（GUI前端选项）
make，或者make docs（创建HTML格式的手册），make pdf（创建PDF格式的手册）

安装二进制版本

./configuremake 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中，一般只会处理与结构相关的注释，函数内部