使用doxygen
（已发表在《程序员》2002年第3期上）
一、介绍
GLAST软件已采用doxygen（GNU GPL软件）来作为文档工具，本文将对其进行简单的介绍。要了解更详细的信息及下载doxygen程序，请访问网站http://www.stack.nl/~dimitri/doxygen/。
什么是doxygen呢？下面的介绍录自doxygen的网页：
“doxygen是一种用于C++、IDL（Corba、Microsoft和KDE-2 DCOP风格）和C的文档系统。它可以通过三种方式来帮助你：
1. 它可以从一组标有文档的源文件中生成在线文档浏览器（HTML格式），以及/或者离线参考手册（LATEX格式）。同时还支持生成RTF（MS-Word）、Postscript、超链接PDF、压缩HTML和UNIX man页面格式的输出。文档是从源文件中直接提取的，从而十分容易保持文档和源码的一致。
2. 可配置doxygen，用以从没有标注文档的源文件中提取代码结构。这对于要在大量源文件中快速地找到所需的东西来说是非常有用的。通过include依赖图、继承图和协作图等手段（它们都是自动生成的），可以使不同成分之间的关系可视化。
3. 你甚至还可以“滥用”doxygen，创建普通文档。”
二、doxygen注释风格
使用doxygen的第一步是在你的代码中插入doxygen风格的注释。你可以使用两种不同风格的doxygen注释：
Qt风格，专用文档块看起来是这样的：
/*!
... text ...
*/
还有单行版本：
file://! ... one line of text ...
JavaDoc风格，专用文档块看起来是这样的：
/**
* ... text ...
*/
还有单行版本：
/// ... one line of text ...
从现在起我将在例子中使用Qt风格，但是你可以在你的代码中使用任何一种。
你可以通过许多方式使用doxygen注释，以为你的代码编写文档。但下面的一种，我们感觉能够令人满意地工作。注意下面的注解仅仅说明应该如何使用doxygen注释；你所应该包含在注释里的信息是另外一回事，并不在这里进行讨论。
我们的基本想法是你想要为每个类、以及该类的重要成员函数增加短注释和长注释。短注释应给出类或函数的基本信息的简要描述。而较长的注释，不奇怪，应该给出更长和更完整的描述。类的短注释和长注释，以及成员函数的简短描述，将放在头文件中。成员函数的长注释将出现在成员函数的实现出现的地方。
下面的例子演示这一注释系统（向Alexandre、Regis和Jose道歉，我在此过程中“黑”了他们的代码）。假定我们正在为一种叫作CalPack 的CMT包工作，它有一个单独的类CsICluster，头文件叫作CsICluster.h，在CalPack/目录中；而实现文件叫作CsICluster.cpp，在src/目录中。文件CalPack/CsICluster.h是这样的：
而文件src/CsICluster.cpp是这样的：
注意，你可能会选择省略那些含义清楚的成员函数的较长注释，这并不会导致任何问题。访问http://www.slac.stanford.edu/exp/glast/ground/software/doxygen_examples/v1/class_CsICluster.html可以看到上面被注释的代码所产生的HTML文档。
三、使用mainpage.h文件
浏览上面的链接中的文档，你可能会注意到名为“Main Page”的链接（它指向index.html）并不是十分有趣。这是一个特殊的页面，在这里你可以添加与你的doxygen页面描述的所有类有关的文档。在我们的例子中只有一个单独的类，但是你可以使用doxygen来处理如你所选择的那么多的类。一种自然的划分是为每一个GLAST CMT包都创建doxygen页面。于是合乎想像地，我们想要这个主页面成为对正在被讨论的包的描述；在我们的个案中就是CalPack包。
那么我们怎么为此主页面增添内容呢？你需要使用doxygen的特殊命令\mainpage。在doxygen中有一些特殊命令，它们放在doxygen注释中以增强你所生成的文档。例如在类描述中，我们已经使用了doxygen特殊命令\author。
命令\mainpage指定用以填充主页面的注释的内容。doxygen允许你将此命令放在任何注释中。但是，GLAST的惯例是将该命令放入文件mainpage.h中。这个mainpage.h文件应该只包含一条使用\mainpage命令的注释。并且这个文件应该放在头文件目录中，也就是，与包自己的名字相同的目录。
于是我们为CalPack包创建一个CalPack/mainpage.h文件：
注意在\mainpage命令后面的字句是主页面的标题。我们还引入了\section命令，其语法你应该可以推论得出。上面的注释所产生的HTML输出见http://www.slac.stanford.edu/exp/glast/ground/software/doxygen_examples/v2/。你还可以在此访问CsICluster类的文档。
四、包含图像
另一个有趣的命令（对此我们希望实施某种标准）是\image命令。此命令用于在你的文档中插入图像。\image命令可以用在任何注释中。此命令的语法如下所示：
\image html mypicture.gif
尽管我们仅仅显示了HTML输出，doxygen还可以用于创建latex、man或rtf文档。但是，并非所有格式都支持所有的图像类型。因而，有必要指定你所希望在其中包含的图像的输出格式。doxygen将在你通过叫作IMAGE_PATH的变量所指定的目录中查找图像文件。对此变量的设置以及其他的doxygen缺省值将在下面的“运行doxygen”中解释。目前，只需注意GLAST的惯例是在你的文档中为给定的包所使用的全部图像文件都将放在叫作doc/images/的目录中。
于是假设有一个叫作figuresim2.gif的图像文件在目录doc/images/中，我们想要将其插入我们的主页面，我们可以通过简单的改动来完成：
所产生的HTML输出见http://www.slac.stanford.edu/exp/glast/ground/software/doxygen_examples/v3/。
五、运行doxygen
你可以通过两种方式来运行doxygen。注意两种方法都需要你将doxygen安装在你的访问路径上。请访问doxygen的主页以获得下载和设置可执行程序的相关信息。
1) 对于vcmt用户，你可以简单地点击doxygen区域中的“create”按钮，从而为你选择的所有包创建HTML文档。然后点击“examine”来查看页面。
2) 对于非vcmt用户，你首先需要创建一个Doxyfile。Doxyfile允许你设置运行doxygen所需的所有设置和路径。要创建Doxyfile，执行
doxygen –g <filename>
“filename”指定含有doxygen设置的文件的名字；如果不指定名字，该文件就叫作“Doxyfile”。使用Doxyfile时你可能想要设置一些参数。我将提及三个有趣的参数，其他的请参考doxygen主页。
● INPUT：此参数指定doxygen在其中搜索源码的目录。对于上面的例子，需要设置
INPUT = src CalPack
● FILE_PATTERNS：此参数指定doxygen所要解析的文件的类型。对于上面的例子，
需要设置
FILE_PATTERNS = *.cpp *.h
● IMAGE_PATH：此参数指定doxygen在哪里查找使用\image命令包含的图像。对
于上面的例子（并且作为GLAST的惯例），需要设置
INCLUDE_PATH = doc/images
一旦你设置了这些参数以及其他任何你想要改变的参数，你就可以运行doxygen了。假定你的Doxyfile就叫作“Doxyfile”，执行
doxygen Doxyfile
它将解析你指定的所有文件。缺省地，HTML输出将被放在叫作html/的目录中（这也可以在Doxyfile中改变）。
译者注：
1. doxygen有内建的多语言支持，目前支持24种语言，其中包括中文。具体用法请参考doxygen的参考手册。
2. GLAST是The Gamma Ray Large Area Space Telescope（伽玛射线大区域空间望远镜）的缩写。主页在http://www-glast.stanford.edu/，可通过CVS访问其源码。
