项目中的注释规范该怎么写？最近在封装组件，写组件说明，为了流程的规范化及合理性，也为了让自己少被后人 ~~(接锅侠)~~

摘要：

最近在封装组件，写组件说明，为了流程的规范化及合理性，也为了让自己少被后人 ~~(接锅侠)~~ 诟病，于是不得不去网上翻阅资料，参考文献，也算是自己的一种记录吧。。。

函数多行注释

函数(方法)注释也是多行注释的一种，但是包含了特殊的注释要求，参照JSDoc。

常用注释关键字

注释名	语法	含义	示例
@param	@param 参数名 {参数类型} 描述信息	描述参数的信息	@param name {String} 传入名称
@return	@return {返回类型} 描述信息	描述返回值的信息	@return {Boolean} true:可执行;false:不可执行
@author	@author 作者信息 [附属信息：如邮箱、日期]	描述此函数作者的信息	@author 张三 2015/07/21
@version	@version XX.XX.XX	描述此函数的版本号	@version 1.0.3
@example	@example 示例代码	演示函数的使用	@example setTitle(‘测试’)

/**
* 合并Grid的行
* @param grid {Ext.Grid.Panel} 需要合并的Grid
* @param cols {Array} 需要合并列的Index(序号)数组；从0开始计数，序号也包含。
* @param isAllSome {Boolean} ：是否2个tr的cols必须完成一样才能进行合并。true：完成一样；false(默认)：不完全一样 
* @return void
* @author xiaoafeng 2015/07/21
* @example
* _________________                       _________________
* | 年龄 | 姓名 |                           | 年龄 | 姓名 |
* ----------------- mergeCells(grid,[0]) -----------------
* | 18 | 张三 |             =>             |      | 张三 |
* -----------------                        - 18 ---------
* | 18 | 王五 |                            |      | 王五 |
* -----------------                        -----------------
*/ 

function mergeCells(grid: Ext.Grid.Panel, cols: Number[], isAllSome: boolean = false) {
  // Do Something
}

文档注释

文档注释将会以预定格式出现在API文档中。它以 “/** ”开头，以“ */ ”结束，其间的每一行均以“*”开头（均与开始符的第一个“*\”对齐），且注释内容与“*”间留一个空格。

文档注释必须包含一个或多个注释标签。

@module。声明模块

/**
* 模块说明
* @module 模块名
*/

/**
* Core模块提供最基础、最核心的接口
* @module Core
*/

@class。声明类

/**
* 类说明
* @class 类名
* @constructor
*/

// @class必须搭配@constructor或@static使用，分别标记非静态类与静态类。 

/**
* 节点集合类
* @class NodeList
* @constructor
* @param {ArrayLike<Element>} nodes 初始化节点
*/

@method。声明函数或类方法

/**
* 方法说明
* @method 方法名
* @for 所属类名
* @param {参数类型} 参数名 参数说明
* @return {返回值类型} 返回值说明
*/

// 没有指定@for时，表示此函数为全局或模块顶层函数。当函数为静态函数时，必须添加@static；当函数有参数时，必须使用@param；当函数有返回值时，必须使用@return。

/**
* 返回当前集合中指定位置的元素
* @method
* @for NodeList
* @param {Number} [i=0] 位置下标。如果为负数，则从集合的最后一个元素开始倒数 
* @return {Element} 指定元素
*/

@param。声明函数参数，必须与@method搭配使用。
@property。声明类属性

 /**
 * 属性说明
 * @property {属性类型} 属性名 
 */

注意事项

应该做的

总是在单行注释符后留一个空格。

 // this is comment

总是在多行注释的结束符前留一个空格（使星号对齐） /* */
如果某段代码有功能未实现，或者有待完善，必须添加 TODO 标记，TODO 前后应留一个空格。

// TODO 未处理IE6-8的兼容性 function setOpacity(node, val) { node.style.opacity = val; }

不该做的

不要把注释写在多行注释的开始符、结束符所在行。

/* start 
end */

/* 
here is line 1 here is line 2 
*/

不要编写无意义的注释。

// 初始化value变量为0 var value = 0;

注释示例

参数和返回值类型 Type：string、boolean、number、object、array、function

基本方法块注释

如果描述不能描述清楚，添加例子来描述。

/**
 * @method
 * @param {Type} data 目标对象
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data){
    return '返回对象'
}

基本方法块注释-注释过长时

如果需要折行则在文本中使用<br/>标签

/**
 * @method
 * @param {Type} data 目标对象<br/>
 * 例：
 *  {
 *      target:手机号
 *  }
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data){
    return '返回对象'
}

基本方法块注释-参数可选

/**
 * @method
 * @param {Type} [data] 目标对象
 * 例：
 *  {
 *      target:手机号
 *  }
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data){
    return '返回对象'
}

基本方法块注释-带默认值

/**
 * @method
 * @param {Type} data={} 目标对象
 * 例：
 *  {
 *      target:手机号
 *  }
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data){
    return '返回对象'
}

方法块注释特殊参数

如果描述不能描述清楚，添加例子来描述。如果方法中有异常处理，标记异常处理注释

/**
 * @method
 * @param {Type} data 目标对象
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 * @throws {string} 抛出'Error'异常
 * @example
 * add(1, 2);    // 返回3
 */
function matchedNumber(data){
    return '返回对象'
}

如果有返回值增加@returns 如果没有省略此属性

文件注释

在文件头部增加文件注释

/**
 * @file LBS控制器
 * @author xiaoafeng
 * @copyright Synway SFE
 * @createDate 2017-10-16 09:40:11
 */

webstorm的live Templates

1. desc: 小阿峰

/**
* @description: 
* @author: xiaoafeng 
* @time: date 
*/

2. fun

/** 
* @func 
* @desc 函数的描述 
* @param {参数1的类型} 参数名 参数描述 
* @param {参数1的类型} 参数名=1 默认值参数 
* @param {参数1的类型} [参数名] 可选参数 
* @returns {Type} 函数返回值的描述 
*/

示例 
/**
* @func 
* @desc 这个函数用于测试
* @param {string} a 第一个参数
* @param {number} b=1 第二个参数 
* @param {number} [c=2] 可选参数 
* @returns {boolean} 返回值 
*/ 
function f(a, b = 1, c = 2) { 
  return true;
}

3. method

/**
* @method
* @desc 根据目标对象获取运营商
* @param {参数1的类型} 参数名 参数描述
* @param {参数1的类型} 参数名=1 默认值参数
* @param {参数1的类型} [参数名] 可选参数
* @returns {Type} 函数返回值的描述 
*/

/** 
* @class
* @classdesc 这是对myClass类的描述
*/
function myClass() {
}

/** 
* @method
* @desc myClass方法的描述
* @param {string} a - 参数a 
*/
myClass.prototype.foo = function (a) { 
  console.log('xiaoafeng');
  return true;
}

4. var

/** 
* @var {object}
* @desc 变量定义
* @property {string} a 属性a 
* @property {string} b 属性b 
*/

示例 
/** 
* @var foo
* @desc 变量定义
* @property {string} a 属性a 
* @property {string} b 属性b 
*/
var foo = { a:'a', b:'b' }

项目中的注释规范该怎么写？