C++标准注释原则 - 基于doxygen的C++注释
来源:互联网 发布:淘宝关键词指数查询 编辑:程序博客网 时间:2024/05/29 10:59
标注总述
下载国外的源代码,往往能看到附带的说明文档,文档都有详细的说明,大部分文档都可以通过doxygen这个跨平台软件生成,doxygen并不能随便读取你的C++的注释,必须按照一定的规则才能生成,所以在编写代码时,一定要按照标准写注释,否则会为以后带来许多麻烦
下面介绍C++的标注写法,c++不推荐c语言式的/* */风格注释,这里,除了文件头使用这种注释外其余到使用C++风格的注释。
先看看总述:
/*!* \file Ctext.h* \brief 概述 * *详细概述 * * \author 作者名字* \version 版本号(maj.min,主版本.分版本格式) * \date 日期 */
命名空间:
/// \brief 命名空间的简单概述 /// ///命名空间的详细概述namespace text{ ……}
类说明:
/// \brief Ctext的doxygen测试////// 作doxygen测试用class Ctext{}
函数标注
方法1:
/// \brief 函数简要说明-测试函数 /// \param n1 参数1 /// \param c2 参数2 /// \return 返回说明 bool text(int n1,Ctext c2);方法2:
/// \brief 函数简要说明-测试函数 /// /// 函数详细说明,这里写函数的详细说明信息,说明可以换行 /// ,如这里所示,同时需要注意的是详细说明和简要说明之间必须空一行 /// ,详细说明之前不需要任何标识符 /// \param n1 参数1说明 /// \param c2 参数2说明 /// \return 返回说明 /// \see text bool text2(int n1,Ctext c2);
变量及枚举
int m_a; ///< 成员变量1m_a说明 double m_b; ///< 成员变量2m_b说明 /// \brief 成员变量m_c简要说明 /// /// 成员变量m_c的详细说明,这里可以对变量进行 ///详细的说明和描述,具体方法和函数的标注是一样的 float m_c; /// \brief xxx枚举变量的简要说明 /// /// xxx枚举变量的详细说明--枚举变量的详细说明和函数的详细说明 ///的写法是一致的。每个枚举变量下可以进行单独说明 enum{ em_1,///< 枚举值1的说明 em_2,///< 枚举值2的说明 em_3 ///< 枚举值3的说明 };
1.文件头说明
文件头说明按照如下格式写/*!* \file Ctext.h* \brief 概述 * *详细概述 * * \author 作者,包含email等 * \version 版本号(maj.min,主版本.分版本格式) * \date 日期 */
上注释等下于下面这种写法
/*! \file Ctext.h\brief 概述 详细概述 \author 作者,包含email等 \version 版本号(maj.min,主版本.分版本格式) \date 日期 */
对于vs编译器可能中间那行*号比较麻烦,可以不写,对于Qt这种要去掉中间的*号反而是件麻烦事就不用去掉
用doxygen生成注释如下效果
2. 命名空间
命名空间说明如下写
/// \brief 命名空间的简单概述 /// ///命名空间的详细概述namespace text{}
doxygen的说明写法都是类似于
/// \brief/// ///
以下将会见到很多这样的写法
上注释的doxygen效果如下
3. 类说明
类的注释和函数一样,
/// \brief Ctext的doxygen测试////// 作doxygen测试用class Ctext{}
上注释用doxygen生成文档效果如下:
4.函数注释原则
函数详细注释位于头文件,cpp文件只对函数做简明注释
cpp文件不做///的注释,否则会和头文件重叠
4.1 函数简要说明
注释方法1:/// \brief 函数简要说明-测试函数 /// \param n1 参数1 /// \param c2 参数2 /// \return 返回说明 bool text(int n1,Ctext c2);
简要注释此注释会让doxygen生成函数简要说明和参数说明
生成结果如:
4.2 函数简要说明+详细说明
/// \brief 函数简要说明-测试函数 /// /// 函数详细说明,这里写函数的详细说明信息,说明可以换行 /// ,如这里所示,同时需要注意的是详细说明和简要说明之间必须空一行 /// ,详细说明之前不需要任何标识符 /// \param n1 参数1说明 /// \param c2 参数2说明 /// \return 返回说明 bool text2(int n1,Ctext c2);
上注释用doxygen生成文档效果如下:
4.3 不带简要说明的函数标注
/// 函数说明-测试函数 /// /// 函数详细说明,这里写函数的详细说明信息,说明可以换行 /// ,如这里所示,同时需要注意的是详细说明和简要说明之间必须空一行 /// ,详细说明之前不需要任何标识符 /// \param n1 参数1说明 /// \param c2 参数2说明 /// \return 返回说明 bool text3(int n1,Ctext c2);
上注释用doxygen生成文档效果如下:
这里没有说明
4.4 带参见的写法
/// \brief 函数说明-测试函数4 /// \param n1 参数1说明 /// \param c2 参数2说明 /// \return 返回说明 /// \see text3 text2 text bool text4(int n1,Ctext c2);
上注释用doxygen生成文档效果如下:
\see 上可以带中文等说明,doxygen会自动识别代码里存在的函数
5.变量注释
变量注释用///< 对变量进行说明,对于详细信息可以加\brief
int m_a; ///< 成员变量1m_a说明 double m_b; ///< 成员变量2m_b说明 /// \brief 成员变量m_c简要说明 /// /// 成员变量m_c的详细说明,这里可以对变量进行 ///详细的说明和描述,具体方法和函数的标注是一样的 float m_c;
如果变量需要详细说明的可已按照m_c的写法写,注意,m_b和m_c之间一定需要空行,否则会导致m_b的简述消失
上注释用doxygen生成文档的具体效果如下
6.枚举
枚举变量的标注方法如下
/// \brief xxx枚举变量的简要说明 /// /// xxx枚举变量的详细说明--枚举变量的详细说明和函数的详细说明 ///的写法是一致的。每个枚举变量下可以进行单独说明 enum{ em_1,///< 枚举值1的说明 em_2,///< 枚举值2的说明 em_3 ///< 枚举值3的说明 };
枚举的总体说明和函数的写法一致,每个枚举变量的说明和变量的说明写法一致
上注释用doxygen生成效果如下:
7.doxygen的设置和中文问题
7.1 生成私有成员
如果想生成私有成员(doxygen默认不生成私有成员),可以如下设置
选择Expert标签的Build项,勾选EXTRACT_PRIVATE即可
7.2 中文问题
中文有时候是乱码对于vs2010的文档,默认是gb2312,可以设置
Expert标签的Project项目的DOXYFILE_ENCODING 为 GB18030
INPUT_ENCODING 为 GB18030
另外Project项目的生成语言(OUTPUT_LANGUAGE)选择Chinese
8.vs2008、vs2010 及以上IDE的快速标注方法
vs2010 等编译器并不能像Qt Creator那样生成上述标注样式,但是可以集成到vs的工具栏里,集成方法如下图所示:
这样在标注时可以直接从工具箱拖曳了,非常方便
附:
Ctext.h/*!* \file Ctext.h* \brief 概述 * *详细概述 * * \author 作者,包含email等 * \version 版本号(maj.min,主版本.分版本格式) * \date 日期 */#pragma once/// \brief 命名空间的简单概述 /// ///命名空间的详细概述namespace text{}/// \brief Ctext的doxygen测试////// 作doxygen测试用class Ctext{public: Ctext(void); ~Ctext(void); /// \brief 函数简要说明-测试函数 /// \param n1 参数1说明 /// \param c2 参数2说明 /// \return 返回说明 bool text(int n1,Ctext c2); /// \brief 函数简要说明-测试函数 /// /// 函数详细说明,这里写函数的详细说明信息,说明可以换行 /// ,如这里所示,同时需要注意的是详细说明和简要说明之间必须空一行 /// ,详细说明之前不需要任何标识符 /// \param n1 参数1说明 /// \param c2 参数2说明 /// \return 返回说明 bool text2(int n1,Ctext c2); /// 函数说明-测试函数 /// /// 函数详细说明,这里写函数的详细说明信息,说明可以换行 /// ,如这里所示,同时需要注意的是详细说明和简要说明之间必须空一行 /// ,详细说明之前不需要任何标识符 /// \param n1 参数1说明 /// \param c2 参数2说明 /// \return 返回说明 bool text3(int n1,Ctext c2); /// \brief 函数说明-测试函数4 /// \param n1 参数1说明 /// \param c2 参数2说明 /// \return 返回说明 /// \see text3 text2 text bool text4(int n1,Ctext c2); int m_a; ///< 成员变量1m_a说明 double m_b; ///< 成员变量2m_b说明 /// \brief 成员变量m_c简要说明 /// /// 成员变量m_c的详细说明,这里可以对变量进行 ///详细的说明和描述,具体方法和函数的标注是一样的 float m_c; /// \brief xxx枚举变量的简要说明 /// /// xxx枚举变量的详细说明--枚举变量的详细说明和函数的详细说明 ///的写法是一致的。每个枚举变量下可以进行单独说明 enum{ em_1,///< 枚举值1的说明 em_2,///< 枚举值2的说明 em_3 ///< 枚举值3的说明 };};
另外可看看这篇文章里面的注释:http://blog.csdn.net/czyt1988/article/details/21743595
- 基于Doxygen的C/C++注释原则
- 基于Doxygen的C/C++注释原则
- 基于Doxygen的C/C++注释原则
- 基于Doxygen的C/C++注释原则
- C++标准注释原则 - 基于doxygen的C++注释
- Doxygen:类C语言的注释块
- C/C++ doxygen注释示例
- C-Style Doxygen注释格式
- [总结]doxygen的使用与C/C++注释规范
- doxygen的使用与C/C++注释规范
- 嵌入式C语言中的Doxygen注释模板
- 嵌入式C语言中的Doxygen注释模板
- 嵌入式C语言中的Doxygen注释模板
- 嵌入式C语言中的Doxygen注释模板
- C语言:标准的函数注释格式
- Doxygen 的注释格式
- Doxygen注释的风格
- Doxygen 的简单注释
- Android - Binder机制 - client和普通service交互
- php性能监测模块XHProf[转]
- Android - Binder机制 - Binder框架总结
- 稳定排序和不稳定排序
- 1
- C++标准注释原则 - 基于doxygen的C++注释
- Android - Binder机制 - ProcessState和IPCThreadState
- 【WPF】自定义控件之依赖属性
- 什么是大数据?
- python类之间调用
- 移动应用数据统计平台(之二)
- JSP url 斜杠
- Python中调用父类的同名方法
- IndexedDB的JS接口设计详解