Doxygen的安装与使用及注释语法

  Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。提供了一套注释方式便于把代码中的注释生成说明文档。

1. Doxygen的安装使用

  需要安装 doxygen，graphviz. htmlhelp，注意：安装目录不要有中文字符或其他奇怪字符。Doxygen套件的下载链接为 Doxygen套件的下载链接

1.1 选择配置源码目录和目标文件目录

1.2 Mode配置

1.3 选择生成 chm 帮助文件

1.4 调用关系图配置

  需要安装 graphviz

1.5 工程文件编码格式配置

1.6 设置提取的范围

  Build页面，这个页面是生成帮助信息中比较关键的配置页面：

--------	-----
EXTRACT_ALL	输出所有的函数，但是private和static函数不属于其管制。
EXTRACT_PRIVATE	输出private函数。
EXTRACT_STATIC	输出static函数。同时还有几个EXTRACT，相应查看文档即可。
HIDE_UNDOC_MEMBERS	那些没有使用doxygen格式描述的文档（函数或类等）就不显示了。当然，如果EXTRACT_ALL被启用，那么这个标志其实是被忽略的。
INTERNAL_DOCS	是否输出注解中的@internal部分。如果没有被启动，那么注解中所有的@internal部分都将在目标帮助中不可见。
CASE_SENSE_NAMES	是否关注大小写名称，注意，如果开启了，那么所有的名称都将被小写。对于C/C++这种字母相关的语言来说，建议永远不要开启。
HIDE_SCOPE_NAMES	域隐藏，建议永远不要开启。
SHOW_INCLUDE_FILES	是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列表。
INLINE_INFO	如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。
SORT_MEMBER_DOCS	如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显示。
GENERATE_TODOLIST	是否生成TODOLIST页面，如果开启，那么包含在@todo注解中的内容将会单独生成并显示在一个页面中，其他的GENERATE选项同。
SHOW_USED_FILES	是否在函数或类等的帮助中，最下面显示函数或类的来源文件。
SHOW_FILES	是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

1.7 Input配置

1.8 chm文件设置

1.9 生成的调用关系图配置

1.10 生成 chm帮助文件

  完成配置以后，点击RUN->tun doxygen开始生成文件。最后生成带中文目录的CHM文档

2. Doxygen注释语法

  Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。提供了一套注释方式便于把代码中的注释生成说明文档。

2.1 简单注释

    单行注释：/// 或者 //!

    多行注释：/** 或者 /*!

2.2 文件注释

  文件注释通常放在整个文件开头。

/**
 * @file 文件名
 * @brief 简介
 * @details 细节
 * @mainpage 工程概览
 * @author 作者
 * @email 邮箱
 * @version 版本号
 * @date 年-月-日
 * @license 版权
 */

  例如：

/**
 * @file Test.h
 * @brief 测试头文件
 * @details 这个是测试Doxygen
 * @mainpage 工程概览
 * @author zhangsan
 * @email zhangsan @126.com
 * @version 1.0.0
 * @date 2017-11-17
 */

2.3 类定义注释

  类定义的注释方式非常简单，使用@brief后面填写类的概述，换行填写类的详细信息。命名空间、结构体、联合体、枚举定义与类定义注释方式一致。

/**
 * @brief 类的简单概述
 * 类的详细概述
 */

  例如：

/**
 * @brief 测试类
 * 主要用来演示Doxygen类的注释方式
 */

class Test{

};

  生成文档效果

2.4 常量/变量的注释

  常量/变量包括以下几种类型

• 全局常量变量
• 宏定义
• 类/结构体/联合体的成员变量
• 枚举类型的成员

  注释分为两种方式，可根据具体情况自行选择

1. 代码前注释

/// 注释
常量/变量

  例如：

/// 缓存大小
#define BUFSIZ 1024*4

  2. 代码后注释

常量/变量     ///< 注释

  例如：

#define BUFSIZ 1024*4     ///< 缓存大小

   生成文档效果

2.5 函数注释

  简约注释，函数注释主要包含返回值说明(@retval)三部分。可以根据需要添加详细说明(@detail)、注解(@note)、注意(@attention)、警告(@warning)或者异常(@exception)等。示例：

/**
 *  @brief   获取串口中断的状态
 *  @param  obj 要操作的串口对象
 *  @param  intStatus 要获取的串口中断的种类
 *  @retval  RESET = 0, SET = !RESET
 */

  生成文档效果

3. 效果展示

  生成的 .chm 帮助文档如下图所示，可以看到生成了各个文件的列表，函数调用关系举例如下下图所示。

  可以看到能够清晰的看出来函数之间的调用关系。