c代码Doxygen注释规范

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

1 Doxygen注释规范模板

1.1 文件注释模板

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

  若某项无相关的说明，中文写 无 ，英文写 None ，此时末尾不加标点，若有相关的说明，则建议正常使用标点符号，包括句末标点。

1.2 函数注释模板

1.2.1 完整格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/**
 * @fn 函数名
 * @brief 简述函数功能。
 * @details 关于函数更详细的细节补充描述。
 * @param[in] 参数名 参数注解。
 * - 值1 注解。
 * - 值2 注解。
 * @param[out] 参数名 参数注解。
 * @param[in, out] 参数名 参数注解。
 * @return 函数返回注解。
 * @retval 对返回值注解。
 * @see 扇入：调用了该函数的上级函数（扇入高表示该函数复用性好）。
 * @see 扇出：该函数里调用了哪些下级函数（扇出高表示该函数复杂度高）。
 * @note 其他注解。
 * @attention 注意事项。
 * @par example:
 * @code
 * //代码示例。
 * @endcode
 */

  若形参是 void 则写 @param void 即可。若返回值是 void 则写 @return void 且不需 @retval 项。

1.2.2 最简格式

1
2
3
4
5
6
7
8
9
10
11
/**
 * @fn 函数名。
 * @brief 简述函数功能。
 * @param[in] 参数名 参数注解。
 * - 值1 注解。
 * - 值2 注解。
 * @param[out] 参数名 参数注解。
 * @param[in, out] 参数名 参数注解。
 * @return 函数返回注解。
 * @retval 对返回值的说明
 */

1.3 宏函数注释模板

1.3.1 完整格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/**
 * @def 宏函数名。
 * @brief 简述函数功能。
 * @details 关于函数更详细的细节补充描述。
 * @param[in] 参数名 参数注解。
 * - 值1 注解。
 * - 值2 注解。
 * @param[out] 参数名 参数注解。
 * @param[in, out] 参数名 参数注解。
 * @return 函数返回注解。
 * @retval 对返回值的说明。
 * @see 扇入：调用了该函数的上级函数（扇入高表示该函数复用性好）。
 * @see 扇出：该函数里调用了哪些下级函数（扇出高表示该函数复杂度高）。
 * @note 其他注解。
 * @attention 注意事项。
 * @par example:
 * @code
 * //代码示例。
 * @endcode
 */

  若宏函数无参数则写 @param void ，若宏函数无返回值则写 @return void 。

1.3.2 最简格式

1
2
3
4
5
6
7
8
9
10
11
/**
 * @def 宏函数名。
 * @brief 简述宏函数功能。
 * @param[in] 参数名 参数注解。
 * - 值1 注解。
 * - 值2 注解。
 * @param[out] 参数名 参数注解。
 * @param[in, out] 参数名 参数注解。
 * @return 函数返回注解。
 * @retval 对返回值的说明。
 */

1.4 变量/宏定义注释模板

1
2
#define MAX                //!<最大值。
Byte g_byMax = 0;          //!<全局变量，最大值。

1.5 枚举注释模板

1.5.1 完整格式

1
2
3
4
5
6
7
/**
 * @enum 枚举名。
 * @brief 简介枚举用途。
 * @details 提示一些注意事项或必要的技术细节。
 * @note 其他注解。
 * @attention 注意事项。
 */

 &esmp;对枚举的每一个元素都应使用行注释 //!< 进行注解。

1.5.2 最简格式

1
2
3
4
/**
 * @enum 枚举名。
 * @brief 简介枚举用途。
 */

1.6 联合注释模板

1.6.1 完整格式

1
2
3
4
5
6
7
/**
 * @union 联合名。
 * @brief 简介联合用途。
 * @details 提示一些注意事项或必要的技术细节。
 * @note 其他注解。
 * @attention 注意事项。
 */

 &esmp;对联合的每一个元素都应使用行注释 //!< 进行注解。

1.6.2 最简格式

1
2
3
4
/**
 * @union 联合名。
 * @brief 简介联合用途。
 */

1.7 结构体注释模板

1.7.1 完整格式

1
2
3
4
5
6
7
/**
 * @struct 结构体名。
 * @brief 简介结构体用途。
 * @details 提示一些注意事项或必要的技术细节。
 * @note 其他注解。
 * @attention 注意事项。
 */

1.6.2 最简格式

1
2
3
4
/**
 * @struct 结构体名。
 * @brief 简介结构体用途。
 */

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