使用Doxygen实现代码自文档化

参考链接

一、Doxygen简介

1.1 综述

• Doxygen是一个程序的文档产生工具，可以将程序中的注释转换成说明文档，后者API参考手册
• 要遵守一定的注释规范，才能被Doxygen识别和转化
• 在每个代码项中都可以有两类描述：brief描述 和 detailed描述；两种任选其一
• 若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释

1. 头文件(.h 和 .hpp)：主要用于声明版权，描述本文件实现的功能，以及文件版本信息等
2. 类的定义：主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述
3. 类的成员定义：在类的成员变量上方，对该成员变量进行简要地描述
4. 类的成员函数定义：在类定义的成员函数上方，对该成员函数功能进行简要描述
5. 函数的实现在函数的实现代码处：详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等

1.2 常用指令

@file	档案的批注说明。
@author	作者的信息
@brief	用于class 或function的简易说明; eg：@brief ``本函数负责打印错误信息串
@param	主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
@return	描述该函数的返回值情况; eg:@return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
@retval	描述返回值类型; eg:@retval NULL ``空字符串。 @retval !NULL ``非空字符串。
@note	注解
@attention	注意
@warning	警告信息
@enum	引用了某个枚举，Doxygen会在该枚举处产生一个链接; eg：@enum CTest::MyEnum
@var	引用了某个变量，Doxygen会在该枚举处产生一个链接; eg：@var CTest::m_FileKey
@class	引用某个类，格式：@class [] []; eg:@class CTest “inc/class.h”
@exception	可能产生的异常描述; eg:@exception 本函数执行可能会产生超出范围的异常

1.3 安装Doxygen

1. 下载地址

Doxygen下载地址

2. 安装步骤

1. 同意安装条约，选择安装路径
2. 完全安装

选择Full Installation	出现Doxygen，安装成功

3. 逐步确认，直到安装成功

二、注释规范

2.1 官方例程

• 切换到安装目录下的examples文件夹
  • *.h中有对应语法的注释规范
  • *.cfg为配置文件
    

2.2 参考例程

Doxygen注释规范

2.3 使用插件自动创建

1. 下载插件

• 选择对应的QtCreator版本，下载插件
• 【TIPS】下载32位！64位异常，无法使用

qtcreator-doxygen

2. 安装插件

• 切换到Qt安装路径–Tools–QtCreator–lib–qtcreator–plugins
• 将下载的dll保存到该路径下
• 重启QtCreator，帮助–关于插件，搜索Doxygen，选择
• 在工具中出现Doxygen选项
• 选择前三项，生成对应的注释格式
• 添加注释内容

三、生成注释文档

1. 打开DoxyWizard

2. 创建文档

• 生成.chm文档需要辅助软件；可以使用默认配置plain HTML

3. 浏览生成的文档

• 通过文档存放目录–html–index.html查询手册

打开index.html	浏览文档

四、范例

4.1 项目描述

• 项目描述一般放在main函数文件中；若项目无入口函数，则置于较为关键，且不会被外部项目引用的文件内
• 包含的信息有：
  1. 项目描述：基本信息(名称、作者)、版本信息
  2. 功能描述
  3. 用法描述
  4. 注意事项
  5. To do list(若有则添加)
• 可以使用html语法使用表格展示信息，换行<tr>、单元格<th>/<td>不必成对使用

/**@mainpage  NavButton
 *
 * <table>
 *  <tr><th>Project  <td>NavButton
 *  <tr><th>Author   <td>BangZG
 *  <tr><th>Source   <td>/home/xxx/Documents/NavButton
 * </table>
 *
 * @section   项目详细描述
 * 自定义导航栏按钮
 *
 * @section   功能描述
 * -# 可设置文字的左侧+右侧+顶部+底部间隔
 * -# 可设置文字对齐方式
 * -# 可设置显示倒三角/倒三角边长/倒三角位置/倒三角颜色
 * -# 可设置显示图标/图标间隔/图标尺寸/正常状态图标/悬停状态图标/选中状态图标
 * -# 可设置显示边框线条/线条宽度/线条间隔/线条位置/线条颜色
 * -# 可设置正常背景颜色/悬停背景颜色/选中背景颜色
 * -# 可设置正常文字颜色/悬停文字颜色/选中文字颜色
 * -# 可设置背景颜色为画刷颜色
 *
 * @section   用法描述
 * @code
 *  // NavButton 继承自QPushButton,
 *  NavButton *btn = new NavButton;
 *  btn->show();
 * @endcode
 *
 * @section   版本信息
 * <table>
 * <tr>
 *  <th>Date
 *  <th>Tag
 *  <th>Version
 *  <th>Author
 *  <th>Description
 *</tr>
 *<tr>
 * <td>2021/05/10
 * <td>1.0
 * <td>S02010041808171
 * <td>BangZG
 * <td>创建初始版本
 *</tr>
 *<tr>
 *  <td>2021/06/16
 *  <td>1.3
 *  <td>S02010041906241
 *  <td>BangZG
 *  <td>完整版本
 * </tr>
 * </table>
 *
 * @todo 配合测试...
 ***********************************************************************************/

