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

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

前言

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

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

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

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

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

问题

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

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

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

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

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

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

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

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

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

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

方案

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

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

这次当然也没让我失望。

一顿操作下来，找到这么几个页面：

• eslint 相关配置页面
  no-unused-vars - Rules - ESLint - Pluggable JavaScript linter

• 相关 github issue 讨论
  Proposed rule change: no-unused-vars should consider a var “used” in JSDoc · Issue #9050 · eslint/eslint · GitHub

• eslint 官方提示
  End-of-Life for Built-in JSDoc Support in ESLint - ESLint - Pluggable JavaScript linter

• 可用的方式
  GitHub - gajus/eslint-plugin-jsdoc: JSDoc specific linting rules for ESLint.

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

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

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

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

验证

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

先安装该插件：

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

装完以后，更改 .eslintrc.js 配置，增加如下配置：

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

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