转载自：http://luchenqun.com/?p=761
做一个C++方面的符合Doxygen的注释文档，备用。
1、头文件根原文件注释。这个我也不知道需要注释什么。能想到的是：谁写的，里面有些什么内容，文件是什么，版本号，日期等等。所以直接拷贝了网上的一个版本。大家根据情况直接增加或者减少吧。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
/**
* Copyright (C), 2015.XXXX公司,All rights reserved.
* @file
* @brief
* @author
* @email
* @version
* @date 2015-XX-XX
* @update 2015-XX-XX
* @note
* @warning
* @todo
* @history:
*/
|
2、一般在一个模块里面要定义一个group，模板如下
|
1
2
3
4
5
6
7
|
/*
* @defgroup 模块名 模块的说明文字
* @{
*/
... 定义的内容 ...
/** @} */
// 模块结尾这样可以在其他地方以更加详细的说明添加members到一个group。
|
3、类名注释模板
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
|
/**
* @class <class‐name> [header‐file] [<header‐name]
* @brief brief description
* @author <list of authors>
* @note
* detailed description
*/
// 一个类里面的简单注释例子
class Test
{
public:
/** @brief A enum, with inline docs */
enum TEnum
{
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
*enumPtr, /**< enum pointer. */
enumVar; /**< enum variable. */
/** @brief A constructor. */
Test();
/** @brief A destructor. */
~Test();
/** @brief a normal member taking two arguments and returning an integer value. */
int testMe(int a,const char *s);
/** @brief A pure virtual member.
* @param[in] c1 the first argument.
* @param[in] c2 the second argument.
* @see testMe()
*/
virtual void testMeToo(char c1,char c2) = 0;
int publicVar;/**< a public variable. */
/** @brief a function variable, note Details. */
int (*handler)(int a,int b);
/** @brief brief before delaration */
int m_func(int a);
};
|
4、枚举注释示例
|
1
2
3
4
5
6
|
/** Another enum, with inline docs */
enum AnotherEnum
{
V1, /**< value 1 */
V2 /**< value 2 */
};
|
5、全局变量与宏
全局变量和全局宏必须要有注释，如果注释较短，则可以在所注释代码上方用
|
1
2
|
/** @brief some brief description */
int g_count;
|
或右方用
|
1
|
int g_count /**< some brief description */进行简要注释。
|
6、函数注释。这个是所有里面最重要的。模板示例如下：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
|
/**
* @brief brief description
* @author <list of authors>
* @param[in|out] <parameter‐name> <parameter description>
* @return <description of the return value>
* @exception <exception‐object> <exception description>
* @note
* detailed description
* @remarks <remark text>
*/
// 一个示例
/**
* @breif 下面是一个含有两个参数的函数的注释说明（简述）
* @param[in] a 被测试的变量（param描述参数）
* @param[in] s 指向描述测试信息的字符串
* @return 测试结果 （return描述返回值）
* @see Test()（本函数参考其它的相关的函数，这里作一个链接）
* @note (note描述需要注意的问题)
*/
int testMe(int a,const char *s)
|
大概就这些吧。对于最后一个用的非常多的函数注释。再补充一下。如果使用Visual Studio，相信大家都装了一个Visual Assistant X的插件。它里面本身提供了一个函数模板，你只需要将那个函数模板改成适合Doxygen的格式即可。然后再函数名字上面点右键–>Refactor–>Document Method它自动会帮你生成一个按照你下的格式的文档。很方便的。
最后，将Doxygen一些常用指令附上。
| @author | 作者 |
| @brief | 摘要 |
| @version | 版本号 |
| @date | 日期 |
| @file | 文件名，可以默认为空，DoxyGen会自己加 |
| @class | 类名 |
| @param | 函数参数 |
| @return | 函数返回值描述 |
| @exception | 函数抛异常描述 |
| @warning | 函数使用中需要注意的地方 |
| @remarks | 备注 |
| @see | see also字段 |
| @note | brief下空一行后的内容表示详细描述，但也可以不空行用note表示 |
| @par | 开始一个段落，段落名称描述由你自己指定，比如可以写一段示例代码 |
| @code | 引用代码段 |
| @endcode | 引用代码段结束 |
| @pre | 函数前置条件，比如对输入参数的要求 |
| @post | 函数后置条件，比如对系统状态的影响或返回参数的结果预期 |
| @defgroup | 模块名 |
| @name | 分组名 |
| @{ | 模块开始 |
| @} | 模块结束 |
| @deprecated | 今后可能将被废弃或已经有替代品的函数 |
| @since | 从哪个版本后开始有这个函数的 |
| @todo | 被标记的代码会在ToDo列表中出现 |
| @bug | 被标记的代码会在Bug列表中出现 |
| @test | 被标记的代码会在Test列表中出现 |
| – | 一级项目符号 |
| -# | 二级项目符号 |
尼玛我必须要吐槽一下，百度UEditor怎么老是对不齐啊！害我对格式对了好久好久！最后很无奈，只能用table来显示。但是table又无法调节每一列的宽度！我勒个去！
说一下如何在Visual Studio 中使用Visual Assist添加Doxygen格式的文档。
随便在一个函数上面右键–>Refactor–>Edit Refactoring Snippets。里面就有大量的注释模板。详见如下两个图片。
Visual Assist定义了许多宏，你按$就会有提示。详见这个链接。编辑好之后，你在函数上面右键，点上面的第一个图的Document Method，他就会帮你自动生成你想要的模板了。
参考资料：