C-Style Doxygen 注释格式

编程

摘录自部分Doxygen的官方文档：Documenting the code

1. doxygen 注释块

对于每一个代码的每一处注释可能包含两个或三个描述部分。这些部分最后都将被 doxygen 最终的文档之中。brief 和 detailed 两个注释部分都是可选的，对于方法（methods）和函数（functions）将会有第三个被叫做 in body 的注释部分。包含多个 brief 和 detailed 在 doxygen 中是可以的，但是并不推荐这么做。

C-Style 的 doxygen 注释格式如下：

1
2
3
/**
 * ... text ...
 */

或

1
2
3
///
/// ... text ...
///

2. Brief 注释部分

2.1 方式一

在注释块的上方使用 \brief 命令，这个命令以该段落结束。所以 detailed 注释部分与 brief 注释以空格隔开。示例如下：

1
2
3
4
5
6
/** 
 * \brief Brief description
 *        Brief description continued
 *
 * Detailed description starts here.
 */

2.2 方式二

对于 brief 注释不超过一行的，也可以用一下方式注释。

1
2
3
4
/// Brief description
/** 
 * Detailed description.
 */

3.将 doxygen 注释放置变量（members）后面

如果想注释一个 struct，class 或是 enum，那么最好的方式是将 doxygen 注释放置到 members 的后面。为了这个目的则需要使用这个 ‘<’ 额外的标记。同样该方法也可以用在函数参数当中。示例如下：

1
2
3
int var; /**< Detailed description after the member */
int var; ///< Detailed description after the member
void foo(int v /**< [in] docs for inpput parameter v. */);

4.将注释写在其它地方

在之前所述的注释方法中都是将注释块放到待注释代码的前面或是变量的前后。当然在大多数时候这样的写法是比较好的。但是有时候可能需要将注释放到其他的位置。

为了不将注释块放到代码的前面或是后面，你只需要在注释中添加一个结构标记。这样会为这个结构添加一些重复的信息，所有不得已最好不要使用。示例如下，为　Test Class 添加相关说明信息。增加了 @class 结构标记。

1
2
3
4
5
/** @class Test
    @brief A test class.

    A more detailed class description.
*/

其他的一些标记如下所示：

  • \struct 注释一个结构体

  • \union 注释一个联合体

  • \enum 注释一个枚举体

  • \fn 注释一个函数

  • \var 注释一个变量.

  • \def 注释一个 #define.

  • \typedef 注释一个 type definition.

  • \file 注释一个文件.

  • \namespace 注释一个命名空间.

  • \package 注释一个 Java package.

  • \interface 注释一个 IDL interface.

5.文件信息的注释例子

1
2
3
4
5
6
7
8
9
10
11
/**
 * @file XXXXX.c
 * @brief XXXXXXXXXXXXXXXXX
 *
 * xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 *
 * @author xxxxxxxxx
 * @date xxxx-xx-xx
 * @copyright xxxxxxx.com
 */