jsdoc 注释标签一览

速览表格

标签列表

标签	简介
param	参数
returns	返回值
example	示例
test	测试代码
class	类定义
property	类属性定义

语法列表

语法	简介
{T}	类型
{T,R}	多个类型
[]	可选值
[arg=v]	默认值
.<T>	泛型
obj.property	对象参数
function(T):R	函数参数

标签

param

/**
 * 在控制台上打印一个值
 * @param obj 需要被打印的值
 */
function print(obj) {
  console.log(obj)
}

returns

/**
 * 获取一个 0-1 之间的随机数
 * @returns 随机数
 */
function random() {
  return Math.random()
}

example

/**
 * 获取一个 0-1 之间的随机数
 * @returns 随机数
 * @example
 * const i = random()
 * console.log(i)
 */
function random() {
  return Math.random()
}

test

/**
 * @test {random} 测试 random 函数
 */
describe('测试 random 函数', () => {
  it('测试两次随机数是否相等', () => {
    const i = random()
    const k = random()
    expect(i).not.toBe(k)
  })
})

class

/**
 * 简单模拟 Vue class
 * @class Vue
 */
class Vue {}

property

/**
 * 简单模拟 Vue class
 * @class Vue
 * @property {String|Element} option.el 实例绑定的 DOM 选择器或元素
 * @property {Object|Function} [option.data={}] 实例内部绑定的数据，默认为空对象
 * @property {Object} [option.methods={}] 实例的方法对象，默认为空对象
 * @property {Function} [option.mounted=function() {}] 实例的初始化函数，默认为空函数
 */
class Vue {
  /**
   * 构造函数
   * @param {Object} option 可选项
   * @param {String|Element} option.el 实例绑定的 DOM 选择器或元素
   * @param {Object|Function} [option.data={}] 实例内部绑定的数据，默认为空对象
   * @param {Object} [option.methods={}] 实例的方法对象，默认为空对象
   * @param {Function} [option.mounted=function() {}] 实例的初始化函数，默认为空函数
   */
  constructor({ el, data = {}, methods = {}, mounted = function() {} } = {}) {
    this.el = el
    this.data = data
    this.methods = methods
    this.mounted = mounted
  }
}

语法

{}

/**
 * 计算两个数字之和
 * @param {Number} i 第一个数字
 * @param {Number} k 第二个数字
 * @returns {Number} 两数之和
 */
function add(i, k) {
  return i + k
}

{T,R}

/**
 * 计算两个数字之和，或者两个字符串之间的连接
 * @param {Number|String} i 第一个数字
 * @param {Number|String} k 第二个数字
 * @returns {Number|String} 两数之和，或者两个字符串之间的连接
 */
function add(i, k) {
  return i + k
}

[]

使用场景: 可选参数不需要在函数中所有条件下使用

例如下面的 sep 在不传入时会默认返回 [str]，一般优先使用 [arg=v] 更好

/**
 * 分割字符串为数组
 * @param {String} str 字符串
 * @param {String} [sep] 分隔符
 * @returns {Array} 分割后的数组
 */
function split(str, sep) {
  return sep ? str.split(sep) : [str]
}

[arg=v]

使用场景: 需要为传入的参数赋予默认值

注: 太过冗长的默认值最好使用文件描述而非加到 [] 中

例如下面的函数参数 sep，如果想要在不传入的时候默认为 ''，就需要使用默认值标记。

/**
 * 分割字符串为数组
 * @param {String} str 字符串
 * @param {String} [sep=''] 分隔符
 * @returns {Array} 分割后的数组
 */
function split(str, sep = '') {
  return str.split(sep)
}

.<T>

使用场景: Array, Map, Set, Iterator 这中集合接口/类限定元素类型，也有 Promise 这种内嵌其他类型异步结果的情况

例如下面的集合就声明元素全部都需要为 String，Object 的话可能出现 [object Object] 这种内容

/**
 * 将 String 类型的数组中的元素都连接起来，并以逗号进行分割
 * @param {Array.<String>} arr 字符串数组
 * @returns {String} 连接后的字符串
 */
function join(arr) {
  return arr.join(',')
}

obj.property

/**
 * 简单模拟 Vue API
 * @param {Object} option 可选项
 * @param {String|Element} option.el 实例绑定的 DOM 选择器或元素
 * @param {Object|Function} [option.data={}] 实例内部绑定的数据，默认为空对象
 * @param {Object} [option.methods={}] 实例的方法对象，默认为空对象
 * @param {Function} [option.mounted=function() {}] 实例的初始化函数，默认为空函数
 */
function Vue({ el, data = {}, methods = {}, mounted = function() {} } = {}) {
  this.el = el
  this.data = data
  this.methods = methods
  this.mounted = mounted
}

function(T):R

/**
 * 自行实现 flatMap，将数组压平一层
 * @param {Array.<Object>} arr 数组
 * @param {function(Object):Array} fn 映射方法，将一个元素映射为一个数组
 * @returns {Array.<Object>} 压平一层的数组
 */
export function flatMap(arr, fn) {
  return arr.reduce((res, item) => res.concat(fn(item)), [])
}