Doxygen 是一种广泛使用的文档生成工具，它允许开发者通过遵循特定的注释规范来提取文档。编写注释时，遵循 Doxygen 的语法规则至关重要，因为这样不仅可以生成格式统一、易于导航的文档，还能提高文档的可读性和专业性。如果注释不符合 Doxygen 的标准格式，生成的文档可能会显得杂乱无章，难以为其他开发者或用户所理解。

特殊命令简介

命令 字段名 语法
@file 文件名 file [< name >]
@brief 简介 brief { brief description }
@author 作者 author { list of authors }
@mainpage 主页信息 mainpage [(title)]
@date 年-月-日 date { date description }
@author 版本号 version { version number }
@copyright 版权 copyright { copyright description }
@param 参数 param [(dir)] < parameter-name> { parameter description }
@return 返回 return { description of the return value }
@retval 返回值 retval { description }
@bug 漏洞 bug { bug description }
@details 细节 details { detailed description }
@pre 前提条件 pre { description of the precondition }
@see 参考 see { references }
@link 连接(与 @see 类库，{@link www.google.com&#125;) link < link-object>
@throw 异常描述 throw < exception-object> { exception description }
@todo 待处理 todo { paragraph describing what is to be done }
@warning 警告信息 warning { warning message }
@deprecated 弃用说明。可用于描述替代方案，预期寿命等 deprecated { description }
@example 弃用说明。可用于描述替代方案，预期寿命等 deprecated { description }

文件注释

一般放在文件开头

/**
 * @file 文件名
 * @brief 简介
 * @details 细节
 * @author 作者
 * @version 版本号
 * @date 年-月-日
 * @copyright 版权
 */

结构体注释

 /**
  * @brief 类的详细描述
  */

函数注释

 /**
  * @brief 函数描述
  * @param 参数描述
  * @return 返回描述
  * @retval 返回值描述
  */

常量/变量注释

一般常量/变量可以有两种形式：

  • 常量/变量上一行注释
  • 常量/变量后注释
//定义一个整型变量a
int a;

/**
 * @brief 定义一个整型变量a
 */
int a;
int a; /*!< 定义一个整型变量a */
int a; /**< 定义一个整型变量a */
int a; //!< 定义一个整型变量a
int a; ///< 定义一个整型变量a