如何配置 ESLint 以检查 TypeScript 类属性 JSDoc 注释？

Question

我有一个包含以下包的 TypeScript 应用程序 (4.0.x)：

"@typescript-eslint/eslint-plugin": "^4.0.1",
"@typescript-eslint/parser": "^4.0.1",
"@vue/cli-plugin-eslint": "^4.5.4",
"eslint": "^7.8.1",
"eslint-plugin-jsdoc": "^30.3.1",

我的 .eslintrc.js 包括以下内容：

'extends': [
    'plugin:vue/essential',
    'eslint:recommended',
    '@vue/typescript/recommended',
    "plugin:jsdoc/recommended"
],
parserOptions: {
    ecmaVersion: 2020
},
plugins: [
    "jsdoc"
],
rules: {
    'jsdoc/require-property-description': 1,
    'jsdoc/require-description': 1,
    'jsdoc/require-param-type': 'off',
    'jsdoc/require-returns-type': 'off',
    'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off'
}

当我对我的代码运行 ESLint 时，如果在类上定义的属性不包含 JSDoc 描述，我希望它返回错误或警告。

例如，使用以下代码，我会收到一条关于 id、mainCharacters 和 state 缺少 JSDoc 描述的消息。

export default class Party {
    public id = -1;
    public mainCharacters: Character[] = [];
    public state: PartyState;
    /**
     * Location index.
     */
    public location = 0;

根据文档，jsdoc/require-property* 规则似乎不起作用，但我确实尝试将它们打开，并且它们没有报告缺少 JSDocs。

'jsdoc/require-property': 1,
'jsdoc/require-property-description': 1,
'jsdoc/require-property-name': 1,
'jsdoc/require-property-type': 1,

我缺少哪些 ESLint 规则会报告 TypeScript 属性上缺少 JSDocs？

Answer 1

首先，我应该注意到eslint-plugin-jsdoc 的规则是递增的。如果你根本没有任何 jsdoc 块，你首先需要添加 jsdoc/require-jsdoc 规则，这样它就会抱怨，除非你至少有类似的东西：

/**
 *
 */

...在您感兴趣的结构之上。在您的情况下，您确实有包含此规则的“推荐”，因此您已被覆盖。

同样，require-property-description 或 require-property-name 之类的规则只有在给定块上已有 @property 时才有效。

其次，require-property 规则的目的与您尝试做的不同。它用于报告当 jsdoc 块具有 @namespace 标记（用于普通对象）或 @typedef 标记（用于定义类型）时存在 @property。

JSDoc 确实 indicate 标记可用于类的 static 属性，因此 eslint-plugin-jsdoc 项目理论上可以调整规则以检查任何 @property 标记之间的一致性类上方的 jsdoc 块和类中使用的那些属性，但我不确定这会多么受欢迎，因为大多数项目似乎更喜欢以您的示例中的方式添加文档（即，在属性本身之上）。

如果您在属性上方使用@property 标签，您也可以使用require-property，以及其他require-property-* 规则，但我认为您不会真的想要这样，尤其是因为我不是确定文档工具在这种情况下如何处理@property——从TypeScript docs 看来，@type 被使用——检查@type 是否具有大括号类型，使用jsdoc/valid-types，你可以使用jsdoc/match-description 表示标签应该有描述或使用jsdoc/require-description 以便在标签上方强制描述，使用这两个与描述相关的规则'contexts 选项和ClassProperty 中的任何一个，因为它们没有' t 默认检查属性）。

但要最终回到您需要的最重要部分，您将需要使用jsdoc/require-jsdoc。但是，默认情况下 require-jsdoc 仅检查 FunctionDeclaration，即常规函数声明，但您可以使用 require 或 contexts 选项进行更精确的控制，即，在您的情况下，您可以添加 {contexts: ['ClassProperty']} .