使用Doxygen构建文档系统

下一页 1 2 

    如果您这次还没来得及使用老式的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
      

    二进制文件安装目录是<prefix>/bin，其中<prefix>缺省为/usr，可以通过configure的参数--prefix修改其值。使用make install_docs可以把文档和例子安装在目录<docdir>/doxygen，其中<docdir>缺省为<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 <config-file>

     忽略<config-file>将会生成一个名为Doxyfile的缺省文件，如果<config-file>已经存在，会被Doxygen改名为<config-file>.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++变体风格。
/// 简要描述
/* 详细描述 */
      

原文转自：http://www.ltesting.net