其他分享
首页 > 其他分享> > 使用Doxygen实现代码自文档化

使用Doxygen实现代码自文档化

作者:互联网

参考链接

一、Doxygen简介

1.1 综述

  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下载地址

Doxygen下载地址

2. 安装步骤

  1. 同意安装条约,选择安装路径
  2. 完全安装
选择Full Installation出现Doxygen,安装成功
  1. 逐步确认,直到安装成功

二、注释规范

2.1 官方例程

2.2 参考例程

Doxygen注释规范

2.3 使用插件自动创建

1. 下载插件

qtcreator-doxygen

2. 安装插件

三、生成注释文档

1. 打开DoxyWizard

2. 创建文档

3. 浏览生成的文档

打开index.html浏览文档

四、范例

4.1 项目描述

/**@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 文件说明

/**@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 函数注释

/**@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 类注释

4.6 其他

标签:Doxygen,函数,代码,注释,文档,返回值,NB,描述
来源: https://blog.csdn.net/GrayD1419/article/details/117955456