标签: doxygen

  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 * liPROJECT_NAME = "Illustratin of the Use of Doxygen" * liOUTPUT_DIRECTORY = ./doc * liOUTPUT_LANGUAGE = Chinese * liEXTRACT_ALL =YES * liFILE_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 * * @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 的尾 };