Doxygen C++注释规范

Doxygen C++注释规范

一、  C++风格的注释

1   概述

C++的注释风格主要使用下面这种样式：即在注释块开始使用三个反斜杠‘/’

其他地方其实与JavaDoc的风格类似，只是C++风格不用 “*” 罢了。

2     简述与详述

C++风格的简述与详述方式与javaDoc类似。一般注释的描述由简述开始，经过特殊分隔方式后，后面紧跟详述的内容，C++风格可以使用的分隔方法有以下两种：

（1）使用 \brief 参数标识，空行作为简述和详述的间隔标识

        ///    \brief   Brief description. 

///    description continued.  

///  

///    Detailed description starts here.  

///

（2） 使用以空行（或者小数点加空格）作为简述与详述的分割

///    Briefdescription  

///   description continued.  

///     

///    Detaileddescription starts here.

以小数点加空格作为分隔如下：

///         Brief description  

///         description continued . （注意:这里有一个小数点,加上一个空格）  

///         Detailed description starts here.  

///

3    注释风格约定

1.一个代码块（类、函数、结构等）的概述采用单行的”///”加一个空格开头的注释，并写在该代码块声明的前面；
    2.一个代码块的详述采用至少两行的”///”加一个空格开头的注释，若不足两行第二行的开头也要写出来，并且放在代码块定义的前面；如果某代码没有声明只有定义或者相反，则在定义或者声明前面写上单行的概述+一个空行+多行的详述；
    3.枚举值列表的各项、结构域的各项等采用在本行最后添加”///<”加一个空格开头的注释；
    4.对变量的定义采用在变量上面加单行”///”加一个空格开头的注释（相当于是给改变量一个概述）；
    5.函数的参数用”/// @param”+一个空格开头的行描述在函数的详述里面；
    6.函数的返回值用”/// @return”+一个空格开头的行描述在函数的详述里面；
    7.函数之间的参考用”/// @see”+一个空格开头的行描述在函数的详述里面；
    8.文件头的版权以及文件描述的注释参见例代码。

4 文件头注释示例  // 

///    COPYRIGHT NOTICE  

///    Copyright (c) 2009,华中科技大学     （版权声明）  

///    All rights reserved.  

///  

///@file            （本文件的文件名eg：Test.h） 

/// @brief           （本文件实现的功能的简述） 

///  

///（本文件实现的功能的详述）  

///  

/// @version1.1     （版本声明）  

///@author           （作者，eg：卢俊） 

///@date             （文件创建日期，eg：2009年7月15日） 

///  

///  

///    修订说明：最初版本  

//

5  类定义注释示例

///    本类的功能：打印错误信息  

///  

///    本类是一个单件  

///    在程序中需要进行错误信息打印的地方  

class CPrintError 

{ 

          …… 

} 

6     类成员变量定义示例

（1）在成员变量上面加注释的格式

    ///成员变量描述

int  m_Var;

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

int  m_color;     ///颜色变量   

7    成员函数的注释示例

/// 下面是一个含有两个参数的函数的注释说明（简述）  

///    

///     这里写该函数的详述信息    

///     @param a被测试的变量（param描述参数）    

///     @param s指向描述测试信息的字符串    

///     @return    测试结果（return描述返回值）   

///     @see    Test()    （本函数参考其它的相关的函数，这里作一个链接）  

///     @note    (note描述需要注意的问题)    

int testMe(int a,constchar *s);  

8    枚举变量的注释示例

///    颜色的枚举定义  

///   

///    该枚举定义了系统中需要用到的颜色\n  

///    可以使用该枚举作为系统中颜色的标识  

enumTEnum  

{  

    RED,            ///<枚举，标识红色       

    BLUE,           ///<枚举，标志蓝色       

    YELLOW          ///<枚举，标志黄色.       

}enumVar;     

9     需要注意的问题

（1）Doxygen会忽略你在注释中加入的多余的换行，如果你希望保留两行注释之间的空行，那么，在该行加入 \n