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

大家好，欢迎来到IT知识分享网。

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来产生批注文档

Doxygen使用配置

使用Doxygen的GUI版本进行配置（Doxygen GUI frontend）

·Wizard -> Project

工作目录：存放配置文件的目录。

Project name：工程名字，项目名称。

Source code directory: 源码目录。

scan recursivery选项：是否支持递归搜索文件目录。需要勾选

Destionation directory：生成文档的存放目录。

·Wizard -> Mode

• 选择期望的提取模式

​ 仅文件实体

​ 所有实体

​ 在输出文档中包含交叉引用的源代码

• 选择编程语言去优化输出的结果

  这里支持C++

  C++/CLI

  Java或者C#

  C或者PHP

  等等

• 如果使用纯C语言编写的话，选择Optimize for C or PHP output 选项

·Wizard -> Output

• 选择生成的输出格式

​ HTML

​ 选择生成.chm格式的文档（compressed HTML）

​ LaTeX

​ as intermediate format for hyperlinked PDF:作为超链接PDF的中间格式

• Wizard -> Diagrams

• 选择生成图表的方式

  使用GraphViz Package的点工具生成图表

  （如果选择这个选项之前需要先安装了 Graphviz 工具包）

·Expert -> project

选择其输出文档的编码格式：UTF8 中文GB2312

设置输出文件的路径

设置输出文档的语言：如果有中文注释需要选择Chinese

向下拉滑动条看到JAVA_AUTOBRIEF和QT_AUTOBRIEF勾选上。

如果勾选就会默认第一行为简单说明，不勾选则需要@brief

·Expert -> Build

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 ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

·Expert -> Input

INPUT_ENCODING:设置输入源码的编码格式，要与输入的源文件的编码格式相同，（代码文件也有自己的编码方式）

·Expert -> HTML

GENERATE_HTML_HELP:勾选

CHM_FILE:生成的CHM_FILE 表示最终生成的文件名要以.chm为后缀

HHC_LOCATION：如果在 Wizard 的 Output Topics 中选择了 prepare for compressed HTML (.chm)选项，此处就会要求选择 hhc.exe 程序的位置。在 windows help workshop 安装目录下可以找到 hhc.exe。

CHM_INDEX_ENCODING：选择输出chm的编码。

为了解决DoxyGen生成的CHM文件的左边树目录的中文变成了乱码，CHM_INDEX_ENCODING中输入GB2312即可。

TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。

·Expert -> Dot

设置DOT_IMAGE_FORMAT 图片的格式，

在DOT_PATH下面填入dot.exe的路径。

设置Run

生成之后可以去 生成目标目录的路径/html/*.chm 的文件就是生成的api文档了

Doxygen注释语法

Doxygen常用注释命令

@exception <exception-object> { 
   exception description} 对一个异常对象进行注释。 @warning { 
   warning message } 一些需要注意的事情 @todo { 
    things to be done } 对将要做的事情进行注释，链接到所有TODO 汇总的TODO 列表 @bug 缺陷，链接到所有缺陷汇总的缺陷列表 @see { 
   comment with reference to other items } 一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。 @relates <name> 通常用做把非成员函数的注释文档包含在类的说明文档中。 @since { 
   text} 通常用来说明从什么版本、时间写此部分代码。 @deprecated @pre { 
    description of the precondition } 用来说明代码项的前提条件。 @post { 
    description of the postcondition } 用来说明代码项之后的使用条件。 @code 在注释中开始说明一段代码，直到@endcode命令。 @endcode 注释中代码段的结束。 @code .. @endcode 包含一段代码 @addtogroup 添加到一个组。 @brief 概要信息 @deprecated 已废弃函数 @details 详细描述 @note 开始一个段落，用来描述一些注意事项 @par 开始一个段落，段落名称描述由你自己指定 @param 标记一个参数的意义 @fn 函数说明 @ingroup 加入到一个组 @return 描述返回意义 @retval 描述返回值意义 @include 包含文件 @var、@enum、@struct、@class 对变量、美剧、结构体、类等进行标注 

注释示例

项目注释

项目注释块用于对项目进行描述，每个项目只出现一次，一般可以放在main.c主函数文件头部。对于其它类型的项目，置于定义项目入口函数的文件中。对于无入口函数的项目，比如静态库项目，置于较关键且不会被外部项目引用的文件中。

文件注释

文件注释块对源代码文件进行注释，包括头文件（.h）、C++文件（.cpp）或C文件（*.c）。文件注释块置于对应文件的开头，至少包括文件名（@file）、文件简要说明（@brief）、作者（@author）、创建日期（@date）和版本号（@version）5个标记。如下所示：

/@file main.c * @brief 项目主函数文件 * @details 主要包含协议应用栈程序框架，main函数入口 * @author 李长条 * @date 2018-8-17 * @version V1.0 * @copyright Copyright (c) 2050 * @attention * SDK版本：v2050.0.0 * @par 修改日志: * <table> * <tr><th>Date <th>Version <th>Author <th>Description * <tr><td>2010/02/17 <td>1.0 <td>wanghuan <td>创建初始版本 * </table> * */ 

