doxygen注释规范

浅写写代码注释规范

基本格式

docxygen给定了一种对文档、函数等注释的基本格式，便于开发者和使用者更好地交代和理解模块、功能等的必要信息。
下面给出的模板中的关键字并不是固定的，需要哪个就写哪个。

头文件注释模板

/**
  * @brief 摘要
  * @file 文件名
  * @author 作者
  * @version 版本
  * @date 文件日期
  * @note 注释
  * @since 从什么时候开始有这个东西的
  */

函数注释模板

/**
  * @brief 功能
  * @param args 解释参数
  * @param argv 解释参数
  * @return 返回值意义
  * @retval 1 成功
  * @retval 0 失败
  * @retval -1 异常
  * @warning 警告
  * @see 例如参考xxx函数
  * @note 注释
  */

常见关键字

• author 作者信息
• brief 对函数、模块等（其作用和功能的）简易说明
• pre 使用代码项的前提条件
• post 使用代码项之后的条件
• param 函数参数说明
• enum 引用了某个枚举
  • @enum LCD::LCD_Color
• var 引用了某个变量
  • @var LCD::LCD_Buffer
• class 引用了某个类
  • @class Texture “inc/texture.h”
• return 返回值情况
  • @return 若成功则返回true，否则返回false
• retval 返回值类型
  • @retval NULL 空数组
  • @retval !NULL 非空数组
• note 注解，比如对@brief的更进一步说明
• todo 就是todo
• attention 注意事项
• warning 警告信息
• exception 可能产生的异常
• bug bug
• code 在注释中开始说明一段代码，直到@endcode为止
• endcode 注释中的代码段的结束
• par 开始一个段落，例如写一段演示代码
• file 文件名，doxygen能自动添加
• date 日期
• since 从哪个版本之后开始有这个模块、文件、函数……
• deprecated 该模块、文件、函数可能在未来的版本中取消
• name 分组名

参考文献

doxygen 注释规范_Doxygen的注释规则

Doxygen 使用说明