JSDoc 快速上手

Midqiu
English

JSDoc 是在JS代码的注释里,以特定的格式标记变量的类型,函数的参数、返回值等,这样做可以避免调用函数的时候传错或少传参数,提高代码的健壮性,减少bug;再加上编辑器的支持,可以极大的提高编码的效率。

比如说下面的这个例子,
image.png
因为我们标记了pd的类型,当调用pd这个变量的时候,编辑器可以非常方便的提示这个对象上有什么方法。

我们翻看JSDoc的官方文档发现罗列了一大堆的功能,但其实常用的功能也就几个,只需要花几分钟掌握一下下面的几个使用方法,就可以大幅度提高写代码的编辑体验。

JSDoc语法上要求以/**开头,*/的注释。

声明函数的参数的类型

@param {参数的类型} 参数的名 注释

如图所示,当我们定义好一个函数后,在函数的上方输入 /**然后按回车,编辑器会自动替我们补充好相关的变量名等信息,我们只需要填上参数的类型就可以了。

写好类型之后,在函数内部使用,编辑器会提示对应的方法和属性;

image.png

调用函数的时候,编辑器也会解析我们写到JSDoc内容,提示需要传入的参数的类型和参数的注释。
image.png

类型除了图上所示的string之外,还有booleanundefinednull 类型;还有复杂类型,{key1:string,key2?:number} ;还可以相互组合比如 string|number 等typescript里面可以用type定义的。

声明函数的返回值的类型

@returns来指定函数的参数类型和返回值类型

@returns {string}

例如:

/**
 *
 * @param {string} id 注释注释注释
 * @param {string} name 注释注释注释
 * @returns {string}
 */
function getName(id, name) {
  //name.
}

调用的效果:
image.png

声明变量的类型

/**@type {string} */
var aaa=global.aaa

效果图:
image.png

定义一个类型

有时候,有一些类型比较复杂,并且许多地方都需要用,这时候我们可以定义一个类型,供其他地方使用。

@typedef {类型} 类型名

比如,我们定义了一个类型User,分别有两个属性name和age

/**@typedef {{name:string,age:number}} User */

也可以写成这种方式:

/**
 * @typedef {Object} User
 * @property {string} name
 * @property {number} age
 */

在函数定义中使用:
image.png

在其他地方使用:
image.png

定义一个函数类型的复杂类型:

/**@typedef {(a:string,b:string)=>void} FN */

其他例子,比如标记对象的某个属性比如说get是一个函数,要标准这个函数里面参数的类型:
image.png

或者这样:
image.png

阅读 767

Midqiu
记录我对前端开发的一些总结。
1.4k 声望
44 粉丝
0 条评论
你知道吗?

1.4k 声望
44 粉丝
宣传栏