javascript开发中函数注释的用法

2023-02-08 21:48 由云冬发表于 #前端开发

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

什么时候对函数进行注释

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

编码实战

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

语法：

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

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

注释名	语法	含义	示例
@function	@function 简要描述	用于定义当前对象是一个函数，后面可跟描述	@function 处理表格的行
@description	@description 描述信息	用于描述	@description 合并Grid的行
@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(‘测试’)

/**
* @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
};