c代码Doxygen注释规范

c代码Doxygen注释规范

---

前言：良好得注释风格利于后期维护和团队协作开发，使得代码逻辑清晰，意图明了。Doxygen是一种能自动提取代码内注释生成版主文档的开源软件，它是跨平台的。非开源项目也许并不需要有这样一份帮助文档，但Doxygen的注释规范也不失为一种好的风格，可以推广遵守。

Doxygen注释规范模板

文件注释模板

/**
  * @file 文件名（*.h/*.c）
  * @brief 该模块功能的简介。
  * @details 使用该模块有哪些细节注意等。
  * @author 创建该文件的人名。
  * @data 该文件的创建日期（2020-03-10）。
  * @version 文件当前的版本号（V1.0.0）。
  * @copyright 版权所属公司。
  */

函数注释模板

/**
  * @fn 函数名
  * @brief 简述函数功能。
  * @details 提示一些注意事项或必要的技术细节。
  * @param[in] 参数名 参数注解
  * @param[out] 参数名 参数注解
  * @param[in, out] 参数名 参数注解
  * @return None （宏函数无返回值）
  * @retval 对返回值的说明
  * @see 扇入：调用了该函数的上级函数（扇入高表示该函数复用性好）
  * @see 扇出：该函数里调用了哪些下级函数（扇出高表示该函数复杂度高）
  * @note 注解。
  * @attention 注意事项。
  * @par example:
  * @code
  //代码示例
  * @endcode
  */

宏函数注释模板

/**
  * @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;          //!< 全局变量，最大值

枚举注释模板

/**
  * @enum 枚举名
  * @brief 简介枚举用途。
  * @details 提示一些注意事项或必要的技术细节。
  * @note 注解。
  * @attention 注意事项。
  */

个人建议将枚举值也定义为宏

联合注释模板

/**
  * @union 联合名
  * @brief 简介联合用途。
  * @details 提示一些注意事项或必要的技术细节。
  * @note 注解。
  * @attention 注意事项。
  */

个人建议将联合按8Bit进行位划分

结构体注释模板

/**
  * @struct 结构体名
  * @brief 简介结构体用途。
  * @details 提示一些注意事项或必要的技术细节。
  * @note 注解。
  * @attention 注意事项。
  */

遵循以上注释风格将会使你的代码更加规范，可读性增强。对于团队开发来说有一个统一的规范标准也使得协作变得简单。