Doxygen使用配置及注释语法规范
程序的文件产生工具，可将程序中特定批注转换成为说明文件。
Doxygen的使用
- 特定格式的批注撰写
- 利用Doxygen的工具来产生文档
可处理的程序语言：C/C++、JAVA、IDL（Corda，Microsoft、KDE-DCOP类型）
可产生的文档格式：HTML、XML、LaTeX、RTF、Unix Man Page。
HTML可以打包成CHM格式，而LaTeX可以透过一些工具产生出PS或是PDF文档
产生文档的三个步骤：
- 在程序代码中加上符合Doxygen所定义批注的格式
- 使用Doxygen wizard进行配置。
- 使用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的中间格式
-
选择生成图表的方式
使用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 插件
6800
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
