C++风格的注释
2016-03-07 17:45
351 查看
5.4 C++风格的注释
5.4.1 概述
C++的注释风格主要使用下面这种样式:即在注释块开始使用三个反斜杠‘/’其他地方其实与JavaDoc的风格类似,只是C++风格不用 “*” 罢了。
5.4.2 简述与详述
C++风格的简述与详述方式与javaDoc类似。一般注释的描述由简述开始,经过特殊分隔方式后,后面紧跟详述的内容,C++风格可以使用的分隔方法有以下两种:
(1)使用 \brief 参数标识,空行作为简述和详述的间隔标识
/// \brief Brief description. /// description continued. /// /// Detailed description starts here. ///
(2) 使用以空行 enum enumEditType
{
enumEditTypeInt=0x1, //只能输入数字。
enumEditTypeChar=0x2, //只能输入字符。
enumEditTypeNormal=0x3, //正常编辑框,可以输入任意字符。
};
typedef struct tagEDITxsl
{
UINT nMinChar;
UINT nMaxChar;
enumEditType m_edit_type;
std::wstring m_disable_char;
};
(或者小数点加空格)作为简述与详述的分割
/// Brief description /// description continued. /// /// Detailed description starts here.
以小数点加空格作为分隔如下:
/// Brief description /// description continued . (注意:这里有一个小数点,加上一个空格) /// Detailed description starts here. ///
5.4.3 注释风格约定
1. 一个代码块(类、函数、结构等)的概述采用单行的”///”加一个空格开头的注释,并写在该代码块声明的前面;2. 一个代码块的详述采用至少两行的”///”加一个空格开头的注释,若不足两行第二行的开头也要写出来,并且放在代码块定义的前面;如果某代码没有声明只有定义或者相反,则在定义或者声明前面写上单行的概述+一个空行+多行的详述;
3. 枚举值列表的各项、结构域的各项等采用在本行最后添加”///<”加一个空格开头的注释;
4. 对变量的定义采用在变量上面加单行”///”加一个空格开头的注释(相当于是给改变量一个概述);
5. 函数的参数用”/// @param”+一个空格开头的行描述在函数的详述里面;
6. 函数的返回值用”/// @return”+一个空格开头的行描述在函数的详述里面;
7. 函数之间的参考用”/// @see”+一个空格开头的行描述在函数的详述里面;
8. 文件头的版权以及文件描述的注释参见例代码。
5.4.4 文件头注释示例
////////////////////////////////////////////////////////////////////////// /// COPYRIGHT NOTICE /// Copyright (c) 2009, 华中科技大学 (版权声明) /// All rights reserved. /// /// @file (本文件的文件名eg:Test.h) /// @brief (本文件实现的功能的简述) /// ///(本文件实现的功能的详述) /// /// @version 1.1 (版本声明) /// @author (作者,eg:卢俊) /// @date (文件创建日期,eg:2009年7月15日) /// /// /// 修订说明:最初版本 //////////////////////////////////////////////////////////////////////////
5.4.5 类定义注释示例
/// 本类的功能:打印错误信息 /// /// 本类是一个单件 /// 在程序中需要进行错误信息打印的地方 class CPrintError { …… }
5.4.6 类成员变量定义示例
(1)在成员变量上面加注释的格式/// 成员变量描述 int m_Var;
(2)在成员变量后面加注释的格式
int m_color; /// 颜色变量
5.4.7 成员函数的注释示例
/// 下面是一个含有两个参数的函数的注释说明(简述) /// /// 这里写该函数的详述信息 /// @param a 被测试的变量(param描述参数) /// @param s 指向描述测试信息的字符串 /// @return 测试结果 (return描述返回值) /// @see Test() (本函数参考其它的相关的函数,这里作一个链接) /// @note (note描述需要注意的问题) int testMe(int a,const char *s);
5.4.8 枚举变量的注释示例
/// 颜色的枚举定义 /// /// 该枚举定义了系统中需要用到的颜色\n /// 可以使用该枚举作为系统中颜色的标识 enum TEnum { RED, ///< 枚举,标识红色 BLUE, ///< 枚举,标志蓝色 YELLOW ///< 枚举,标志黄色. }enumVar;
5.5 需要注意的问题
(1)Doxygen会忽略你在注释中加入的多余的换行,如果你希望保留两行注释之间的空行,那么,在该行加入 \n6 Doxygen使用的常见问题小结
6.1 中文问题:中文注释在文档中是乱码
解决:在expert中的INPUT选项页的INPUT_ENCODEING中填入“GB2312”,这样基于GB的文本编辑器生成的代码就可以正常使用了。6.2 图形问题:无法绘制类图协作图等图形。
解决:首先确保安装了graphviz for win,注意不是wingraphviz,后者是一个graphviz的com封装,但是doxygen并不是基于它开发的,所以装了也没用。然后在expert的DOT_PATH中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。如果出现无法包含.map文件的错误,可以将工作目录设置成html,并将html中所有文件都清除再试。这个问题的原因还不太确定。
6.3 输出chm的问题:如何输出.chm文件
配置时注意expert中的HTML页:选中“GENERATE_HTMLHELP”,然后在CHM_FILE中填上想要的chm文件名。HHC_LOCATION中输入hhc.exe文件的路径。hhc.exe可以通过安装HTML Help Workshop获得。
或者使用HTML Help Workshop来编译Doxygen生成的html文件夹中的.hhp文件,编译完成后即可在该html文件夹中找到对应的chm文件
6.4 Doxygen无法为DLL中定义的类 导出文档
例如:class __declspec(dllexport) CClassName:public CObject
{
}
目前发现Doxygen无法识别出DLL中定义的类。
相关文章推荐
- C语言-基础
- c++ 版本 opencv 读取视频
- 关于C++泛型及C++高效迭代开发的思考
- [原创]配置Dev c++热键实现快速注释
- 面试经验(妙计旅行:C++算法工程师)
- 最长递增子序列问题
- C++中给类初始化与赋值的区别
- C++中四种类型转换方式
- 第六节--基于Sobel的边缘检测C++程序的实现
- 第五届--图像腐蚀和膨胀的C++的处理
- C语言union关键字
- 第二节--中值滤波VC++实现
- 第一节--滤波操作的VC++实现
- C++中的运算符重载
- 1107. Social Clusters (30)
- c++ 字符串和数字相互转化
- C++中的单例模式
- 2016.3.7 16.14复习篇之三(蓝桥杯恶补)
- Cpp--处理字符串的自定义类
- C语言中改变字体颜色和背景的方法