编程规范 - doxygen注释规范示例（C++）

doxygen注释规范示例（C++）

doxygen能根据code的注释自动生成code的帮助文档，并且doxygen是一个跨平台的开源的软件，但是要生成帮助文档，code内的注释必须按一定规则书写。下面是我总结的c/c++的注释书写规范，代码风格结合了google c++风格。

/**                                   | 文件注释
 * @file apply.c                      | “@file”后的文件名需与当前文件名一致
 * @author clover/[email protected]
 * @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             警告
 */