Doxygen使用教程2--C++标准注释原则（QtCreator）

C++注释规范

下载国外的源代码，往往能看到附带的说明文档，文档都有详细的说明，大部分文档都可以通过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
{
}

函数标注

方法一：

/// \brief 函数简要说明-测试函数
/// \param n1 参数1
/// \param c2 参数2
/// \return 返回说明
bool text(int n1,Ctext c2);

方法二：

/// \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的说明
};

其他关键字

命令	生成字段	说明
@see	参考
@class	引用类	用于文档生成连接
@var	引用变量	用于文档生成连接
@enum	引用枚举	用于文档生成连接
@code	代码块开始	与@endcode成对使用
@endcode	代码块结束	与@code成对使用
@bug	缺陷	链接到所有缺陷汇总的缺陷列表
@todo	TODO	链接到所有TODO汇总的TODO列表
@example	使用例子说明
@remarks	备注说明
@pre	函数前置条件
@deprecated	函数过时说明

其他Doxygen的关键字参见Doxygen文档：
http://www.doxygen.nl/manual/index.html

QtCreator中使用

在QtCreator中自带Doxygen补全模块，开启如下图
自动补全如下：在变量名或函数前一行输入///然后回车，系统会自动生成

///
/// \brief 变量名或函数名及参数或类名
///

将Readme.md作为文档首页

readme.md格式如下

Title {#mainpage}
================
具体详细内容