本文详细介绍了C++代码中如何使用Doxygen进行注释标注，包括文件头、命名空间、类说明、函数注释、变量及枚举的标注方法。并提供了在Visual Studio环境下设置中文显示和生成私有成员的方法，以及如何利用工具箱快速标注代码。
标注总述
下载国外的源代码，往往能看到附带的说明文档，文档都有详细的说明，大部分文档都可以通过doxygen这个跨平台软件生成，doxygen并不能随便读取你的C++的注释,必须按照一定的规则才能生成，所以在编写代码时，一定要按照标准写注释，否则会为以后带来许多麻烦
下面介绍C++的标注写法，c++不推荐c语言式的/* */风格注释，这里，除了文件头使用这种注释外其余到使用C++风格的注释。
先看看总述：
文件头：
[cpp] view plaincopy
[cpp] view plaincopy
-
/*!
-
* \file Ctext.h
-
* \brief 概述
-
*
-
*详细概述
-
*
-
* \author 作者名字
-
* \version 版本号(maj.min，主版本.分版本格式)
-
* \date 日期
-
*/
命名空间：
[cpp] view plaincopy
-
/// \brief 命名空间的简单概述
-
///
-
///命名空间的详细概述
-
namespace text
-
{
-
……
-
}
类说明：
[cpp] view plaincopy
-
/// \brief Ctext的doxygen测试
-
///
-
/// 作doxygen测试用
-
class Ctext
-
{
-
}
函数标注
方法1：
[cpp] view plaincopy
-
/// \brief 函数简要说明-测试函数
-
/// \param n1 参数1
-
/// \param c2 参数2
-
/// \return 返回说明
-
bool text(int n1,Ctext c2);
方法2：
[cpp] view plaincopy
-
/// \brief 函数简要说明-测试函数
-
///
-
/// 函数详细说明，这里写函数的详细说明信息，说明可以换行
-
/// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行
-
/// ，详细说明之前不需要任何标识符
-
/// \param n1 参数1说明
-
/// \param c2 参数2说明
-
/// \return 返回说明
-
/// \see text
-
bool text2(int n1,Ctext c2);
变量及枚举
[cpp] view plaincopy
-
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的说明
-
};
[cpp] view plaincopy
-
/*!
-
* \file Ctext.h
-
* \brief 概述
-
*
-
*详细概述
-
*
-
* \author 作者,包含email等
-
* \version 版本号(maj.min，主版本.分版本格式)
-
* \date 日期
-
*/
上注释等下于下面这种写法
[cpp] view plaincopy
-
/*!
-
\file Ctext.h
-
\brief 概述
-
详细概述
-
\author 作者,包含email等
-
\version 版本号(maj.min，主版本.分版本格式)
-
\date 日期
-
*/
对于vs编译器可能中间那行*号比较麻烦，可以不写，对于Qt这种要去掉中间的*号反而是件麻烦事就不用去掉
用doxygen生成注释如下效果
命名空间说明如下写
[cpp] view plaincopy
-
/// \brief 命名空间的简单概述
-
///
-
///命名空间的详细概述
-
namespace text
-
{
-
-
}
doxygen的说明写法都是类似于
[cpp] view plaincopy
-
/// \brief
-
///
-
///
以下将会见到很多这样的写法
上注释的doxygen效果如下
3. 类说明
类的注释和函数一样，
[cpp] view plaincopy
-
/// \brief Ctext的doxygen测试
-
///
-
/// 作doxygen测试用
-
class Ctext
-
{
-
}
上注释用doxygen生成文档效果如下：
函数详细注释位于头文件，cpp文件只对函数做简明注释
cpp文件不做///的注释，否则会和头文件重叠
[cpp] view plaincopy
-
/// \brief 函数简要说明-测试函数
-
/// \param n1 参数1
-
/// \param c2 参数2
-
/// \return 返回说明
-
bool text(int n1,Ctext c2);
简要注释此注释会让doxygen生成函数简要说明和参数说明
生成结果如：
4.2 函数简要说明+详细说明
[cpp] view plaincopy
-
/// \brief 函数简要说明-测试函数
-
///
-
/// 函数详细说明，这里写函数的详细说明信息，说明可以换行
-
/// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行
-
/// ，详细说明之前不需要任何标识符
-
/// \param n1 参数1说明
-
/// \param c2 参数2说明
-
/// \return 返回说明
-
bool text2(int n1,Ctext c2);
上注释用doxygen生成文档效果如下：
4.3 不带简要说明的函数标注
[cpp] view plaincopy
-
/// 函数说明-测试函数
-
///
-
/// 函数详细说明，这里写函数的详细说明信息，说明可以换行
-
/// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行
-
/// ，详细说明之前不需要任何标识符
-
/// \param n1 参数1说明
-
/// \param c2 参数2说明
-
/// \return 返回说明
-
bool text3(int n1,Ctext c2);
上注释用doxygen生成文档效果如下：
这里没有说明
4.4 带参见的写法
[cpp] view plaincopy
-
/// \brief 函数说明-测试函数4
-
/// \param n1 参数1说明
-
/// \param c2 参数2说明
-
/// \return 返回说明
-
/// \see text3 text2 text
-
bool text4(int n1,Ctext c2);
上注释用doxygen生成文档效果如下：
\see 上可以带中文等说明，doxygen会自动识别代码里存在的函数
5.变量注释
变量注释用///< 对变量进行说明，对于详细信息可以加\brief
[cpp] view plaincopy
-
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.枚举
枚举变量的标注方法如下
[cpp] view plaincopy
-
/// \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
对于其他的代码文件如果中文乱码，可以用文本编辑器转换代码文本编码为UTF-8带BOM的（注意这有可能影响代码，所以转换编码时要备份），再进行导出。
vs2010 等编译器并不能像Qt Creator那样生成上述标注样式，但是可以集成到vs的工具栏里，集成方法如下图所示：
这样在标注时可以直接从工具箱拖曳了，非常方便
[cpp] view plaincopy
-
/*!
-
* \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的说明
-
};
-
};
扫一扫
971
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
