---

qtcreator-doxygen是Qt Creator的Doxygen插件，可以实现doxygen标准的注释。

源码下载地址：https://github.com/fpoussin/qtcreator-doxygen

插件下载地址：https://github.com/fpoussin/qtcreator-doxygen/releases

根据QT Creator的版本，选择相应版本的插件下载：

https://gitcode.com/gh_mirrors/qt/qtcreator-doxygen?utm_source=highuv_users_article_gitcode&index=top&type=card&

QtCreator Doxygen 插件常见问题解决方案

原文链接：https://blog.csdn.net/gitblog_01117/article/details/144877473

QtCreator Doxygen 插件是一个为 Qt Creator 集成开发环境（IDE）提供 Doxygen 文档生成支持的开源项目。该项目主要使用 C++ 编程语言开发。

常见问题及解决步骤

问题一：如何安装 QtCreator Doxygen 插件？

解决步骤：

下载 QtCreator Doxygen 插件的源码或预编译的二进制文件。
如果下载的是源码，需要先编译插件。编译前确保安装了与 Qt Creator 相同版本的 Qt 开发库。
编译插件时，需要设置 Qt Creator 的源代码路径和构建路径环境变量（QTC_SOURCE 和 QTC_BUILD）。
编译完成后，插件将自动安装到 Qt Creator 的插件目录中。
如果下载的是二进制文件，直接将其放入 Qt Creator 的插件目录中。
重启 Qt Creator，在“工具”菜单中应该能够找到 Doxygen 插件。

问题二：如何使用 QtCreator Doxygen 插件生成文档？

解决步骤：

确保插件已经正确安装并启用。
在 Qt Creator 中打开需要生成文档的项目。
通过“工具”菜单选择 Doxygen，然后选择“生成文档”。
在弹出的文件选择对话框中，选择需要生成文档的文件或整个项目。
配置 Doxygen 的参数，包括文档输出路径、文档格式等。
点击“确定”开始生成文档。

问题三：遇到编译错误，提示找不到 Qt Creator 的源代码或构建路径怎么办？

解决步骤：

确认 Qt Creator 的安装路径是否正确，以及是否与编译插件时使用的 Qt 版本相匹配。
检查 QTC_SOURCE 环境变量是否指向了 Qt Creator 的源代码目录。
检查 QTC_BUILD 环境变量是否指向了 Qt Creator 的构建目录。
如果使用的是预编译的 Qt Creator 版本，确保 QTC_SOURCE 指向的是 Qt Creator 的安装目录。
如果问题仍然存在，尝试重新下载 Qt Creator 的源代码或二进制文件，并确保版本匹配。
清理构建目录后，重新编译插件。

Chapter1 使用Doxygen实现代码自文档化

原文链接：https://blog.csdn.net/GrayD1419/article/details/117955456

一、Doxygen简介

1.1 综述

Doxygen是一个程序的文档产生工具，可以将程序中的注释转换成说明文档，后者API参考手册
要遵守一定的注释规范，才能被Doxygen识别和转化
在每个代码项中都可以有两类描述：brief描述 和 detailed描述；两种任选其一
若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释
头文件(.h 和 .hpp)：主要用于声明版权，描述本文件实现的功能，以及文件版本信息等
类的定义：主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述
类的成员定义：在类的成员变量上方，对该成员变量进行简要地描述
类的成员函数定义：在类定义的成员函数上方，对该成员函数功能进行简要描述
函数的实现在函数的实现代码处：详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等

1.2 常用指令

1.3 安装Doxygen

1. 下载地址
   Doxygen下载地址
   

2. 安装步骤
   
   

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查询手册
  

四、范例

4.1 项目描述

• 项目描述一般放在main函数文件中；若项目无入口函数，则置于较为关键，且不会被外部项目引用的文件内
• 包含的信息有：

1. 项目描述：基本信息(名称、作者)、版本信息
2. 功能描述
3. 用法描述
4. 注意事项
5. To do list(若有则添加)

• 可以使用html语法使用表格展示信息，换行、单元格/不必成对使用

