阅读 410
前端人需要了解的JsDoc

前端人需要了解的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方法,因为注释里边明确告诉编辑器,这个变量是字符串,所以可以自动提示出来字符串的方法. 这样就避免我们自己盲打然后打错了,接着再花一段时间去查错了.

image.png

类型检查

先上代码:

// @ts-check

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

increase('测试')
复制代码

image.png 在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'
复制代码

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

导入类型

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

image.png

其他

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

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

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

结语

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

文章分类
前端
文章标签