JSDoc 快速上手

Posted 2021-07-12 SegmentFault

作者：Midqiu

来源：SegmentFault 思否社区

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 */

或者：

/**@typedef {Function} FN
 * @argument {string} a
 * @argument {string} b
 */

---

点击左下角阅读原文，到  SegmentFault 思否社区  和文章作者展开更多互动和交流，扫描下方” 二维码 “或在“ 公众号后台 “ 回复“  入群  ”即可加入我们的 技术交流群 ，收获更多的技术文章~

- END -