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

问题描述

我有一个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*规则似乎不起作用，但是无论如何我都尝试将其切换，并且它们没有报告缺少JSDoc。

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

我缺少什么ESLint规则，这些规则会报告有关TypeScript属性的JSDocs丢失？

解决方法

首先，我应该注意到eslint-plugin-jsdoc 的规则是递增的。如果您根本没有任何 jsdoc 块，您首先需要添加 jsdoc/require-jsdoc 规则，以便它会抱怨，除非您至少有以下内容：

/**
 *
 */

...在您感兴趣的结构之上。在您的情况下，您确实有包含此规则的“推荐”，因此您在那里得到了保障。

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

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

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

如果您在属性正上方使用 @property 标签，您也可以使用 require-property 以及其他 require-property-* 规则，但我认为您不会真的想要那样，特别是因为我不确定文档工具在这种情况下如何处理 @property——从 TypeScript docs 看来，@property 被用来代替——检查 @type花括号类型，使用 jsdoc/valid-types 并且您可以使用 jsdoc/match-description 来指示标签应该具有描述或使用 jsdoc/require-description 以强制在标签上方添加描述，使用以下任一种这两个与描述相关的规则的 @type 选项包含 contexts，因为它们默认不检查属性）。

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

jsdoc typescript typescript typescript-eslint