/**@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.详细描述
  3.可以综合函数、枚举、结构体注释，对类员进行说明

4.6 其他

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

Chapter2 Qt中使用Doxygen注释生成总结

原文链接：https://blog.csdn.net/ljsant/article/details/116647334

Chapter3 QT Creator 如何使用 Doxygen 规范代码注释

原文链接：https://blog.csdn.net/hellokandy/article/details/104906513

Chapter4 Qt Creator Doxygen 插件下载及安装教程

原文链接：https://blog.csdn.net/gitblog_01279/article/details/143047738

1. 项目介绍

Qt Creator Doxygen 插件是一个为 Qt Creator 开发的插件，旨在帮助开发者更方便地使用 Doxygen 生成代码文档。该插件提供了文件选择对话框和重复块检测等功能，适用于最新的 Qt Creator 版本。

2. 项目下载位置

要下载 Qt Creator Doxygen 插件，请访问项目的 GitHub 仓库。你可以通过以下步骤进行下载：

打开终端或命令提示符。

使用 git clone 命令下载项目：

git clone https://github.com/fpoussin/qtcreator-doxygen.git

这将把项目克隆到你的本地机器上。

3. 项目安装环境配置

在安装 Qt Creator Doxygen 插件之前，你需要确保你的开发环境已经配置好。以下是必要的配置步骤：

3.1 安装 Qt 和 Qt Creator

确保你已经安装了与目标 Qt Creator 版本匹配的 Qt 版本。你可以在 Qt Creator 的“关于”菜单中查看当前使用的 Qt 版本。

3.2 安装编译工具

你需要安装编译工具，如 qmake 和 make。这些工具通常随 Qt 一起安装。

3.3 环境配置示例

以下是一个环境配置的示例：

# 安装 Qt 5.10
sudo apt-get install qt5-default
 
# 安装编译工具
sudo apt-get install build-essential

4. 项目安装方式

安装 Qt Creator Doxygen 插件有两种方式：使用 qmake 或使用 Qt Creator 的插件管理器。

4.1 使用 qmake 安装

1. 进入项目目录：

cd qtcreator-doxygen

2. 使用 qmake 配置项目：

qmake USE_USER_DESTDIR=yes QTC_SOURCE=~/src/qt-creator-opensource-src-4.5.0 QTC_BUILD=~/qtcreator-4.5.0

3. 编译项目：

make

4. 安装插件：

make install

4.2 使用 Qt Creator 插件管理器安装

1. 打开 Qt Creator。
2. 进入“工具” -> “选项” -> “插件”。
3. 点击“添加插件”，选择你编译好的插件文件。
4. 重启 Qt Creator 以加载新插件。

5. 项目处理脚本

在项目中，你可以使用以下脚本来处理插件的编译和安装：

#!/bin/bash
 
# 进入项目目录
cd qtcreator-doxygen
 
# 使用 qmake 配置项目
qmake USE_USER_DESTDIR=yes QTC_SOURCE=~/src/qt-creator-opensource-src-4.5.0 QTC_BUILD=~/qtcreator-4.5.0
 
# 编译项目
make
 
# 安装插件
make install

将上述脚本保存为 install_plugin.sh，然后在终端中运行：

bash install_plugin.sh

通过以上步骤，你就可以成功下载并安装 Qt Creator Doxygen 插件。

qtcreator-doxygen
Doxygen Plugin for Qt Creator
项目地址: https://gitcode.com/gh_mirrors/qt/qtcreator-doxygen

Chapter5 Qt Creator使用Doxygen

原文链接

Chapter6 【Doxygen】Doxygen使用配置及注释语法规范

原文链接：https://blog.csdn.net/Stay_Hun_forward/article/details/140873510

Doxygen使用配置及注释语法规范
程序的文件产生工具，可将程序中特定批注转换成为说明文件。

Doxygen的使用

• 特定格式的批注撰写
• 利用Doxygen的工具来产生文档

可处理的程序语言：C/C++、JAVA、IDL（Corda，Microsoft、KDE-DCOP类型）

可产生的文档格式：HTML、XML、LaTeX、RTF、Unix Man Page。

​ HTML可以打包成CHM格式，而LaTeX可以透过一些工具产生出PS或是PDF文档

产生文档的三个步骤：

1. 在程序代码中加上符合Doxygen所定义批注的格式
2. 使用Doxygen wizard进行配置。
3. 使用Doxygen来产生批注文档

Chapter7 超酷！！！成功使用doxygen+Graphviz+HtmlHelp 自动生成函数调用关系图

原文链接

打开Doxywizard 应用程序，按照下面的步骤一步步配置生成：

Chapter8 Doxygen 使用总结，生成chm文件，附：配置文件Doxyfile

原文链接：https://blog.csdn.net/qq_38977110/article/details/103464195

win系统下，doxygen软件下载和安装
doxygen-1.8.14-setup.exe

协调使用的软件下载和配置：
graphviz-2.38.msi——生成调用关系图

htmlhelp.exe——生成chm文件（可选）

1）htmlhelp下载：http://msdn.microsoft.com/en-us/library/ms669985.aspx
Doxygen自动生成chm，需下载HTML Help Workshop，我们将要使用当中的hcc.exe文件以及相关dll。
2）Graphviz下载：http://www.graphviz.org/download/
graphviz 是一个由AT&T实验室启动的开源工具包，用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图，如不需要此功能可不安装该工具包。

Chapter9 【Doxygen 注释】深入探讨：Doxygen中的C++专有注释格式

原文链接：https://blog.csdn.net/qq_21438461/article/details/141194678

第1章：引言

1.1 Doxygen的重要性

在软件开发的世界里，文档是理解、使用和维护代码的关键。对于C++这样复杂的编程语言，有效的文档尤为重要。Doxygen 是一个广泛使用的文档生成工具，它可以从标记的源代码注释中自动创建高质量的文档。这不仅有助于开发团队内部的知识共享，还可以提升外部开发者对代码库的理解。

1.2 C++中文档的特殊挑战

C++是一种支持多范式的编程语言，其复杂性来源于其支持的多种编程风格和高级特性，如类、模板、多态、重载和异常处理。每一种特性都需要在文档中准确地表达，以确保代码的可读性和可维护性。在这种情况下，普通的注释方法可能不足以满足需求，而Doxygen提供的高级注释标签可以帮助开发者克服这些挑战。

1.3 为什么专门针对C++的Doxygen注释格式特别重要

针对C++的高级特性进行有效的文档化，可以显著提高代码库的可访问性和可理解性。Doxygen支持的专门标签允许开发者详细描述类层次结构、模板行为、接口和多态关系，以及异常处理，这些都是C++项目成功的关键。通过这些工具，Doxygen不仅能够生成文本文档，还能生成直观的关系图，这些图表能够清晰地展示类之间的继承关系和相互协作，从而进一步增强文档的效用。

通过这个引言，我们为读者建立了对Doxygen在C++项目中应用的背景和重要性的基本理解。接下来的章节将详细介绍具体的注释格式，并展示它们如何帮助生成丰富、有结构的HTML文档，以及这些文档如何帮助开发者和用户更好地理解和使用C++代码。

第2章：C++专有的Doxygen注释格式

2.1 @class 和 @interface

在C++中，类是构建数据和功能模块的基本单位。Doxygen提供了专门的注释标签@class和@interface，以便开发者能够详细描述类或接口的用途、设计和功能。

2.1.1 @class

@class标签用于文档化C++中的类定义。它不仅帮助生成类的详细文档，还包括成员变量、成员函数、继承关系和友元关系的说明。使用@class标签时，开发者可以在类的声明前添加详细的描述，包括类的职责、使用方式和与其他类的交互。

示例：

/**
 * @class MyClass
 * @brief A demonstration of a C++ class documented using Doxygen.
 *
 * MyClass performs operations X, Y, and Z. It is designed to be lightweight
 * and efficient, suitable for scenarios requiring high performance.
 *
 * @see AnotherClass
 * @note Make sure to call initialize() before using any other methods.
 */
