如何配置 ESLint 以检查 TypeScript class 属性 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 反对我的代码时，如果 class 上定义的属性不包含 JSDoc，我希望它 return 一个错误或警告说明。

例如，对于以下代码，我希望收到有关 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 标签可用于 classes 的 static 属性，因此理论上 eslint-plugin-jsdoc 项目可以调整规则以检查 class 上方 jsdoc 块中的任何 @property 标记与 class 中使用的那些属性之间的一致性，但我不确定这会有多受欢迎大多数项目似乎更喜欢以您示例中的方式添加文档（即，在属性本身之上）。

如果您在属性上方使用 @property 标记，您也可以使用 require-property 以及其他 require-property-* 规则，但我认为您不会真的想要那个，特别是因为我不确定文档工具如何处理 @property 在这种情况下 - 它似乎来自 TypeScript docs that @type is used instead--to check that @type has a curly-bracketed type, use jsdoc/valid-types and you could use jsdoc/match-description to indicate that the tag should have a description or use jsdoc/require-description 以便使用这两个描述相关的任何一个来强制执行标签上方的描述规则的 contexts 选项里面有 ClassProperty 因为它们默认不检查属性。

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

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

How do I configure ESLint to check for TypeScript class property JSDoc comments?

jsdoc

typescript

typescript-eslint

eslint-plugin-jsdoc