jsdoc 注释标签一览
本文最后更新于:2021年12月24日 晚上
速览表格
标签列表
标签 | 简介 |
---|---|
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)), []);
}
本博客所有文章除特别声明外,均采用 CC BY-SA 4.0 协议 ,转载请注明出处!