class MyClass {
public:
    /**
     * @brief Initializes the MyClass object.
     * @return true if initialization is successful, false otherwise.
     */
    bool initialize();

    /**
     * @brief Performs operation X.
     */
    void operationX();
private:
    int data; /**< Detail of what data represents. */
};

在生成的HTML文档中，MyClass会有自己的页面，详细列出所有公开和私有成员，方法描述，以及任何特别的注意事项或相关的类。

2.1.2 @interface

虽然C++标准中没有"interface"关键字，@interface标签可以用来描述充当接口的抽象类。这对于描述那些主要用于定义接口而不包含实现的类特别有用。Doxygen将处理这些抽象类，并在文档中清楚地标记它们作为接口。

示例：

/**
 * @interface IProcessor
 * @brief Interface for processor classes.
 *
 * This interface defines the standard operations for processors,
 * ensuring that all derived classes implement these operations.
 */
class IProcessor {
public:
    /**
     * @brief Process data.
     * @param data Data to be processed.
     * @return Processed data output.
     */
    virtual std::string process(std::string data) = 0;
};

在生成的HTML中，IProcessor会被标识为一个接口，并且会列出所有需要由子类实现的纯虚函数。这有助于开发者理解哪些功能是由接口定义的，必须由任何实现该接口的类来提供。

通过这样的注释，Doxygen 能够为C++中的类和接口生成清晰、详尽的文档，这对于理解复杂的类层次结构和接口关系至关重要。这些文档不仅为开发者提供了一个详细的功能参考，还通过直观的类和接口关系图增强了整体的可理解性。

2.2 @public, @protected, @private

在C++中，访问控制关键字public, protected, 和private定义了类成员的可访问性。Doxygen通过使用相应的标签@public, @protected, 和@private，允许开发者在文档中明确标识成员变量和函数的访问级别。这些标签有助于在生成的文档中清晰地展示类的封装细节，从而使代码更易于理解和维护。

2.2.1 使用场景和重要性

访问控制是面向对象编程中封装概念的核心部分。正确的访问级别不仅保护了数据的完整性，还确保了类的接口与实现之间的分离。在Doxygen中显式标记这些访问级别，有助于开发者快速理解类的结构，尤其是在处理大型类或复杂继承结构时。

示例：

/**
 * @class Account
 * @brief A class to represent a bank account.
 *
 * This class provides functions to deposit, withdraw, and track the balance of a bank account.
 */
class Account {
public:
    /**
     * @brief Deposits an amount to the account.
     * @param amount The amount to deposit.
     */
    void deposit(double amount);

protected:
    /**
     * @brief Calculates the interest on the current balance.
     * @return The amount of interest.
     */
    double calculateInterest();

private:
    double balance; /**< @private Store the balance of the account. */
};