JSDoc 快速上手

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

比如说下面的这个例子，

因为我们标记了pd的类型，当调用pd这个变量的时候，编辑器可以非常方便的提示这个对象上有什么方法。

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

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

声明函数的参数的类型

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

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

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

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

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

声明函数的返回值的类型

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

@returns {string}

例如：

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

调用的效果：

声明变量的类型

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

效果图：

定义一个类型

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

@typedef {类型} 类型名

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

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

也可以写成这种方式：

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

在函数定义中使用：

在其他地方使用：

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

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

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

或者这样：