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 | “///

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 警告

*/