/ * @file 文件名（*.h/*.c） * @brief 该模块功能的简介。 * @details 使用该模块有哪些细节注意等。 * @author 创建该文件的人名。 * @data 该文件的创建日期（2020-03-10）。 * @version 文件当前的版本号（V1.0.0）。 * @copyright 版权所属公司。 */ 

函数注释

注释块对函数进行描述，位于对应函数的定义上方。

函数注释块包含以下内容：

• 简要说明标记（@brief），内容为方法 / 函数的简要说明。
• 详细描述，详细描述与@brief标记之间空一行”\n”或者使用@details。
• 若干个参数描述标记（@param），数量与该方法的输入参数个数相同。格式为：“@param 参数名称 参数说明”。
• 返回值标记（@return），描述该方法的返回值，格式为：“@return 返回值类型 返回值描述”。若返回值为void类型，则省略该标记。
• 返回值说明（@retval），对具体返回值进行描述说明。
• 特殊标记

函数注释块示例，实际根据情况增减：

/@brief 注册函数 * @param[in] *data 上报数据指针 * @param[in] len 上报数据长度 * @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 * int ret = register_all(&data, len, RT_TYPE_T1) * @endcode * @see :: xx表 */ 

/ * @fn 函数名 * @brief 简述函数功能。 * @details 提示一些注意事项或必要的技术细节。 * @param[in] 参数名 参数注解 * @param[out] 参数名 参数注解 * @param[in, out] 参数名 参数注解 * @return None （宏函数无返回值） * @retval 对返回值的说明 * @see 扇入：调用了该函数的上级函数（扇入高表示该函数复用性好） * @see 扇出：该函数里调用了哪些下级函数（扇出高表示该函数复杂度高） * @note 注解。 * @attention 注意事项。 * @par example: * @code //代码示例 * @endcode */ 

枚举、结构体等注释模板

/@enum msg_types * @brief 定义驱动上报应用消息类型 */ /@struct info * @brief 信息结构体 \n * 定义存储的信息 */ typedef struct 结构体名字 { 
    成员1, ///< 简要说明文字 */ 如果不加<，则会认为是成员2的注释 成员2, ///< 简要说明文字  成员3, ///< 简要说明文字  }结构体别名； 

/ * @enum 枚举名 * @brief 简介枚举用途。 * @details 提示一些注意事项或必要的技术细节。 * @note 注解。 * @attention 注意事项。 */ 

宏函数注释模板

/ * @def 宏函数名 * @brief 简述函数功能。 * @details 提示一些注意事项或必要的技术细节。 * @param[in] 参数名 参数注解 * @param[out] 参数名 参数注解 * @param[in, out] 参数名 参数注解 * @return None （宏函数无返回值） * @see 扇入：调用了该函数的上级函数（扇入高表示该函数复用性好） * @see 扇出：该函数里调用了哪些下级函数（扇出高表示该函数复杂度高） * @note 注解。 * @attention 注意事项。 * @par example: * @code //代码示例 * @endcode */ 

变量/宏定义注释模板

#define MAX //!< 最大值 Byte g_byMax = 0; //!< 全局变量，最大值 

VS code 配置自动生成Doxygen格式注释

ENV：

• VScode
• Generate Doxygen Comments 插件

插件安装完成后，File – Preference – Settings – 中打开用户 setting.json文件