Doxygen注释风格

 http://www.cnblogs.com/wishma/archive/2008/07/24/1250339.html

5      Doxygen的注释风格5.1   综述在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是brief描述, 另一种就是detailed。 两种都是可选的，但不能同时没有。 顾名思义, 简述(brief)就是在一行内简述地描述。而详细描述(detailed description)则提供更长, 更详细的文档。 Doxygen支持c风格注释、c++风格注释以及javaDoc风格注释等，下面将分别予以介绍。若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释：
    1） 文件头（包括.h和.cpp）
        主要用于声明版权，描述本文件实现的功能，以及文件版本信息等
    2） 类的定义
        主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述
    3） 类的成员变量定义
        在类的成员变量上方，对该成员变量进行简要地描述
    4） 类的成员函数定义
        在类定义的成员函数上方，对该成员函数功能进行简要描述
    5） 函数的实现在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等 5.2    Doxygen支持的指令5.2.1   概述可以在注释中加一些Doxygen支持的指令，主要作用是控制输出文档的排版格式，使用这些指令时需要在前面加上“”或者“@”（JavaDoc风格）符号，告诉Doxygen这些是一些特殊的指令，通过加入这些指令以及配备相应的文字，可以生成更加丰富的文档，下面对比较常用的指令做一下简单介绍。5.2.2   常用指令介绍 @file 档案的批注说明。 @author 作者的信息 @brief 用于class 或function的简易说明 eg： @brief 本函数负责打印错误信息串 @param 主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明 @return 描述该函数的返回值情况 eg: @return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE @retval 描述返回值类型 eg:@retval NULL 空字符串。
@retval !NULL 非空字符串。 @note 注解 @attention 注意 @warning 警告信息 @enum 引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg： @enum CTest::MyEnum @var 引用了某个变量，Doxygen会在该枚举处产生一个链接 eg： @var CTest::m_FileKey @class 引用某个类， 格式：@class <name> [<header-file>] [<header-name>] eg: @class CTest "inc/class.h" @exception 可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常 5.3      JavaDoc风格的注释5.3.1    概述JavaDoc风格的注释风格主要使用下面这种样式：即在注释块开始使用两个星号‘*‘

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

5.3.2    简述与详述的方式Doxygen支持的块（类、函数、结构体等）的注释描述分为两种：简述 和 详述一般注释的描述由简述开始，经过特殊分隔方式后，后面紧跟详述的内容，javaDoc风格可以使用的分隔方法有以下两种：1）       使用 rief 参数标识，空行作为简述和详述的间隔标识

1. /*!     @brief   Brief description.
2. *     description continued.
3. *
4. *     Detailed description starts here.
5. */

2） 直接使用javaDoc风格，javaDoc风格自动以简述开头，以空行（或者小数点加空格）作为简述与详述的分割

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

2. /**         Brief description
3. *          description continued . (注意:这里有一个小数点,加上一个空格)
4. *          Detailed description starts here.
5. */

5.3.3   文件头注释示例

1. //////////////////////////////////////////////////////////////////////////
2. ///     COPYRIGHT NOTICE
3. ///     Copyright (c) 2009, 华中科技大学      （版权声明）
4. ///     All rights reserved.
5. ///
6. /// @file     （本文件的文件名eg：Test.h）
7. /// @brief （本文件实现的功能的简述）
8. ///
9. ///（本文件实现的功能的详述）
10. ///
11. /// @version 1.1      （版本声明）
12. /// @author             （作者，eg：卢俊）
13. /// @date                 （文件创建日期，eg：2009年7月15日）
14. ///
15. ///
16. ///     修订说明：最初版本
17. //////////////////////////////////////////////////////////////////////////
18.   

5.3.4   类定义注释示例

1. /**     本类的功能：打印错误信息
2. *
3. *      本类是一个单件
4. *      在程序中需要进行错误信息打印的地方
5. */
6. class CPrintError
7. {
8.              ……
9. }

5.3.5   类成员变量定义示例（1）在成员变量上面加注释的格式

1. /** 成员变量描述 */
2. int   m_Var;

（2）在成员变量后面加注释的格式

1. int   m_color;     /**< 颜色变量 */     

5.3.6   成员函数的注释示例

1. /** 下面是一个含有两个参数的函数的注释说明（简述）
2. *
3. *      这里写该函数的详述信息
4. *      @param a 被测试的变量（param描述参数）
5. *      @param s 指向描述测试信息的字符串
6. *      @return     测试结果 （return描述返回值）
7. *      @see     Test()     （本函数参考其它的相关的函数，这里作一个链接）
8. *      @note     (note描述需要注意的问题)
9. */
10. int testMe(int a,const char *s);

5.3.7     枚举变量的注释示例

1. /**     颜色的枚举定义
2.    *
3.    *     该枚举定义了系统中需要用到的颜色
4.    *     可以使用该枚举作为系统中颜色的标识
5.    */
6. enum TEnum
7. {
8.       RED,           /**< 枚举，标识红色     */    
9.       BLUE,          /**< 枚举，标志蓝色     */    
10.       YELLOW         /**< 枚举，标志黄色. */    
11. }enumVar;