1 JS函数注释规范

1.1 描述函数作用或功能

格式为@description descriptionStatements
专注于what
较为复杂的业务可以适当写why

/**
 * @description 描述fn的作用或功能
 */
复制代码

1.2 描述参数

格式为@param {paramDataType} p1 descriptionStatements
p1代表必选参数
[p1]代表可选参数
[p1=xxx]代表带默认值的参数

/**
 * @param {string} a 参数描述
 * @param {number} [b] 参数描述
 * @param {boolean} [c=false] 参数描述
 */
复制代码

1.3 描述为数组的参数

参数为数组必须对其每个元素进行详细描述
元素描述规则参考1.2小节

格式如下

/**
 * 数组参数：
 * @param {array} arr 参数描述
 * @param {string} arr[0] 参数描述
 * @param {number} [arr[1]=undefined] 参数描述
 */
复制代码

1.4 描述返回值

格式为@return {paramDataType} descriptionStatements
即使无返回值，也要写@return {undefined}

/**
 * @return {number} 描述返回值
 */
复制代码

1.5 完整例子

完整注释如下

/**
 * @description 描述fn的作用或功能
 * @param {string} a 参数描述
 * @param {number} [b] 参数描述
 * @param {boolean} [c=false] 参数描述
 *
 * 数组参数：
 * @param {array} arr 参数描述
 * @param {string} arr[0] 参数描述
 * @param {number} [arr[1]=undefined] 参数描述
 *
 * @return {number} 描述返回值
 */
function fn(a, b, c = false) {
  // code
  return 1;
}
复制代码

例子

  /**
   * @description 对树形组件数据进行修正，本地化操作，仅需执行一次
   * @param {object} data 从后端拉取的未修改数据
   * @return {undefined} 无需返回值
   */
  cleanLeftMenuData(data) {
    // ....
  }
复制代码