转载自：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++为代码作注释）

最新文章

  1. 修改Firefox的User-Agent，伪装修改秘籍
  2. Discrete.Differential.Geometry-An.Applied.Introduction(sig2008)笔记
  3. 搜索引擎 ElasticSearch 之 步步为营1 【环境搭建&amp;初识ElasticSearch】
  4. linux 匹配字符串是否为数字
  5. Spring的quartz定时器同一时刻重复执行二次的问题解决
  6. ISNULL
  7. Android 图片处理方法
  8. tornado学习精要
  9. iOS工程适配64-bit经验分享
  10. 【转载】关于c++中的explicit
  11. 总账balance表
  12. UVA1328 Period
  13. Match-----Correlation-----find_ncc_model_exposure
  14. SQL Server 2014内存优化表的使用场景（转载）
  15. 5-niginx-健康检查模块
  16. Daily Scrum5 11.7
  17. 团体程序设计天梯赛 L3-012. 水果忍者
  18. [leetcode]Single Number II @ Python
  19. OleVariant Variant
  20. tomcat运行springboot项目war包

热门文章

  1. 【环境配置】Linux的经常使用命令
  2. 数据结构与算法——AVL树类的C++实现
  3. java基础&amp;amp;&amp;amp;高薪面试
  4. Spring Boot 测试时的日志级别
  5. Java Base64加密、解密原理Java代码(转载）
  6. [Phoenix] 一、快速入门
  7. echart地图下钻
  8. 九度OJ 1106：数字之和 （基础题）
  9. 【Effective C++】构造/析构/赋值运算
  10. 获取app-package和app-activity的值