doxygen注释规范示例(C++)
doxygen能根据code的注释自动生成code的帮助文档,并且doxygen是一个跨平台的开源的软件,但是要生成帮助文档,code内的注释必须按一定规则书写。下面是我总结的c/c++的注释书写规范,代码风格结合了google c++风格。
/** | 文件注释
* @file apply.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 警告
*/