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}) | 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