原创 Doxygen 用法举例

在C++程序中写注释，把注释自动生成文档的工具
doxygen 是很有用的，它可以使你不用同时维护程序注释和文档，
自然地把你的文档和程序保持一致。
下面给出一个例子，illustrate 怎样使用doxygen 生成文档.
生成的html文档在
http://dsec.pku.edu.cn/~tlu/para/src/doc/html/index.html

原始的C++文件是

/**
* \file test.cpp 自动注释文档范例
* @author Tiao Lu 卢朓
* @date 2007-8-20
*
* @brief 例子说明Doxygen要求注释的格式.
*
* 上面是简单说明，空一个行后开始谢详细的说明。
* "@file" 这是对整个文件的注释，file前的'@'也可以用'\'代替.
* 用doxygen 生成的文件的步骤如下。
* <ol>
* <li>命令\n doxygen -g \n
* 这个命令将会生成一个文件,名字是 Doxyfile,
* 对这个文件稍加修改，我修改过的几个选项如下：
* <ol>
* <li>PROJECT_NAME = "Illustratin of the Use of Doxygen"
* <li>OUTPUT_DIRECTORY = ./doc
* <li>OUTPUT_LANGUAGE = Chinese
* <li>EXTRACT_ALL =YES
* <li>FILE_PATTERN = *.cpp
* </ol>
* <li>命令doxygen 将会在当前目录下创建一个文件夹 doc,
* 并且生成latex和html两个子文件夹，下面分别放着相应的文档。
* html文件立刻可以浏览，但是latex文件要稍微修改才能编译出正确的
* 中文文档。
* </ol>
*/

/**
* @brief这是一个全局变量。
*
* doxygen 默认的注释都是写在要注释的部分的前面，
* 写在后面的注释要加一个额外的符号'<'。
* 后面的注释往往用来说明一个class,struct, union, or
* enum 的成员变量
* */
int n;

int m; ///< 这是另一个全局变量。写在后面的注释也可采用"///<"

/**
* @brief 这是一个函数注释方式.
*
* 可以在注释中加入 Tex 格式书写的数学公式。
* 比如，一个嵌在行内的公式\f$ x^2+y^=z^2 \f$.
* 例如一个据中对齐的公式
* \f[
* \frac{x+y}{\sqrt{\Omega}} = \int_{0}^{1} t d t
* \f]
*
* @param x 对函数参数的注释。
* 这里使用 "@param x"标明这事变量 x 的说明语句。
* 注意刚才那句话的 "@param"和前面的汉字(英文也一样）
* 之间需要有一个空格，没有空格则显示不正常。
* 因为这个注释没有写在变量x的语句的前面，因此需要用 "@param x" 来声明。
* @param y 对函数参数的注释
*
*/
int f(int x, int y);

/**
* @brief 表述鼠标和键盘事件的类。
*
* 在写注释的时候，也可以使用html 的语法。如下面的例子就是生成列表
* ul 标示没有序号的列表，ol 标示有序号的列表。也可以使用-来生成列表，
* 不过使用html 语言更清楚，因为-生成的列表就是考自己对齐来判断列表的项
* 是否是同层的。
* 事件的列表:
* <ul>
* <li> 鼠标事件
* <ol>
* <li> 鼠标移动事件
* <li> 鼠标点击事件\n
* 鼠标点击事件的更多信息.
* <li>鼠标双击事件
* </ol>
* <li> 键盘事件
* <ol>
* <li> 按下键事件
* <li> 松开键事件
* </ol>
* </ul>
*/
class Event {
public:
int mouse; ///< 鼠标状态
int key;   ///< 键盘状态
};

/**
*@brief 这是键盘鼠标事件类的子类的简短注释。
*
* 空一行写详细注释。可以使用html 语言生成一个http 链接。
* 如北京大学将会在
* 文档中产生一个链接。注意：上面的链接地址立的 " 前面不要有
* "\"。 Doxygen 会自动分析所有的类之间的
* 相互继承关系，从而自动生成类的继承关系图表。
*
*/
class ChildEvent : Event {

public:

double time; ///< 按住键盘的时间
/**
* @defgroup Coord 坐标
* "@addtogroup" 后面的第一个单词是一个用来标识group的ID，
* 后面是group 的名字。可以使用"@{" 和 "@}" 来把要放在group 的
* 东西圈起来。
* @{
* */
double x_; ///< x_ 是x坐标
double y_; ///< y_ 是y坐标
const double & x() const; ///< 取得只读x坐标
const double & y() const; ///< 取得只读y坐标

/** @}*/ //Coord 坐标 这是用来标识Coord group的结束。
};

/**
* @brief 为了演示后面的"@addtogroup"，参考: AnotherChildEvent
*
* 应该写入详细注释。这里随便写几句。为了让两个加入group 的东西隔开
* 这里我们把 AnotherChildEvent 这儿，由于它是一个类，在html文档中，
* 这将自动生成一个超链接，点击可以链接到 AnotherChildEvent 的说明文档。
* 这个 AnotherChildEvent没有生成超级链接是因为这个单词和它后面的文字没有
* 用空格隔开。下面我们还用到 "@see" 这个命令，它将生成参考文件的一个列表。
*
* @param i 一个整数
* @param j 另一个整数
* @return 返回两个整数中较大的一个整数的值
* @see Event ChildEvent AnotherChildEvent
*/
int maximum(int i, int j);

/** @addtogroup Coord
* @{
*/

/**
* @brief 用来演示 "@addtogroup"
*
* 写了一些程序以后，还想把后面写的东西放在原来定义的group 当中，
* 但是我们不能用 "@{" 和"@}" 圈起来，因为中间可能有些东西你不想放在
* 这个group里。这时可以用 "addtogroup group的ID" 来把新的"@{" 和"@}"
* 内的注释加到group 中。
*/
class AnotherChildEvent: Event
{

public:
    int action; ///< 动作选项
/** @}*/ //addtogroup Coord 的尾
};