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: pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy