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