ReactJS ESLint对类组件误报缺失JSDoc @return问题求助

问题原因 #

• 根本原因是ESLint v7版本自带的原生valid-jsdoc规则存在识别缺陷，会错误将ES6类声明的头部JSDoc识别为普通函数的注释，因此触发了函数才需要的@return校验逻辑，才会出现“加也报错不加也报错”的矛盾提示。
• 你使用的eslint-config-google@0.13.0对ESLint v7的适配不完善，默认开启的valid-jsdoc规则没有对类注释做特殊兼容，进一步放大了这个问题。

解决方案 #

以下方案按推荐优先级排序：

方案1：给类注释添加标识标签（成本最低） #

在类的头部JSDoc中添加@class标签，明确告知校验规则这是类的注释而非函数注释，即可规避校验错误，修改后的示例代码如下：

/**
 * DashboardBanner is the top bar of the body.
 * @class
 */
class DashboardBanner extends React.Component {
  // 类内部代码无需修改
}

方案2：替换废弃的原生JSDoc校验规则（最优长期方案） #

ESLint官方早已废弃原生的valid-jsdoc和require-jsdoc规则，更推荐使用维护更活跃、识别更准确的eslint-plugin-jsdoc插件做JSDoc校验，该插件对React类组件、函数组件的JSDoc识别都做了专门适配，不会出现这类误判问题。
操作步骤：

1. 安装插件：npm install eslint-plugin-jsdoc --save-dev
2. 修改.eslintrc.js配置：
   • 在plugins数组中添加jsdoc
   • 移除原有的valid-jsdoc和require-jsdoc规则，替换为插件提供的对应规则即可。

方案3：调整原生valid-jsdoc规则配置（临时适配） #

如果不想改动现有校验逻辑，也可以直接修改规则配置，关闭不必要的返回值强制校验：

// .eslintrc.js rules部分修改如下
'valid-jsdoc': [1, {
  requireReturn: false, // 不强制要求所有函数必须写@return
  requireReturnForObjectLiteral: false,
}]

额外优化提示：你现有代码里render方法的@return {html}写法不规范，标准类型建议写JSX.Element，不过这不是本次报错的原因。

内容的提问来源于stack exchange，提问作者ZontarZon