效果预览

4.2 文件说明

• 文件描述至少包含：
  1. 文件名
  2. 文件简要说明
  3. 作者
  4. 创建日期
  5. 版本号

/**@file  main.cpp
 * @brief   项目主函数文件
 * @details 启动UI主线程，main函数入口
 * @author  BangZG  any question please send mail to xxx@qq.com
 * @date    2021-6-15
 * @version V1.3
 **********************************************************************************
 * @attention
 * 软件平台:windows \n
 * Qt版本: Qt5.14.2
 * @par 修改日志:
 * <table>
 * <tr><th>Date        <th>Version  <th>Author  <th>Description
 * <tr><td>2021/05/10  <td>1.0      <td>BangZG  <td>创建初始版本
 * </table>
 **********************************************************************************
 */

效果预览

4.3 函数注释

• 函数注释主要包含以下内容：
  1. 简要说明
  2. 详细描述：详细描述与@brief标记之间空一行”\n”或者使用@details。
  3. 参数描述：格式为 @param[in|out] 参数名称 参数说明
  4. 返回值标记：描述该方法的返回值，格式为：“@return 返回值类型 返回值描述”；若返回值为void类型，则省略该标记
  5. 返回值说明：@retval，对具体返回值进行描述说明

/**@brief NB模组向云平台上报数据
*
* @param[in]  handle              NB模组驱动句柄
* @param[in]  *data                上报数据指针
* @param[in]  len                上报数据长度
* @param[in]  rcc_enabled          上报时是否主动释放RCC链接
* @param[in]  update_enabled    上报时是否更新注册(只适用于onenet)
* @param[in]  report_fail_try_type    上报失败重新注册类型 \n
* @ref NB_REPFAIL_REG_TRY 出错立即重试    \n
* @ref NB_REPFAIL_REG_DELAY_TRY 出错延缓重试，在延迟期间如果正常则重新延缓，适用于高频率上报（上报失败重新注册超时15min） \n
* @ref NB_REPFAIL_REG_NO_TRY 出错不重试
*
* @return  函数执行结果
* - NB_NOTIFY_SUCCESS	 上报成功
* - NB_NOTIFY_FAIL       上报失败
* - NB_IOT_REGIST_FAILED 注册失败返回
* - Others  其他错误
*
* @par 示例:
* @code
*    移动平台发送数据 AT+MIPLNOTIFY=0,122553,3308,0,5900,4,4,50,0,0
*    电信平台发送数据 AT+M2MCLISEND=000101
* @endcode
*
* @see :: ME3616_FxnTable
*/
static uint8_t me3616_notify(NB_Handle handle, uint8_t* data, uint16_t len, uint8_t rcc_enabled, uint8_t update_enabled, uint8_t report_fail_try_type);

效果预览

4.4 枚举、结构体注释

• 主要对成员进行描述说明

/**
 * @brief The String struct
 * 通用String的实现
 */
struct String {
    char *data;  /**< 字符内容 */
    int   count; /**< 字符长度 */
};


/**@enum LinePosition
 * @brief 线条所在位置类型
 */
enum LinePosition {
    LinePosition_Left   = 0, /**< 左侧 */
    LinePosition_Right  = 1, /**< 右侧 */
    LinePosition_Top    = 2, /**< 顶部 */
    LinePosition_Bottom = 3  /**< 底部 */
};

结构体	枚举

4.5 类注释

• 类注释内容包含：
  1. 简要说明
  2. 详细描述
• 可以综合函数、枚举、结构体注释，对类员进行说明

4.6 其他

• 其他可暂不考虑，目前以上述内容为主