什么时候对函数进行注释

不一定说任何函数方法都必须使用JSDoc，但是有一点要注意如果是自己封装的方法，有必要使用JSDoc，理由是可以让其他成员更容易的去了解你封装的方法的属性或返回值，这样可以降低维护成本和提高开发效率。

编码实战

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

语法：

/** 
* 函数说明 
* @关键字 
*/

常用注释关键字：(只列出一部分，并不是全部)

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

这里只是详细讲解了 js中函数(方法)注释，还有很多其它的规范没来得及填充，可以参考一下Airbnb JavaScript Style Guide

参数传入回调函数

/**
 * This callback type is called `requestCallback` and is displayed as a global symbol.
 *
 * @callback requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */
/**
 * Does something asynchronously and executes the callback on completion.
 * @param {requestCallback} cb - The callback that handles the response.
 */
function doSomethingAsynchronously(cb) {
    // code
}; 

参考资料

JSDoc 中文文档