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 模块简介
*
* 模块的详细描述
* @{
*/
/** @} */
@{ 是模块起始标记。
/* @} /是模块结束标记。
位于模块起始注释块与结束注释块之间的所有内容将归入该模块。