jsdoc 注释标签一览

jsdoc 注释标签一览

速览表格

标签列表

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

语法列表

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

标签

param

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

returns

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

example

1
2
3
4
5
6
7
8
9
10
/**
* 获取一个 0-1 之间的随机数
* @returns 随机数
* @example
* const i = random()
* console.log(i)
*/
function random() {
return Math.random()
}

test

1
2
3
4
5
6
7
8
9
10
/**
* @test {random} 测试 random 函数
*/
describe('测试 random 函数', () => {
it('测试两次随机数是否相等', () => {
const i = random()
const k = random()
expect(i).not.toBe(k)
})
})

class

1
2
3
4
5
/**
* 简单模拟 Vue class
* @class Vue
*/
class Vue {}

property

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
/**
* 简单模拟 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
}
}

语法

{}

1
2
3
4
5
6
7
8
9
/**
* 计算两个数字之和
* @param {Number} i 第一个数字
* @param {Number} k 第二个数字
* @returns {Number} 两数之和
*/
function add(i, k) {
return i + k
}

{T,R}

1
2
3
4
5
6
7
8
9
/**
* 计算两个数字之和,或者两个字符串之间的连接
* @param {Number|String} i 第一个数字
* @param {Number|String} k 第二个数字
* @returns {Number|String} 两数之和,或者两个字符串之间的连接
*/
function add(i, k) {
return i + k
}

[]

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

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

1
2
3
4
5
6
7
8
9
/**
* 分割字符串为数组
* @param {String} str 字符串
* @param {String} [sep] 分隔符
* @returns {Array} 分割后的数组
*/
function split(str, sep) {
return sep ? str.split(sep) : [str]
}

[arg=v]

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

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

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

1
2
3
4
5
6
7
8
9
/**
* 分割字符串为数组
* @param {String} str 字符串
* @param {String} [sep=''] 分隔符
* @returns {Array} 分割后的数组
*/
function split(str, sep = '') {
return str.split(sep)
}

.<T>

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

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

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

obj.property

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/**
* 简单模拟 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

1
2
3
4
5
6
7
8
9
/**
* 自行实现 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)), [])
}