doxygen常用代码注释标记示例说明

类、结构体

类和结构体的描述必须包含“所属类别（group）”以及“显示表示简要描述（brief）”

说明：

隐式区分简要描述和详细描述：
默认会先判断第一行为简易说明,这个简易说明将一直到遇见一个空白行的出现为止; 之后的注解将会被视为详细说明。

显式区分简要描述和详细描述：
指定@brief 的指令,这将会明确的告诉 Doxygen 哪个是简易说明，然后用空行当作段分隔符号，后面进行详细描述。

说明：
1.<p>有换行效果
2.连续写两行，中间没有类似于<p>的标识，输出会默认是一行。

公有函数、全局函数

通用注释格式：


扩展注释格式：

枚举

使用示例一：


说明：
1.如果是注释下一行的代码，可用/** ...单行注释... */
2.如果是注释同一行的代码，可用/**< ...代码同行情况的注释 */

使用示例二：


说明：
1.如果是注释下一行的代码，可用/// 单行注释
2.如果是注释同一行的代码，可用///< 代码同行情况的注释

错误示例一：


说明：
1.在doxygen 里面 采用的 // 注释格式，是生不成文档的。

公有成员变量、全局常量

枚举中已使用相应方法，在此不在赘述。

常见问题

如何在注释文件中添加表格

tr 表示当前行
th 表示表头
td 表示内容

如何在注释中分条列举

如何给描述内容分段

通过<p>和 空行达到的效果一样，都将会被当作段分隔符号。

示例一：

示例二：

Doxygen 常用的代码注释标记介绍

1.文件信息
@file 文件名(遵守文件命名规则) --> 文件声明，即当前文件名
@author 作者名 --> 作者
@version 版本号 --> 版本号
@todo 说明文字 --> TODO 列表，在相关页面有它专门一项
注:只能在实现文件(.c/.cpp)中使用，如果相同函数的实现文件与头文件中均有，生成的文档中会有重复项，可以理解为调用者不应知道实现流程
@date 日期时间 --> 说明文件生成的日期时间
@section 章节标题 --> @section LICENSE 版权许可 @section DESCRIPTION 描述
2.模块信息
@defgroup 模块名(英文) 显示名(中文) @{ 类/函数/变量/宏/... @}--> 定义模块
@ingroup 模块名(英文) [显示名(中文)]--> 作为指定名的模块的子模块,显示名为可选项,可与指定名的模块的显示名不同
@addtogroup 模块名(英文) [显示名(中文)] --> 作为指定名的模块的成员,显示名为可选项,必需与指定名的模块的显示名相同
@name 显示名(中文) @{ 变量/宏 @} --> 按用途分,以便理解全局变量/宏的用途
这部分推荐参考： doxygen使用总结
3.函数信息
@param 参数名 说明文字 --> 不建议使用这个
@param[in] 参数名 说明文字 --> 输入参数
@param[out] 参数名 说明文字 --> 输出参数
@param[in,out] 参数名 说明文字 --> 即输入又输出参数
@exception 用来说明异常类及抛出条件
@remark 表示评论，暴露给客户程序员的文档
@return 说明文字 --> 返回值说明
@retval 说明文字 --> 特定返回值说明
@note 说明文字 --> 注解,可以描述工作流程和注意事项
@par [段落标题] --> 开创新段落,一般与示例代码联用
@code --> 示例代码开始
@endcode --> 示例代码结束
@see 类/函数/变量/文件/URL --> 参见,
　 类名::函数名 或 ::函数名 可以变成超链接点击跳转到对应函数说明处
　 函数重载的情况下,要带上参数列表以及返回值
@deprecated 说明文字 --> 过时列表,在相关页面有它专门一项
　 注:只能在头文件(*.h)中使用,如果相同函数的实现文件与头文件中均有,
　 　 生成的文档中会有重复项,可以理解为维护者不关心这个接口是不是要过时
@pre 说明文字 --> 前置条件
@arg 参数/返回值 说明文字 --> 以列表形式说明参数取值意义
注:也可以用 - 或 -# 来代替,建议此种方法,简单明了
　- 第一级
　　- 第二级
　　　- 第三级
　　即相同开头的-或 -#第二行比第一行缩进一个英文空格就变了第二级,依次类推
　　- 开头的第一级为实心黑圆点;第二级为空心黑圆点;第三级以后为实心方块;
　　-#开头的第一级为数字(1./2./3./...),
　　第二级为小写字母(a./b./c./...),
　　第三级为罗马数字(i./ii./iii./...),
　　第四级为大写字母(A./B./C./...)
4.提醒信息
@brief 说明文字 --> 摘要,即当前文件/函数说明
@attention 说明文字 --> 注意
@bug 说明文字 --> 问题
@warning 说明文字 --> 警告
@ref 引用其他标记，类似于html中的锚　
@since {text} 通常用来说明从什么版本、时间写此部分代码
@relates 通常用做把非成员函数的注释文档包含在类的说明文档中
@def 宏定义说明
@fn 函数 函数说明
@test 测试示例、信息
(@bug、@test以及@todo等会出现链接页面)