From 05faac9da5f0a658230938d0719a52fa4a744186 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 29 Dec 2023 14:49:18 -0500 Subject: [PATCH 1/2] chore: enable jsdoc/informative-docs internally --- .eslintrc.js | 2 + package.json | 1 + .../src/rules/adjacent-overload-signatures.ts | 1 - .../src/rules/member-ordering.ts | 1 - .../rules/padding-line-between-statements.ts | 3 +- .../src/rules/space-before-function-paren.ts | 2 - .../src/definition/DefinitionBase.ts | 4 -- packages/scope-manager/src/scope/ScopeBase.ts | 7 --- packages/typescript-estree/src/convert.ts | 4 -- packages/typescript-estree/src/node-utils.ts | 2 - packages/utils/src/eslint-utils/deepMerge.ts | 1 - packages/utils/src/ts-eslint/CLIEngine.ts | 2 +- packages/utils/src/ts-eslint/ESLint.ts | 1 - packages/utils/src/ts-eslint/RuleTester.ts | 1 - packages/utils/src/ts-eslint/SourceCode.ts | 5 -- yarn.lock | 62 +++++++++++++++++++ 16 files changed, 67 insertions(+), 32 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 400ed10c4aaa..ec7f52978253 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -10,6 +10,7 @@ module.exports = { 'eslint-plugin', 'import', 'jest', + 'jsdoc', 'simple-import-sort', 'unicorn', ], @@ -218,6 +219,7 @@ module.exports = { 'one-var': ['error', 'never'], + 'jsdoc/informative-docs': 'error', 'unicorn/no-typeof-undefined': 'error', }, overrides: [ diff --git a/package.json b/package.json index 5448f0ebae21..bcbc6c9d40cc 100644 --- a/package.json +++ b/package.json @@ -87,6 +87,7 @@ "eslint-plugin-eslint-plugin": "^5.1.0", "eslint-plugin-import": "^2.27.5", "eslint-plugin-jest": "^27.2.2", + "eslint-plugin-jsdoc": "^46.9.1", "eslint-plugin-jsx-a11y": "^6.7.1", "eslint-plugin-react": "^7.32.2", "eslint-plugin-react-hooks": "^4.6.0", diff --git a/packages/eslint-plugin/src/rules/adjacent-overload-signatures.ts b/packages/eslint-plugin/src/rules/adjacent-overload-signatures.ts index 45aee8fe043b..e10a4c815448 100644 --- a/packages/eslint-plugin/src/rules/adjacent-overload-signatures.ts +++ b/packages/eslint-plugin/src/rules/adjacent-overload-signatures.ts @@ -128,7 +128,6 @@ export default createRule({ } /** - * Check the body for overload methods. * @param {ASTNode} node the body to be inspected. */ function checkBodyForOverloadMethods(node: RuleNode): void { diff --git a/packages/eslint-plugin/src/rules/member-ordering.ts b/packages/eslint-plugin/src/rules/member-ordering.ts index 95d6c3715e0f..a972bf86b2ba 100644 --- a/packages/eslint-plugin/src/rules/member-ordering.ts +++ b/packages/eslint-plugin/src/rules/member-ordering.ts @@ -632,7 +632,6 @@ function getRank( * public-instance-method. * If a lowest possible rank is a member group, a comma separated list of ranks is returned. * @param ranks the existing ranks in the object. - * @param target the target rank. * @param order the current order to be validated. * @returns the name(s) of the lowest possible rank without dashes (-). */ diff --git a/packages/eslint-plugin/src/rules/padding-line-between-statements.ts b/packages/eslint-plugin/src/rules/padding-line-between-statements.ts index 9c6555eb9075..3f631c83e826 100644 --- a/packages/eslint-plugin/src/rules/padding-line-between-statements.ts +++ b/packages/eslint-plugin/src/rules/padding-line-between-statements.ts @@ -124,7 +124,7 @@ function newNodeTypeTester(type: AST_NODE_TYPES): NodeTestObject { /** * Skips a chain expression node * @param node The node to test - * @returnsA non-chain expression + * @returns A non-chain expression * @private */ function skipChainExpression(node: TSESTree.Node): TSESTree.Node { @@ -325,7 +325,6 @@ function isExpression( * ;[1, 2, 3].forEach(bar) * @param sourceCode The source code to get tokens. * @param node The node to get. - * @returns The actual last token. * @private */ function getActualLastToken( diff --git a/packages/eslint-plugin/src/rules/space-before-function-paren.ts b/packages/eslint-plugin/src/rules/space-before-function-paren.ts index 9e3366f3a9b1..2b2d8da18bde 100644 --- a/packages/eslint-plugin/src/rules/space-before-function-paren.ts +++ b/packages/eslint-plugin/src/rules/space-before-function-paren.ts @@ -70,7 +70,6 @@ export default createRule({ /** * Determines whether a function has a name. - * @param {ASTNode} node The function node. * @returns {boolean} Whether the function has a name. */ function isNamedFunction( @@ -97,7 +96,6 @@ export default createRule({ /** * Gets the config for a given function - * @param {ASTNode} node The function node * @returns {string} "always", "never", or "ignore" */ function getConfigForFunction( diff --git a/packages/scope-manager/src/definition/DefinitionBase.ts b/packages/scope-manager/src/definition/DefinitionBase.ts index 01976f164eb0..05097653c11b 100644 --- a/packages/scope-manager/src/definition/DefinitionBase.ts +++ b/packages/scope-manager/src/definition/DefinitionBase.ts @@ -16,10 +16,6 @@ abstract class DefinitionBase< */ public readonly $id: number = generator(); - /** - * The type of the definition - * @public - */ public readonly type: TType; /** diff --git a/packages/scope-manager/src/scope/ScopeBase.ts b/packages/scope-manager/src/scope/ScopeBase.ts index 1cdb2c98586c..0cff4b1e8f86 100644 --- a/packages/scope-manager/src/scope/ScopeBase.ts +++ b/packages/scope-manager/src/scope/ScopeBase.ts @@ -107,9 +107,6 @@ function isStrictScope( return false; } -/** - * Register scope - */ function registerScope(scopeManager: ScopeManager, scope: Scope): void { scopeManager.scopes.push(scope); @@ -200,10 +197,6 @@ abstract class ScopeBase< * @public */ public readonly through: Reference[] = []; - /** - * The type of scope - * @public - */ public readonly type: TType; /** * Reference to the parent {@link Scope}. diff --git a/packages/typescript-estree/src/convert.ts b/packages/typescript-estree/src/convert.ts index 5dcde889e8dd..99b3da978f25 100644 --- a/packages/typescript-estree/src/convert.ts +++ b/packages/typescript-estree/src/convert.ts @@ -138,8 +138,6 @@ export class Converter { /** * Fixes the exports of the given ts.Node - * @param node the ts.Node - * @param result result * @returns the ESTreeNode with fixed exports */ private fixExports< @@ -750,8 +748,6 @@ export class Converter { * Converts a TypeScript node into an ESTree node. * The core of the conversion logic: * Identify and convert each relevant TypeScript SyntaxKind - * @param node the child ts.Node - * @param parent parentNode * @returns the converted ESTree node */ private convertNode(node: TSNode, parent: TSNode): TSESTree.Node | null { diff --git a/packages/typescript-estree/src/node-utils.ts b/packages/typescript-estree/src/node-utils.ts index a131e8043e34..811bed8fcad4 100644 --- a/packages/typescript-estree/src/node-utils.ts +++ b/packages/typescript-estree/src/node-utils.ts @@ -83,7 +83,6 @@ type DeclarationKind = TSESTree.VariableDeclaration['kind']; /** * Returns true if the given ts.Token is the assignment operator * @param operator the operator token - * @returns is assignment */ function isAssignmentOperator( operator: ts.BinaryOperatorToken, @@ -188,7 +187,6 @@ export function isComment(node: ts.Node): boolean { /** * Returns true if the given ts.Node is a JSDoc comment * @param node the TypeScript node - * @returns is JSDoc comment */ function isJSDocComment(node: ts.Node): node is ts.JSDoc { // eslint-disable-next-line deprecation/deprecation -- SyntaxKind.JSDoc was only added in TS4.7 so we can't use it yet diff --git a/packages/utils/src/eslint-utils/deepMerge.ts b/packages/utils/src/eslint-utils/deepMerge.ts index 85412ed399db..f6513944c1bd 100644 --- a/packages/utils/src/eslint-utils/deepMerge.ts +++ b/packages/utils/src/eslint-utils/deepMerge.ts @@ -2,7 +2,6 @@ type ObjectLike = Record; /** * Check if the variable contains an object strictly rejecting arrays - * @param obj an object * @returns `true` if obj is an object */ function isObjectNotArray(obj: unknown): obj is T { diff --git a/packages/utils/src/ts-eslint/CLIEngine.ts b/packages/utils/src/ts-eslint/CLIEngine.ts index 2e668b49bfcd..d0b19081d98f 100644 --- a/packages/utils/src/ts-eslint/CLIEngine.ts +++ b/packages/utils/src/ts-eslint/CLIEngine.ts @@ -15,7 +15,7 @@ declare class CLIEngineBase { /** * Add a plugin by passing its configuration - * @param name Name of the plugin. + * @param name Name (id) of the plugin. * @param pluginObject Plugin configuration object. */ addPlugin(name: string, pluginObject: Linter.Plugin): void; diff --git a/packages/utils/src/ts-eslint/ESLint.ts b/packages/utils/src/ts-eslint/ESLint.ts index 104d8f83765f..f7f556b653bc 100644 --- a/packages/utils/src/ts-eslint/ESLint.ts +++ b/packages/utils/src/ts-eslint/ESLint.ts @@ -49,7 +49,6 @@ declare class ESLintBase { * options.warnIgnored option is set along with the options.filePath option, this method returns a LintResult object. * In that case, the result may contain a warning that indicates the file was ignored. * @param code The source code text to check. - * @param options The options. * @returns The promise that will be fulfilled with an array of LintResult objects. This is an array (despite there * being only one lint result) in order to keep the interfaces between this and the eslint.lintFiles() * method similar. diff --git a/packages/utils/src/ts-eslint/RuleTester.ts b/packages/utils/src/ts-eslint/RuleTester.ts index 51b54fb7b5f3..f6883845e064 100644 --- a/packages/utils/src/ts-eslint/RuleTester.ts +++ b/packages/utils/src/ts-eslint/RuleTester.ts @@ -129,7 +129,6 @@ interface TestCaseError { /** * @param text a string describing the rule - * @param callback the test callback */ type RuleTesterTestFrameworkFunction = ( text: string, diff --git a/packages/utils/src/ts-eslint/SourceCode.ts b/packages/utils/src/ts-eslint/SourceCode.ts index 50ffd9000a7e..f23208a08aca 100644 --- a/packages/utils/src/ts-eslint/SourceCode.ts +++ b/packages/utils/src/ts-eslint/SourceCode.ts @@ -65,7 +65,6 @@ declare class TokenStore { * Gets the first `count` tokens of the given node. * @param node The AST node. * @param options The option object. If this is a number then it's `options.count`. If this is a function then it's `options.filter`. - * @returns Tokens. */ getFirstTokens( node: TSESTree.Node, @@ -109,7 +108,6 @@ declare class TokenStore { * Gets the last `count` tokens of the given node. * @param node The AST node. * @param options The option object. If this is a number then it's `options.count`. If this is a function then it's `options.filter`. - * @returns Tokens. */ getLastTokens( node: TSESTree.Node, @@ -183,7 +181,6 @@ declare class TokenStore { * Gets the `count` tokens that follows a given node or token. * @param node The AST node. * @param options The option object. If this is a number then it's `options.count`. If this is a function then it's `options.filter`. - * @returns Tokens. */ getTokensAfter( node: TSESTree.Node | TSESTree.Token, @@ -193,7 +190,6 @@ declare class TokenStore { * Gets the `count` tokens that precedes a given node or token. * @param node The AST node. * @param options The option object. If this is a number then it's `options.count`. If this is a function then it's `options.filter`. - * @returns Tokens. */ getTokensBefore( node: TSESTree.Node | TSESTree.Token, @@ -216,7 +212,6 @@ declare class TokenStore { declare class SourceCodeBase extends TokenStore { /** * Represents parsed source code. - * @param text The source code text. * @param ast The Program node of the AST representing the code. This AST should be created from the text that BOM was stripped. */ constructor(text: string, ast: SourceCode.Program); diff --git a/yarn.lock b/yarn.lock index 765726dc8bc6..9d6ef19d406b 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2897,6 +2897,17 @@ __metadata: languageName: node linkType: hard +"@es-joy/jsdoccomment@npm:~0.41.0": + version: 0.41.0 + resolution: "@es-joy/jsdoccomment@npm:0.41.0" + dependencies: + comment-parser: 1.4.1 + esquery: ^1.5.0 + jsdoc-type-pratt-parser: ~4.0.0 + checksum: cfe0714027ff8fa82dad8c84f75af3f6df9d6797d60c289b8d3c259c5375c134bd5ca630beba0daed3adceef01a74f19e05052018f6b66ad6a4f483adf599c39 + languageName: node + linkType: hard + "@esbuild/aix-ppc64@npm:0.19.10": version: 0.19.10 resolution: "@esbuild/aix-ppc64@npm:0.19.10" @@ -6100,6 +6111,7 @@ __metadata: eslint-plugin-eslint-plugin: ^5.1.0 eslint-plugin-import: ^2.27.5 eslint-plugin-jest: ^27.2.2 + eslint-plugin-jsdoc: ^46.9.1 eslint-plugin-jsx-a11y: ^6.7.1 eslint-plugin-react: ^7.32.2 eslint-plugin-react-hooks: ^4.6.0 @@ -6762,6 +6774,13 @@ __metadata: languageName: node linkType: hard +"are-docs-informative@npm:^0.0.2": + version: 0.0.2 + resolution: "are-docs-informative@npm:0.0.2" + checksum: 7a48ca90d66e29afebc4387d7029d86cfe97bad7e796c8e7de01309e02dcfc027250231c02d4ca208d2984170d09026390b946df5d3d02ac638ab35f74501c74 + languageName: node + linkType: hard + "are-we-there-yet@npm:^3.0.0": version: 3.0.0 resolution: "are-we-there-yet@npm:3.0.0" @@ -8210,6 +8229,13 @@ __metadata: languageName: node linkType: hard +"comment-parser@npm:1.4.1": + version: 1.4.1 + resolution: "comment-parser@npm:1.4.1" + checksum: e0f6f60c5139689c4b1b208ea63e0730d9195a778e90dd909205f74f00b39eb0ead05374701ec5e5c29d6f28eb778cd7bc41c1366ab1d271907f1def132d6bf1 + languageName: node + linkType: hard + "common-tags@npm:^1.8.0": version: 1.8.2 resolution: "common-tags@npm:1.8.2" @@ -10118,6 +10144,25 @@ __metadata: languageName: node linkType: hard +"eslint-plugin-jsdoc@npm:^46.9.1": + version: 46.9.1 + resolution: "eslint-plugin-jsdoc@npm:46.9.1" + dependencies: + "@es-joy/jsdoccomment": ~0.41.0 + are-docs-informative: ^0.0.2 + comment-parser: 1.4.1 + debug: ^4.3.4 + escape-string-regexp: ^4.0.0 + esquery: ^1.5.0 + is-builtin-module: ^3.2.1 + semver: ^7.5.4 + spdx-expression-parse: ^4.0.0 + peerDependencies: + eslint: ^7.0.0 || ^8.0.0 + checksum: c1307398f9cf79ad1479b7f2c08ffc150d2b4f9747880f6a0de2f34dc1b04ec34d01acbd69d0ed1a4d1e435dba6683bd1446b3ff89a2074e9c739e15d22c228f + languageName: node + linkType: hard + "eslint-plugin-jsx-a11y@npm:^6.7.1": version: 6.8.0 resolution: "eslint-plugin-jsx-a11y@npm:6.8.0" @@ -13640,6 +13685,13 @@ __metadata: languageName: node linkType: hard +"jsdoc-type-pratt-parser@npm:~4.0.0": + version: 4.0.0 + resolution: "jsdoc-type-pratt-parser@npm:4.0.0" + checksum: af0629c9517e484be778d8564440fec8de5b7610e0c9c88a3ba4554321364faf72b46689c8d8845faa12c0718437a9ed97e231977efc0f2d50e8a2dbad807eb3 + languageName: node + linkType: hard + "jsesc@npm:^2.5.1": version: 2.5.2 resolution: "jsesc@npm:2.5.2" @@ -18981,6 +19033,16 @@ __metadata: languageName: node linkType: hard +"spdx-expression-parse@npm:^4.0.0": + version: 4.0.0 + resolution: "spdx-expression-parse@npm:4.0.0" + dependencies: + spdx-exceptions: ^2.1.0 + spdx-license-ids: ^3.0.0 + checksum: 936be681fbf5edeec3a79c023136479f70d6edb3fd3875089ac86cd324c6c8c81add47399edead296d1d0af17ae5ce88c7f88885eb150b62c2ff6e535841ca6a + languageName: node + linkType: hard + "spdx-license-ids@npm:^3.0.0": version: 3.0.13 resolution: "spdx-license-ids@npm:3.0.13" From a3a4914600d27942f3cd4674f12e4949cfbd96c9 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sun, 4 Feb 2024 10:47:05 -0500 Subject: [PATCH 2/2] Review suggestions --- .../eslint-plugin/src/rules/adjacent-overload-signatures.ts | 3 --- packages/eslint-plugin/src/rules/member-ordering.ts | 1 + .../eslint-plugin/src/rules/space-before-function-paren.ts | 1 - 3 files changed, 1 insertion(+), 4 deletions(-) diff --git a/packages/eslint-plugin/src/rules/adjacent-overload-signatures.ts b/packages/eslint-plugin/src/rules/adjacent-overload-signatures.ts index e10a4c815448..4ffb10109536 100644 --- a/packages/eslint-plugin/src/rules/adjacent-overload-signatures.ts +++ b/packages/eslint-plugin/src/rules/adjacent-overload-signatures.ts @@ -127,9 +127,6 @@ export default createRule({ } } - /** - * @param {ASTNode} node the body to be inspected. - */ function checkBodyForOverloadMethods(node: RuleNode): void { const members = getMembers(node); diff --git a/packages/eslint-plugin/src/rules/member-ordering.ts b/packages/eslint-plugin/src/rules/member-ordering.ts index a972bf86b2ba..9bcaf896ee7d 100644 --- a/packages/eslint-plugin/src/rules/member-ordering.ts +++ b/packages/eslint-plugin/src/rules/member-ordering.ts @@ -632,6 +632,7 @@ function getRank( * public-instance-method. * If a lowest possible rank is a member group, a comma separated list of ranks is returned. * @param ranks the existing ranks in the object. + * @param target the minimum target rank to filter on. * @param order the current order to be validated. * @returns the name(s) of the lowest possible rank without dashes (-). */ diff --git a/packages/eslint-plugin/src/rules/space-before-function-paren.ts b/packages/eslint-plugin/src/rules/space-before-function-paren.ts index 2b2d8da18bde..f7c8c5ed2014 100644 --- a/packages/eslint-plugin/src/rules/space-before-function-paren.ts +++ b/packages/eslint-plugin/src/rules/space-before-function-paren.ts @@ -70,7 +70,6 @@ export default createRule({ /** * Determines whether a function has a name. - * @returns {boolean} Whether the function has a name. */ function isNamedFunction( node: