1、Doxygen介绍
Doxygen能将程序中的特定批注转换成为说明文件。它可以依据程序本身的结构,将程序中按规范注释的批注经过处理生成一个纯粹的参考手册,通过提取代码结构或借助自动生成的包含依赖图、继承图)以及协作图来可视化文档之间的关系,Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML等。
微软出品的HTML Help WorkShop是制作CHM文件的最佳工具,它能将HTML文件编译生成CHM文档。Doxygen软件默认生成HTML文件或Latex文件,我们要通过HTML生成CHM文档,需要先安装HTML Help WorkShop软件,并在Doxygen中进行关联即可。
2、语法介绍
所谓Doxygen
语法就是在写程序注视时候按照Doxygen
语法规则来写注释。只有按照标准的注释规则来写注释,生成的文档才会非常漂亮,否则乱七八糟的。
文件注释
一般放到文件开头
/**
* @file 文件名
* @brief 简介
* @details 细节
* @author 作者
* @version 版本号
* @date 年-月-日
* @copyright 版权
*/
实例
3、结构体注释
/**
* @brief 类的详细描述
*/
实例
4、函数注释
/**
* @brief 函数描述
* @param 参数描述
* @return 返回描述
* @retval 返回值描述
*/
实例
5、常量/变量
一般常量/变量可以有两种形式:
-
常量/变量上一行注释
-
常量/变量后注释
//定义一个整型变量a int a; /** * @brief 定义一个整型变量a */ int a;
int a; /*!< 定义一个整型变量a */
int a; /**< 定义一个整型变量a */
int a; //!< 定义一个整型变量a
int a; ///< 定义一个整型变量a
网上抄一个例子
/** | 文件注释
* @file hello.c | “@file”后的文件名需与当前文件名一致
* @author clover/clover@123.com
* @version 1.0
* @date 2013-12-12
* @brief 概述:doxygen使用文档
* 详细介绍了doxygen的C++注释方法
* @details 详细说明
* @see MainWindow参考其它的相关的函数,这里作一个链接 url
* @note 描述需要注意的问题
*/
/// This macro is toolong, so comment here briefly! | 推荐使用简洁的宏注释
#define HTTP_REQUEST_LEN_MAX APPLY_BUF_SIZE_BIG
/**
* The detail macro comment, may be multi-line. | 尽量少写宏函数,可以使用内联函数代替
* @param a The brief parameter comment
* @param b The brief parameter comment
* @return The brief return value comment
*/
#define MAX(a, b) ((a) > (b))? (a) : (b)
/**
* @brief 结构体 | 结构体成员的详细注释写在该成员上面
* (与名称后面的描述有一个就可以) | 结构体成员的详细注释与上一成员间留1个空行
* | 推荐使用简洁的结构体注释
*/
struct StructVariable { /// @brief 简单的描述 | “///”与注释间留有2个空格
int a; ///< variable a | “///<”与注释间留有1个空格
int b; ///< variable b
/** this is details mement comment */
int c; ///< variable c
int d; ///< variable d
};
/**
* @enum 性别枚举
*/
enum Sex { /// @enum 性别枚举
kMale, ///< enum male
kFemale ///< enum female
};
/**
* @brief 主窗口
*/
class MainWindow : public QMainWindow
{
Q_OBJECT
public:
MainWindow(QWidget *parent = 0);
~MainWindow();
bool SetProName(QString name); ///< 设置工区名称
private:
QString m_name_;
};
/// @brief 函数名称:setProName
static int ApplyLogin();
/**
* @brief 函数名称:setProName |尽量避免函数声明和定义重复注释
* @todo 代码实现的功能: 设置工区名称
* @param 参数:QWidget*
* @return 说明:int
* @retval 1. true 名字设置成功 (返回值说明(可选))
* @retval 2. false 名字设置失败
* @bug 此处的bug描述: 无
*/
bool MainWindow::SetProName(QString name)
{
}
// 其它注释
// 代码中其余注释一律使用普通的单行注释“//”和多行注释“/*”“*/
/*
* Doxygen 会忽略你注释中的换行符,将多行注释连接成一个连续行并使用空格隔开。
* 如果你希望保留两行注释之间的换行,需要在该行末加入“/n”。
*
* 常用命令
* @attention 注意
* @author 作者
* @bug 缺陷,链接到所有缺陷汇总的缺陷列表
* @brief 简要注释
* @code 代码块开始,与“endcode”成对使用
* @endcode 代码块结束,与“code”成对使用
* @details 详细注释
* @date 日期
* @file < 文件名> 文件参考,用在文件注释中
* @param 参数,用在函数注释中
* @return 返回,用在函数注释中
* @todo TODO,链接到所有TODO 汇总的TODO 列表
* @version 版本
* @warning 警告
*/