看懂源码之注释规范

1.前言

为了增强源代码的可阅读性、结构性，方便代码阅读者对源代码的阅读和理解，以及方便源代码文档的制作和生成，源代码的注释通常按一定的规范编写。
所以要想更好的读懂源码，就必须对注释规范有一定的了解。

2.注释详解

2.1 定义注释块

/*!
 * 一个注释块
 */

2.2 文件注释块

/*!
 * @file 文件名
 * @brief 文件简要说明
 * @author 作者
 * @date 时间
 * @version 版本
 */

2.3 类注释块

/*!

 * @class 类名
 * @brief 类简要说明
 * 
 * 详细描述
 */

2.4 类成员方法、数注释标记

• 简要说明标记（@brief），内容为方法 / 函数的简要说明。
• 详细描述，详细描述与@brief标记之间空一行
• 若干个参数描述标记（@param），数量与该方法的输入参数个数相同。格式为：“@param 参数名称 参数说明”。
• 异常描述标记（@exception），对该方法抛出的异常进行描述，可省略。
• 警告标记（@warning），对调用方法需要注意的地方进行描述，可省略
• 前置条件标记（@pre），描述执行方法的前置条件，比如对输入参数的要求等，可省略。
• 后置条件标记（@post），描述执行方法的后置条件，比如对系统状态的影响或返回参数的结果预期等，可省略。
• 增加日期标记（@since），对于新增的方法，描述什么时候增加该方法及增加该方法的意图。可省略
• TODO标记（@todo），对该方法将要做的事情进行描述，用于比较关键的方法。
• 缺陷标记（@bug），对该方法存在的缺陷进行描述。若存在已知的缺陷，需要定义该标记，否则省略
• 返回值标记（@return），描述该方法的返回值，格式为：“@return 返回值类型 返回值描述”。若返回值为void类型，则省略该标记

2.5 模块注释

/*！
 * @defgroup 模块名称
 * @brief 模块简介
 *
 * 模块的详细描述
 * @{
 */





/** @} */

@{ 是模块起始标记。
/* @} /是模块结束标记。
位于模块起始注释块与结束注释块之间的所有内容将归入该模块。