共计 1754 个字符,预计需要花费 5 分钟才能阅读完成。
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 警告
*/
正文完