网上摘录Doxygen的使用

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