[转载]Doxygen C++ 注释风格

转载自：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，他就会帮你自动生成你想要的模板了。

参考资料：

1、doxygen的特定命令

2、doxygen 使用简介（C,C++为代码作注释）