JSDoc 快速上手-技术圈

作者：Midqiu

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 -