前端人需要了解的JsDoc

这是我参与新手入门的第一篇文章

前言

大家在写前端的时候，应该多多少少都知道JsDoc, 就算不知道JsDoc的大名，估计在看到一些代码的时候，就会惊呼，原来我之前就用过它! 下面就写一段大家最常见的一些代码:

/**
 * 自我介绍
 * @param {String} name 名字
 * @param {Number} age 年龄
 */
function introduce (name, age) {
    console.log(`你好呀, 我叫${name}, 我今年${age}岁了`)
}
复制代码

很多人以为这就是所有的JsDoc了，其实这只是JsDoc里边的冰山一角而已，JsDoc里边有很多东西，但是按照28原则，我们平常能用到的其实就是里边的20%而已，下面我就把我理解的JsDoc的一些好用的地方给大家讲一下~

自动补全

还是上边那个自我介绍的例子，定义了@param {String} name 名字这个文档注释后，在函数体里边就可以直接 name.i可以点出来indexOf方法，因为注释里边明确告诉编辑器，这个变量是字符串，所以可以自动提示出来字符串的方法. 这样就避免我们自己盲打然后打错了，接着再花一段时间去查错了.

类型检查

先上代码:

// @ts-check

/**
 * 加法
 * @param {Number} num 数字
 */
function increase (num) {
  return num + 1
}

increase('测试')
复制代码

在vscode里边，还没有执行就提前报错了. 这是因为我们在函数前面加上了 // @ts-check ，这样vscode就会去检查传递的参数是否跟我们想要的参数类型一致。 是不是看着感觉有点像typescript了。只是我们的类型写在注释里边了. 感觉是不是像给我们平常写的javascript赋能了一样. 接着我们再写一些更像typescript的东西.

自定义类型

/**
 * 包含姓名和年龄的对象
 * @typedef {Object<string, any>} Person
 * @property {string} name - 姓名
 * @property {number} [age] - 年龄
 */

/**
 * @type { Person } person
 */
const person = {
  name: 'Nancy',
  age: 18
}
复制代码

用@typedef来自定义一个类型Person,然后用@type 来使用类型. 这里我们把类型Person描述成是一个键是string,值是any的对象，如果这时候我们把any改成number的话，编辑器将会给我们报错，因为对象里边name不符合定义的这个类型.

枚举

/**
 * @typedef { 'bob' | 'nancy' | 'james' } nameEnum
 */

/**
 * @type { nameEnum } name
 */
const name = 'james'
复制代码

类似枚举的一种写法，也是先用@typedef来自定义一个类型，只是这个类型是预先写好的几个固定值，这时候，在需要用到的变量前使用@type,就可以如截图中看到的，编辑器会把我们定义好的值做成下来选项让我们选择. 这种做法也能极大的规避我们写错一些状态值什么的，不容易发现的小错误。

导入类型

我们写webpack配置的时候，是不是老是会记不住单词? 比如里边配置到底是rule,还是rules, module还是modules？ 忘记的话，我们只好去翻一下webpack官网了。 这样的话，就很花时间了.
这种场景，我们也可以用JsDoc去解决。

其他

其他比如还有写在文件头部的描述文件和作者的注释

/**
 * @file 文件配置
 * @module config/config
 * @author jameskid007 <https://github.com/jameskid007/nuxt-ssr-demo>
 */
复制代码

另外还有很多很多有用的jsDoc，我这里就先抛砖引玉了，大家可以找到JsDoc文档具体去看一下~
JsDoc文档

结语

好了，JsDoc我认为的一些好用的点，我都简单的去描述了一下，也给自己做一个记录。这是我第一篇文章，虽然写的东西很少，但是也还是蛮花时间去敲的. 不过整个过程还蛮愉悦的. 希望可以写出多一点东西，记录一下自己的学习！