解决 eslint 针对 jsdoc 类型变量 no-unused-vars 的报错

前言

前端如果规范开发的话,肯定离不开 eslint。

怎么用 eslint,在这里就不赘述了,不是这篇文章想展开的话题。

当然,如果作为前端,你们团队是选用 typescript 开发的话,这篇文章想探求的话题,或许压根就不会成为你的烦恼。但是如果是用 js 的话,开发的时候又会用 eslint 来规范代码的话,并且,注重代码质量以及维护成本的话,或许也会碰到如同我一样的烦恼。

虽然个人一直想用 typescript 进行开发,但是无奈对于公司团队合作的项目来说,很难推广开来。

话不多说,先谈谈问题吧。

问题

现在假设我用这么个方法,想要获取 cesium 场景镜头信息(不了解 cesium 的童鞋不要紧,这里只是拿 cesium 的代码来举个例子):

eslint then不换行_vscode

每次调用该方法的时候,方法内部希望能获取 viewer 对象,为了配合支持参数的智能提示,则需要以 Use JSDoc: @param 的方式,标注一下参数。

这样标注了以后,配合 vscode 在使用该方法的时候,传参的过程中,就能支持智能提示了。

eslint then不换行_eslint_02

但是如果不做处理,就目前而言,会遇到一些问题。

Viewer 对象是我从 cesium 模块中导出来的对象,但是这个对象我在当前文件中并不需要用到,它只是在这个方法的标注中,给参数起提示作用的。

因此这个变量便无法通过 eslint 的监测,会提示其是 no-unused-vars ,即没有用到的变量。

eslint then不换行_vscode_03

当然,这里最简单最粗暴的解决方案是,直接在 .eslintrc.js 文件中,配置忽略掉这条规则的检测,或者在这个文件中,忽略掉这条规则的检测。

但是一旦我忽略掉这条规则的检测,就会影响到我正常的代码规范,这不是我希望看到的。

有没有一种方式,既能不忽略掉这条规则的检查,同时又能让 jsdoc 支持导入的变量呢?

答案当然是肯定的,否则也不会有这篇文章了。

方案

碰到问题,求助搜索引擎,准确点来说,是 Google,不失为一种良策。

找准关键词,来一顿猛搜,自然能找到相关的解决方案。

这次当然也没让我失望。

一顿操作下来,找到这么几个页面:

细心的童鞋可能会发现,这几个页面,刚好是层层递进的关系。

先看看 eslint 有没有提供对应的解决方案;发现没有后,于是再找找 eslint 官方的 issue 有没有对应的讨论;顺着 issue,找到了 eslint 官方有个页面,专门对 jsdoc 的支持进行了说明,还顺便推荐我们使用 eslint jsdoc 插件。

那我们就来看看,eslint-plugin-jsdoc 这个插件,有没有处理我们碰到的这个情况的解决方案,果然经过一番研究,还真的有:GitHub - gajus/eslint-plugin-jsdoc: JSDoc specific linting rules for ESLint.

可以看到,这个规则,就是专门解决我们的问题的。

eslint then不换行_eslint then不换行_04

验证

找到解决方案, 下一步当然是要验证一下,这个方案是否能解决我们的问题了。

先安装该插件:

npm install --save-dev eslint-plugin-jsdoc

装完以后,更改 .eslintrc.js 配置,增加如下配置:

eslint then不换行_eslint then不换行_05

然后再次打开我们的代码,发现已经没有提示错误的信息了:

eslint then不换行_eslint_06

当然,这个插件还有一些别的检查规则,我用不上,就没做过多的研究。如果感兴趣的童鞋,可以自己研究一下。