From 463ecf80459ad8f00a2dc458c19e5b42d2211b91 Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Sun, 18 Jul 2021 12:40:30 +0800 Subject: [PATCH] Chore: Update jsdoc plugin and tweak rules in effect --- .eslintrc.js | 18 +++++++- Makefile.js | 10 ++++- lib/cli-engine/cli-engine.js | 4 +- lib/cli-engine/file-enumerator.js | 2 +- lib/cli.js | 2 +- lib/config/rule-validator.js | 1 - lib/init/autoconfig.js | 6 +-- lib/linter/linter.js | 18 ++++---- lib/linter/report-translator.js | 24 +++++------ lib/linter/safe-emitter.js | 4 +- lib/rule-tester/rule-tester.js | 2 + lib/rules/indent.js | 12 +++--- lib/rules/no-useless-escape.js | 17 ++++---- lib/rules/object-shorthand.js | 4 -- lib/rules/utils/ast-utils.js | 5 ++- lib/rules/utils/lazy-loading-rule-map.js | 6 +-- lib/shared/config-validator.js | 10 ++--- lib/source-code/source-code.js | 8 ++-- package.json | 2 +- packages/eslint-config-eslint/default.yml | 49 ++++++++++++++++++---- packages/eslint-config-eslint/package.json | 2 +- tests/_utils/in-memory-fs.js | 10 ++--- tests/lib/cli-engine/cli-engine.js | 6 +-- tests/lib/cli-engine/file-enumerator.js | 6 +-- tests/lib/eslint/eslint.js | 4 +- tests/lib/linter/linter.js | 2 +- tests/lib/rules/utils/ast-utils.js | 2 - tools/eslint-fuzzer.js | 2 +- 28 files changed, 147 insertions(+), 91 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 668bc2747c54..a7f2da05c6ea 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -51,7 +51,7 @@ module.exports = { "plugin:eslint-plugin/recommended" ], parserOptions: { - ecmaVersion: 2020 + ecmaVersion: 2021 }, /* @@ -76,6 +76,22 @@ module.exports = { "internal-rules/multiline-comment-style": "error" }, overrides: [ + { + files: "**/no-useless-escape.md/*.js", + rules: { + "no-unused-expressions": "off" + } + }, + { + files: "**/ast-utils.md/*.js", + rules: { + "no-floating-decimal": "off", + "no-octal": "off", + "no-unused-expressions": "off", + "no-multi-spaces": "off", + semi: "off" + } + }, { files: ["lib/rules/*", "tools/internal-rules/*"], excludedFiles: ["index.js"], diff --git a/Makefile.js b/Makefile.js index 62b1d76669fb..024df2d220b8 100644 --- a/Makefile.js +++ b/Makefile.js @@ -957,14 +957,20 @@ function createConfigForPerformanceTest() { content.join("\n").to(PERF_ESLINTRC); } +/** + * @callback TimeCallback + * @param {?int[]} results + * @returns {void} + */ + /** * Calculates the time for each run for performance * @param {string} cmd cmd * @param {int} runs Total number of runs to do * @param {int} runNumber Current run number * @param {int[]} results Collection results from each run - * @param {Function} cb Function to call when everything is done - * @returns {int[]} calls the cb with all the results + * @param {TimeCallback} cb Function to call when everything is done + * @returns {void} calls the cb with all the results * @private */ function time(cmd, runs, runNumber, results, cb) { diff --git a/lib/cli-engine/cli-engine.js b/lib/cli-engine/cli-engine.js index ca298f9c356c..80572504732a 100644 --- a/lib/cli-engine/cli-engine.js +++ b/lib/cli-engine/cli-engine.js @@ -55,8 +55,8 @@ const validFixTypes = new Set(["problem", "suggestion", "layout"]); /** @typedef {import("../shared/types").Plugin} Plugin */ /** @typedef {import("../shared/types").RuleConf} RuleConf */ /** @typedef {import("../shared/types").Rule} Rule */ -/** @typedef {ReturnType} ConfigArray */ -/** @typedef {ReturnType} ExtractedConfig */ +/** @typedef {ReturnType} ConfigArray */ +/** @typedef {ReturnType} ExtractedConfig */ /** * The options to configure a CLI engine with. diff --git a/lib/cli-engine/file-enumerator.js b/lib/cli-engine/file-enumerator.js index ade28517b425..6fd1b1bb7291 100644 --- a/lib/cli-engine/file-enumerator.js +++ b/lib/cli-engine/file-enumerator.js @@ -60,7 +60,7 @@ const IGNORED_SILENTLY = 1; const IGNORED = 2; // For VSCode intellisense -/** @typedef {ReturnType} ConfigArray */ +/** @typedef {ReturnType} ConfigArray */ /** * @typedef {Object} FileEnumeratorOptions diff --git a/lib/cli.js b/lib/cli.js index f766764546cc..3be24bd44d11 100644 --- a/lib/cli.js +++ b/lib/cli.js @@ -127,7 +127,7 @@ function translateOptions({ /** * Count error messages. * @param {LintResult[]} results The lint results. - * @returns {{errorCount:number;warningCount:number}} The number of error messages. + * @returns {{errorCount:number, warningCount:number}} The number of error messages. */ function countErrors(results) { let errorCount = 0; diff --git a/lib/config/rule-validator.js b/lib/config/rule-validator.js index f162dd81a050..c438661b22fd 100644 --- a/lib/config/rule-validator.js +++ b/lib/config/rule-validator.js @@ -98,7 +98,6 @@ class RuleValidator { * A collection of compiled validators for rules that have already * been validated. * @type {WeakMap} - * @property validators */ this.validators = new WeakMap(); } diff --git a/lib/init/autoconfig.js b/lib/init/autoconfig.js index 054c538496f8..62f225af74a7 100644 --- a/lib/init/autoconfig.js +++ b/lib/init/autoconfig.js @@ -32,9 +32,9 @@ const MAX_CONFIG_COMBINATIONS = 17, // 16 combinations + 1 for severity only /** * Information about a rule configuration, in the context of a Registry. * @typedef {Object} registryItem - * @param {ruleConfig} config A valid configuration for the rule - * @param {number} specificity The number of elements in the ruleConfig array - * @param {number} errorCount The number of errors encountered when linting with the config + * @property {ruleConfig} config A valid configuration for the rule + * @property {number} specificity The number of elements in the ruleConfig array + * @property {number} errorCount The number of errors encountered when linting with the config */ /** diff --git a/lib/linter/linter.js b/lib/linter/linter.js index 4e80926a895e..e446add45c0c 100644 --- a/lib/linter/linter.js +++ b/lib/linter/linter.js @@ -46,8 +46,8 @@ const parserSymbol = Symbol.for("eslint.RuleTester.parser"); // Typedefs //------------------------------------------------------------------------------ -/** @typedef {InstanceType} ConfigArray */ -/** @typedef {InstanceType} ExtractedConfig */ +/** @typedef {InstanceType} ConfigArray */ +/** @typedef {InstanceType} ExtractedConfig */ /** @typedef {import("../shared/types").ConfigData} ConfigData */ /** @typedef {import("../shared/types").Environment} Environment */ /** @typedef {import("../shared/types").GlobalConf} GlobalConf */ @@ -56,17 +56,19 @@ const parserSymbol = Symbol.for("eslint.RuleTester.parser"); /** @typedef {import("../shared/types").Processor} Processor */ /** @typedef {import("../shared/types").Rule} Rule */ +/* eslint-disable jsdoc/valid-types -- https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser/issues/4#issuecomment-778805577 */ /** * @template T * @typedef {{ [P in keyof T]-?: T[P] }} Required */ +/* eslint-enable jsdoc/valid-types */ /** * @typedef {Object} DisableDirective - * @property {("disable"|"enable"|"disable-line"|"disable-next-line")} type - * @property {number} line - * @property {number} column - * @property {(string|null)} ruleId + * @property {("disable"|"enable"|"disable-line"|"disable-next-line")} type Type of directive + * @property {number} line The line number + * @property {number} column The column number + * @property {(string|null)} ruleId The rule ID */ /** @@ -94,12 +96,12 @@ const parserSymbol = Symbol.for("eslint.RuleTester.parser"); * @typedef {Object} ProcessorOptions * @property {(filename:string, text:string) => boolean} [filterCodeBlock] the * predicate function that selects adopt code blocks. - * @property {Processor["postprocess"]} [postprocess] postprocessor for report + * @property {Processor.postprocess} [postprocess] postprocessor for report * messages. If provided, this should accept an array of the message lists * for each code block returned from the preprocessor, apply a mapping to * the messages as appropriate, and return a one-dimensional array of * messages. - * @property {Processor["preprocess"]} [preprocess] preprocessor for source text. + * @property {Processor.preprocess} [preprocess] preprocessor for source text. * If provided, this should accept a string of source text, and return an * array of code blocks to lint. */ diff --git a/lib/linter/report-translator.js b/lib/linter/report-translator.js index 75005c16e580..838c8768eb2f 100644 --- a/lib/linter/report-translator.js +++ b/lib/linter/report-translator.js @@ -32,18 +32,18 @@ const interpolate = require("./interpolate"); /** * Information about the report * @typedef {Object} ReportInfo - * @property {string} ruleId - * @property {(0|1|2)} severity - * @property {(string|undefined)} message - * @property {(string|undefined)} [messageId] - * @property {number} line - * @property {number} column - * @property {(number|undefined)} [endLine] - * @property {(number|undefined)} [endColumn] - * @property {(string|null)} nodeType - * @property {string} source - * @property {({text: string, range: (number[]|null)}|null)} [fix] - * @property {Array<{text: string, range: (number[]|null)}|null>} [suggestions] + * @property {string} ruleId The rule ID + * @property {(0|1|2)} severity Severity of the error + * @property {(string|undefined)} message The message + * @property {(string|undefined)} [messageId] The message ID + * @property {number} line The line number + * @property {number} column The column number + * @property {(number|undefined)} [endLine] The ending line number + * @property {(number|undefined)} [endColumn] The ending column number + * @property {(string|null)} nodeType Typeo f node + * @property {string} source Source text + * @property {({text: string, range: (number[]|null)}|null)} [fix] The fix object + * @property {Array<{text: string, range: (number[]|null)}|null>} [suggestions] Suggestion info */ //------------------------------------------------------------------------------ diff --git a/lib/linter/safe-emitter.js b/lib/linter/safe-emitter.js index ab212230d398..f4837c1ddcf5 100644 --- a/lib/linter/safe-emitter.js +++ b/lib/linter/safe-emitter.js @@ -12,8 +12,8 @@ /** * An event emitter * @typedef {Object} SafeEmitter - * @property {function(eventName: string, listenerFunc: Function): void} on Adds a listener for a given event name - * @property {function(eventName: string, arg1?: any, arg2?: any, arg3?: any)} emit Emits an event with a given name. + * @property {(eventName: string, listenerFunc: Function) => void} on Adds a listener for a given event name + * @property {(eventName: string, arg1?: any, arg2?: any, arg3?: any) => void} emit Emits an event with a given name. * This calls all the listeners that were listening for that name, with `arg1`, `arg2`, and `arg3` as arguments. * @property {function(): string[]} eventNames Gets the list of event names that have registered listeners. */ diff --git a/lib/rule-tester/rule-tester.js b/lib/rule-tester/rule-tester.js index 2b5524923bea..5a6234b44e43 100644 --- a/lib/rule-tester/rule-tester.js +++ b/lib/rule-tester/rule-tester.js @@ -61,6 +61,7 @@ const parserSymbol = Symbol.for("eslint.RuleTester.parser"); /** @typedef {import("../shared/types").Parser} Parser */ +/* eslint-disable jsdoc/valid-types -- https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser/issues/4#issuecomment-778805577 */ /** * A test case that is expected to pass lint. * @typedef {Object} ValidTestCase @@ -103,6 +104,7 @@ const parserSymbol = Symbol.for("eslint.RuleTester.parser"); * @property {number} [endLine] The 1-based line number of the reported end location. * @property {number} [endColumn] The 1-based column number of the reported end location. */ +/* eslint-enable jsdoc/valid-types */ //------------------------------------------------------------------------------ // Private Members diff --git a/lib/rules/indent.js b/lib/rules/indent.js index 04f41db9e261..d03a6846ae41 100644 --- a/lib/rules/indent.js +++ b/lib/rules/indent.js @@ -263,7 +263,7 @@ class OffsetStorage { /** * Sets the offset column of token B to match the offset column of token A. - * **WARNING**: This matches a *column*, even if baseToken is not the first token on its line. In + * - **WARNING**: This matches a *column*, even if baseToken is not the first token on its line. In * most cases, `setDesiredOffset` should be used instead. * @param {Token} baseToken The first token * @param {Token} offsetToken The second token, whose offset should be matched to the first token @@ -352,11 +352,11 @@ class OffsetStorage { * Instead, the offset tree is represented as a collection of contiguous offset ranges in a file. For example, the following * list could represent the state of the offset tree at a given point: * - * * Tokens starting in the interval [0, 15) are aligned with the beginning of the file - * * Tokens starting in the interval [15, 30) are offset by 1 indent level from the `bar` token - * * Tokens starting in the interval [30, 43) are offset by 1 indent level from the `foo` token - * * Tokens starting in the interval [43, 820) are offset by 2 indent levels from the `bar` token - * * Tokens starting in the interval [820, ∞) are offset by 1 indent level from the `baz` token + * - Tokens starting in the interval [0, 15) are aligned with the beginning of the file + * - Tokens starting in the interval [15, 30) are offset by 1 indent level from the `bar` token + * - Tokens starting in the interval [30, 43) are offset by 1 indent level from the `foo` token + * - Tokens starting in the interval [43, 820) are offset by 2 indent levels from the `bar` token + * - Tokens starting in the interval [820, ∞) are offset by 1 indent level from the `baz` token * * The `setDesiredOffsets` methods inserts ranges like the ones above. The third line above would be inserted by using: * `setDesiredOffsets([30, 43], fooToken, 1);` diff --git a/lib/rules/no-useless-escape.js b/lib/rules/no-useless-escape.js index 512c93a8bc08..cf3ad4a8ce14 100644 --- a/lib/rules/no-useless-escape.js +++ b/lib/rules/no-useless-escape.js @@ -34,16 +34,17 @@ const REGEX_NON_CHARCLASS_ESCAPES = union(REGEX_GENERAL_ESCAPES, new Set("^/.$*+ * @returns {Object[]} A list of characters, each with info on escaping and whether they're in a character class. * @example * - * parseRegExp('a\\b[cd-]') + * parseRegExp("a\\b[cd-]"); * - * returns: + * // returns: * [ - * {text: 'a', index: 0, escaped: false, inCharClass: false, startsCharClass: false, endsCharClass: false}, - * {text: 'b', index: 2, escaped: true, inCharClass: false, startsCharClass: false, endsCharClass: false}, - * {text: 'c', index: 4, escaped: false, inCharClass: true, startsCharClass: true, endsCharClass: false}, - * {text: 'd', index: 5, escaped: false, inCharClass: true, startsCharClass: false, endsCharClass: false}, - * {text: '-', index: 6, escaped: false, inCharClass: true, startsCharClass: false, endsCharClass: false} - * ] + * { text: "a", index: 0, escaped: false, inCharClass: false, startsCharClass: false, endsCharClass: false }, + * { text: "b", index: 2, escaped: true, inCharClass: false, startsCharClass: false, endsCharClass: false }, + * { text: "c", index: 4, escaped: false, inCharClass: true, startsCharClass: true, endsCharClass: false }, + * { text: "d", index: 5, escaped: false, inCharClass: true, startsCharClass: false, endsCharClass: false }, + * { text: "-", index: 6, escaped: false, inCharClass: true, startsCharClass: false, endsCharClass: false } + * ]; + * */ function parseRegExp(regExpText) { const charList = []; diff --git a/lib/rules/object-shorthand.js b/lib/rules/object-shorthand.js index 3999ff8b99fb..020fe49a23f6 100644 --- a/lib/rules/object-shorthand.js +++ b/lib/rules/object-shorthand.js @@ -149,7 +149,6 @@ module.exports = { * @param {ASTNode} property Property AST node * @returns {boolean} True if the property can have a shorthand form * @private - * */ function canHaveShorthand(property) { return (property.kind !== "set" && property.kind !== "get" && property.type !== "SpreadElement" && property.type !== "SpreadProperty" && property.type !== "ExperimentalSpreadProperty"); @@ -169,7 +168,6 @@ module.exports = { * @param {ASTNode} property Property AST node * @returns {boolean} True if the property is considered shorthand, false if not. * @private - * */ function isShorthand(property) { @@ -182,7 +180,6 @@ module.exports = { * @param {ASTNode} property Property AST node * @returns {boolean} True if the key and value are named equally, false if not. * @private - * */ function isRedundant(property) { const value = property.value; @@ -202,7 +199,6 @@ module.exports = { * @param {ASTNode} node Property AST node * @param {boolean} checkRedundancy Whether to check longform redundancy * @returns {void} - * */ function checkConsistency(node, checkRedundancy) { diff --git a/lib/rules/utils/ast-utils.js b/lib/rules/utils/ast-utils.js index 6b853001132e..572f0d0840c1 100644 --- a/lib/rules/utils/ast-utils.js +++ b/lib/rules/utils/ast-utils.js @@ -1261,7 +1261,8 @@ module.exports = { * 5e1_000 // false * 5n // false * 1_000n // false - * '5' // false + * "5" // false + * */ isDecimalInteger(node) { return node.type === "Literal" && typeof node.value === "number" && @@ -1573,7 +1574,7 @@ module.exports = { return sourceCode.getText().slice(leftToken.range[0], rightToken.range[1]); }, - /* + /** * Determine if a node has a possibility to be an Error object * @param {ASTNode} node ASTNode to check * @returns {boolean} True if there is a chance it contains an Error obj diff --git a/lib/rules/utils/lazy-loading-rule-map.js b/lib/rules/utils/lazy-loading-rule-map.js index d426d85c59a7..7f116a2684fe 100644 --- a/lib/rules/utils/lazy-loading-rule-map.js +++ b/lib/rules/utils/lazy-loading-rule-map.js @@ -14,10 +14,10 @@ const debug = require("debug")("eslint:rules"); * const rules = new LazyLoadingRuleMap([ * ["eqeqeq", () => require("eqeqeq")], * ["semi", () => require("semi")], - * ["no-unused-vars", () => require("no-unused-vars")], - * ]) + * ["no-unused-vars", () => require("no-unused-vars")] + * ]); * - * rules.get("semi") // call `() => require("semi")` here. + * rules.get("semi"); // call `() => require("semi")` here. * * @extends {Map Rule>} */ diff --git a/lib/shared/config-validator.js b/lib/shared/config-validator.js index 03b32f1c9183..d38e60f71c74 100644 --- a/lib/shared/config-validator.js +++ b/lib/shared/config-validator.js @@ -152,7 +152,7 @@ function validateRuleOptions(rule, ruleId, options, source = null) { * Validates an environment object * @param {Object} environment The environment config object to validate. * @param {string} source The name of the configuration source to report in any errors. - * @param {function(envId:string): Object} [getAdditionalEnv] A map from strings to loaded environments. + * @param {(envId:string) => Object} [getAdditionalEnv] A map from strings to loaded environments. * @returns {void} */ function validateEnvironment( @@ -181,7 +181,7 @@ function validateEnvironment( * Validates a rules config object * @param {Object} rulesConfig The rules config object to validate. * @param {string} source The name of the configuration source to report in any errors. - * @param {function(ruleId:string): Object} getAdditionalRule A map from strings to loaded rules + * @param {(ruleId:string) => Object} getAdditionalRule A map from strings to loaded rules * @returns {void} */ function validateRules( @@ -225,7 +225,7 @@ function validateGlobals(globalsConfig, source = null) { * Validate `processor` configuration. * @param {string|undefined} processorName The processor name. * @param {string} source The name of config file. - * @param {function(id:string): Processor} getProcessor The getter of defined processors. + * @param {(id:string) => Processor} getProcessor The getter of defined processors. * @returns {void} */ function validateProcessor(processorName, source, getProcessor) { @@ -282,8 +282,8 @@ function validateConfigSchema(config, source = null) { * Validates an entire config object. * @param {Object} config The config object to validate. * @param {string} source The name of the configuration source to report in any errors. - * @param {function(ruleId:string): Object} [getAdditionalRule] A map from strings to loaded rules. - * @param {function(envId:string): Object} [getAdditionalEnv] A map from strings to loaded envs. + * @param {(ruleId:string) => Object} [getAdditionalRule] A map from strings to loaded rules. + * @param {(envId:string) => Object} [getAdditionalEnv] A map from strings to loaded envs. * @returns {void} */ function validate(config, source, getAdditionalRule, getAdditionalEnv) { diff --git a/lib/source-code/source-code.js b/lib/source-code/source-code.js index cc4524fa74c8..69135d98c02b 100644 --- a/lib/source-code/source-code.js +++ b/lib/source-code/source-code.js @@ -175,20 +175,20 @@ class SourceCode extends TokenStore { /** * The flag to indicate that the source code has Unicode BOM. - * @type boolean + * @type {boolean} */ this.hasBOM = (text.charCodeAt(0) === 0xFEFF); /** * The original text source code. * BOM was stripped from this text. - * @type string + * @type {string} */ this.text = (this.hasBOM ? text.slice(1) : text); /** * The parsed AST for the source code. - * @type ASTNode + * @type {ASTNode} */ this.ast = ast; @@ -223,7 +223,7 @@ class SourceCode extends TokenStore { /** * The source code split into lines according to ECMA-262 specification. * This is done to avoid each rule needing to do so separately. - * @type string[] + * @type {string[]} */ this.lines = []; this.lineStartIndices = [0]; diff --git a/package.json b/package.json index 0e64b624b966..3f48bacd7f05 100644 --- a/package.json +++ b/package.json @@ -98,7 +98,7 @@ "eslint-config-eslint": "file:packages/eslint-config-eslint", "eslint-plugin-eslint-plugin": "^3.2.0", "eslint-plugin-internal-rules": "file:tools/internal-rules", - "eslint-plugin-jsdoc": "^25.4.3", + "eslint-plugin-jsdoc": "^35.4.5", "eslint-plugin-node": "^11.1.0", "eslint-release": "^2.0.0", "eslump": "^3.0.0", diff --git a/packages/eslint-config-eslint/default.yml b/packages/eslint-config-eslint/default.yml index 38061e801556..cbdce1a0f36e 100644 --- a/packages/eslint-config-eslint/default.yml +++ b/packages/eslint-config-eslint/default.yml @@ -2,8 +2,7 @@ reportUnusedDisableDirectives: true extends: - "eslint:recommended" - "plugin:node/recommended" -plugins: - - "jsdoc" + - "plugin:jsdoc/recommended" settings: jsdoc: tagNamePreference: @@ -12,6 +11,11 @@ settings: class: "constructor" preferredTypes: object: "Object" +overrides: + - files: "**/*.md/*.js" + rules: + strict: "off" + rules: array-bracket-spacing: "error" array-callback-return: "error" @@ -43,23 +47,54 @@ rules: generator-star-spacing: "error" grouped-accessor-pairs: "error" guard-for-in: "error" + + # jsdoc non-recommended or configured rules + jsdoc/check-examples: "error" + # jsdoc/check-indentation: "error" + # jsdoc/check-line-alignment: "error" + jsdoc/check-syntax: "error" + jsdoc/check-values: ["error", { allowedLicenses: true }] + jsdoc/newline-after-description: ["error", "never"] + jsdoc/no-bad-blocks: "error" + jsdoc/require-asterisk-prefix: "error" + jsdoc/require-description: "error" + # jsdoc/require-file-overview: "error" + jsdoc/require-hyphen-before-param-description: ["error", "never"] + jsdoc/require-returns: ["error", { forceRequireReturn: true, forceReturnsWithAsync: true }] + # jsdoc/require-throws: "error" + jsdoc/tag-lines: ["error", "never", { tags: { example: { lines: "always" }, fileoverview: { lines: "any" } } }] + + # jsdoc disabled recommended rules + jsdoc/no-undefined-types: "off" + jsdoc/require-yields: "off" + # https://github.com/gajus/eslint-plugin-jsdoc/pull/769 + jsdoc/require-returns-check: "off" + + # jsdoc recommended rules turned from warnings into errors + jsdoc/check-access: "error" jsdoc/check-alignment: "error" jsdoc/check-param-names: "error" - jsdoc/check-syntax: "error" + jsdoc/check-property-names: "error" jsdoc/check-tag-names: "error" jsdoc/check-types: "error" + jsdoc/empty-tags: "error" jsdoc/implements-on-classes: "error" - jsdoc/newline-after-description: ["error", "never"] - jsdoc/require-description: "error" - jsdoc/require-hyphen-before-param-description: ["error", "never"] + jsdoc/multiline-blocks: "error" + jsdoc/no-multi-asterisks: "error" jsdoc/require-jsdoc: "error" jsdoc/require-param: "error" jsdoc/require-param-description: "error" jsdoc/require-param-name: "error" jsdoc/require-param-type: "error" - jsdoc/require-returns: ["error", { forceRequireReturn: true, forceReturnsWithAsync: true }] + jsdoc/require-property: "error" + jsdoc/require-property-description: "error" + jsdoc/require-property-name: "error" + jsdoc/require-property-type: "error" jsdoc/require-returns-description: "error" jsdoc/require-returns-type: "error" + jsdoc/require-yields-check: "error" + jsdoc/valid-types: "error" + key-spacing: ["error", { beforeColon: false, afterColon: true }] keyword-spacing: "error" lines-around-comment: ["error", { diff --git a/packages/eslint-config-eslint/package.json b/packages/eslint-config-eslint/package.json index a695451ea879..131cea596de2 100644 --- a/packages/eslint-config-eslint/package.json +++ b/packages/eslint-config-eslint/package.json @@ -20,7 +20,7 @@ "homepage": "https://eslint.org", "bugs": "https://github.com/eslint/eslint/issues/", "peerDependencies": { - "eslint-plugin-jsdoc": ">=22.1.0", + "eslint-plugin-jsdoc": ">=35.4.5", "eslint-plugin-node": ">=11.1.0" }, "keywords": [ diff --git a/tests/_utils/in-memory-fs.js b/tests/_utils/in-memory-fs.js index ddacfc7bec6f..a6909a881738 100644 --- a/tests/_utils/in-memory-fs.js +++ b/tests/_utils/in-memory-fs.js @@ -290,7 +290,7 @@ function defineInMemoryFs({ * @param {Object} options The options. * @param {() => string} [options.cwd] The current working directory. * @param {Object} [options.files] The initial files definition in the in-memory file system. - * @returns {{ fs: import("fs"), RelativeModuleResolver: import("../../lib/shared/relative-module-resolver"), ConfigArrayFactory: import("../../lib/cli-engine/config-array-factory")["ConfigArrayFactory"] }} The stubbed `ConfigArrayFactory` class. + * @returns {{ fs: import("fs"), RelativeModuleResolver: import("../../lib/shared/relative-module-resolver"), ConfigArrayFactory: import("../../lib/cli-engine/config-array-factory").ConfigArrayFactory }} The stubbed `ConfigArrayFactory` class. */ function defineConfigArrayFactoryWithInMemoryFileSystem({ cwd = process.cwd, @@ -374,7 +374,7 @@ function defineConfigArrayFactoryWithInMemoryFileSystem({ * @param {Object} options The options. * @param {() => string} [options.cwd] The current working directory. * @param {Object} [options.files] The initial files definition in the in-memory file system. - * @returns {{ fs: import("fs"), RelativeModuleResolver: import("../../../lib/shared/relative-module-resolver"), ConfigArrayFactory: import("../../../lib/cli-engine/config-array-factory")["ConfigArrayFactory"], CascadingConfigArrayFactory: import("../../../lib/cli-engine/cascading-config-array-factory")["CascadingConfigArrayFactory"] }} The stubbed `CascadingConfigArrayFactory` class. + * @returns {{ fs: import("fs"), RelativeModuleResolver: import("../../../lib/shared/relative-module-resolver"), ConfigArrayFactory: import("../../../lib/cli-engine/config-array-factory").ConfigArrayFactory, CascadingConfigArrayFactory: import("../../../lib/cli-engine/cascading-config-array-factory").CascadingConfigArrayFactory }} The stubbed `CascadingConfigArrayFactory` class. */ function defineCascadingConfigArrayFactoryWithInMemoryFileSystem({ cwd = process.cwd, @@ -409,7 +409,7 @@ function defineCascadingConfigArrayFactoryWithInMemoryFileSystem({ * @param {Object} options The options. * @param {() => string} [options.cwd] The current working directory. * @param {Object} [options.files] The initial files definition in the in-memory file system. - * @returns {{ fs: import("fs"), RelativeModuleResolver: import("../../../lib/shared/relative-module-resolver"), ConfigArrayFactory: import("../../../lib/cli-engine/config-array-factory")["ConfigArrayFactory"], CascadingConfigArrayFactory: import("../../../lib/cli-engine/cascading-config-array-factory")["CascadingConfigArrayFactory"], FileEnumerator: import("../../../lib/cli-engine/file-enumerator")["FileEnumerator"] }} The stubbed `FileEnumerator` class. + * @returns {{ fs: import("fs"), RelativeModuleResolver: import("../../../lib/shared/relative-module-resolver"), ConfigArrayFactory: import("../../../lib/cli-engine/config-array-factory").ConfigArrayFactory, CascadingConfigArrayFactory: import("../../../lib/cli-engine/cascading-config-array-factory").CascadingConfigArrayFactory, FileEnumerator: import("../../../lib/cli-engine/file-enumerator").FileEnumerator }} The stubbed `FileEnumerator` class. */ function defineFileEnumeratorWithInMemoryFileSystem({ cwd = process.cwd, @@ -448,7 +448,7 @@ function defineFileEnumeratorWithInMemoryFileSystem({ * @param {Object} options The options. * @param {() => string} [options.cwd] The current working directory. * @param {Object} [options.files] The initial files definition in the in-memory file system. - * @returns {{ fs: import("fs"), RelativeModuleResolver: import("../../../lib/shared/relative-module-resolver"), ConfigArrayFactory: import("../../../lib/cli-engine/config-array-factory")["ConfigArrayFactory"], CascadingConfigArrayFactory: import("../../../lib/cli-engine/cascading-config-array-factory")["CascadingConfigArrayFactory"], FileEnumerator: import("../../../lib/cli-engine/file-enumerator")["FileEnumerator"], CLIEngine: import("../../../lib/cli-engine/cli-engine")["CLIEngine"], getCLIEngineInternalSlots: import("../../../lib/cli-engine/cli-engine")["getCLIEngineInternalSlots"] }} The stubbed `CLIEngine` class. + * @returns {{ fs: import("fs"), RelativeModuleResolver: import("../../../lib/shared/relative-module-resolver"), ConfigArrayFactory: import("../../../lib/cli-engine/config-array-factory").ConfigArrayFactory, CascadingConfigArrayFactory: import("../../../lib/cli-engine/cascading-config-array-factory").CascadingConfigArrayFactory, FileEnumerator: import("../../../lib/cli-engine/file-enumerator").FileEnumerator, CLIEngine: import("../../../lib/cli-engine/cli-engine").CLIEngine, getCLIEngineInternalSlots: import("../../../lib/cli-engine/cli-engine").getCLIEngineInternalSlots }} The stubbed `CLIEngine` class. */ function defineCLIEngineWithInMemoryFileSystem({ cwd = process.cwd, @@ -492,7 +492,7 @@ function defineCLIEngineWithInMemoryFileSystem({ * @param {Object} options The options. * @param {() => string} [options.cwd] The current working directory. * @param {Object} [options.files] The initial files definition in the in-memory file system. - * @returns {{ fs: import("fs"), RelativeModuleResolver: import("../../lib/shared/relative-module-resolver"), ConfigArrayFactory: import("../../lib/cli-engine/config-array-factory")["ConfigArrayFactory"], CascadingConfigArrayFactory: import("../../lib/cli-engine/cascading-config-array-factory")["CascadingConfigArrayFactory"], FileEnumerator: import("../../lib/cli-engine/file-enumerator")["FileEnumerator"], ESLint: import("../../lib/eslint/eslint")["ESLint"], getCLIEngineInternalSlots: import("../../lib//eslint/eslint")["getESLintInternalSlots"] }} The stubbed `ESLint` class. + * @returns {{ fs: import("fs"), RelativeModuleResolver: import("../../lib/shared/relative-module-resolver"), ConfigArrayFactory: import("../../lib/cli-engine/config-array-factory").ConfigArrayFactory, CascadingConfigArrayFactory: import("../../lib/cli-engine/cascading-config-array-factory").CascadingConfigArrayFactory, FileEnumerator: import("../../lib/cli-engine/file-enumerator").FileEnumerator, ESLint: import("../../lib/eslint/eslint").ESLint, getCLIEngineInternalSlots: import("../../lib//eslint/eslint").getESLintInternalSlots }} The stubbed `ESLint` class. */ function defineESLintWithInMemoryFileSystem({ cwd = process.cwd, diff --git a/tests/lib/cli-engine/cli-engine.js b/tests/lib/cli-engine/cli-engine.js index 59243b0b7dcf..7af0129a9d25 100644 --- a/tests/lib/cli-engine/cli-engine.js +++ b/tests/lib/cli-engine/cli-engine.js @@ -40,10 +40,10 @@ describe("CLIEngine", () => { originalDir = process.cwd(), fixtureDir = path.resolve(fs.realpathSync(os.tmpdir()), "eslint/fixtures"); - /** @type {import("../../../lib/cli-engine")["CLIEngine"]} */ + /** @type {import("../../../lib/cli-engine").CLIEngine} */ let CLIEngine; - /** @type {import("../../../lib/cli-engine/cli-engine")["getCLIEngineInternalSlots"]} */ + /** @type {import("../../../lib/cli-engine/cli-engine").getCLIEngineInternalSlots} */ let getCLIEngineInternalSlots; /** @@ -777,7 +777,7 @@ describe("CLIEngine", () => { describe("executeOnFiles()", () => { - /** @type {InstanceType} */ + /** @type {InstanceType} */ let engine; it("should use correct parser when custom parser is specified", () => { diff --git a/tests/lib/cli-engine/file-enumerator.js b/tests/lib/cli-engine/file-enumerator.js index 1ea7a3bd2c4f..57f219a68003 100644 --- a/tests/lib/cli-engine/file-enumerator.js +++ b/tests/lib/cli-engine/file-enumerator.js @@ -54,7 +54,7 @@ describe("FileEnumerator", () => { describe("if 'lib/*.js' was given,", () => { - /** @type {Array<{config:(typeof import('../../../lib/cli-engine'))["ConfigArray"], filePath:string, ignored:boolean}>} */ + /** @type {Array<{config:(typeof import('../../../lib/cli-engine')).ConfigArray, filePath:string, ignored:boolean}>} */ let list; beforeEach(() => { @@ -86,7 +86,7 @@ describe("FileEnumerator", () => { describe("if 'lib/**/*.js' was given,", () => { - /** @type {Array<{config:(typeof import('../../../lib/cli-engine'))["ConfigArray"], filePath:string, ignored:boolean}>} */ + /** @type {Array<{config:(typeof import('../../../lib/cli-engine')).ConfigArray, filePath:string, ignored:boolean}>} */ let list; beforeEach(() => { @@ -129,7 +129,7 @@ describe("FileEnumerator", () => { describe("if 'lib/*.js' and 'test/*.js' were given,", () => { - /** @type {Array<{config:(typeof import('../../../lib/cli-engine'))["ConfigArray"], filePath:string, ignored:boolean}>} */ + /** @type {Array<{config:(typeof import('../../../lib/cli-engine')).ConfigArray, filePath:string, ignored:boolean}>} */ let list; beforeEach(() => { diff --git a/tests/lib/eslint/eslint.js b/tests/lib/eslint/eslint.js index c5a1b7360c06..ef1d77a49e17 100644 --- a/tests/lib/eslint/eslint.js +++ b/tests/lib/eslint/eslint.js @@ -41,7 +41,7 @@ describe("ESLint", () => { const originalDir = process.cwd(); const fixtureDir = path.resolve(fs.realpathSync(os.tmpdir()), "eslint/fixtures"); - /** @type {import("../../../lib/eslint")["ESLint"]} */ + /** @type {import("../../../lib/eslint").ESLint} */ let ESLint; /** @@ -863,7 +863,7 @@ describe("ESLint", () => { describe("lintFiles()", () => { - /** @type {InstanceType} */ + /** @type {InstanceType} */ let eslint; it("should use correct parser when custom parser is specified", async () => { diff --git a/tests/lib/linter/linter.js b/tests/lib/linter/linter.js index 522f9b197261..526662d69c86 100644 --- a/tests/lib/linter/linter.js +++ b/tests/lib/linter/linter.js @@ -54,7 +54,7 @@ const ESLINT_ENV = "eslint-env"; describe("Linter", () => { const filename = "filename.js"; - /** @type {InstanceType} */ + /** @type {InstanceType} */ let linter; beforeEach(() => { diff --git a/tests/lib/rules/utils/ast-utils.js b/tests/lib/rules/utils/ast-utils.js index d0ad27484316..9fb2762266d5 100644 --- a/tests/lib/rules/utils/ast-utils.js +++ b/tests/lib/rules/utils/ast-utils.js @@ -185,7 +185,6 @@ describe("ast-utils", () => { * Asserts the node is NOT a directive comment * @param {ASTNode} node node to assert * @returns {void} - * */ function assertFalse(node) { assert.isFalse(astUtils.isDirectiveComment(node)); @@ -195,7 +194,6 @@ describe("ast-utils", () => { * Asserts the node is a directive comment * @param {ASTNode} node node to assert * @returns {void} - * */ function assertTrue(node) { assert.isTrue(astUtils.isDirectiveComment(node)); diff --git a/tools/eslint-fuzzer.js b/tools/eslint-fuzzer.js index c9705200eaf2..6c5ed9b1bcb4 100644 --- a/tools/eslint-fuzzer.js +++ b/tools/eslint-fuzzer.js @@ -43,7 +43,7 @@ function sample(array) { * might also be passed other keys. * @param {boolean} [options.checkAutofixes=true] `true` if the fuzzer should check for autofix bugs. The fuzzer runs * roughly 4 times slower with autofix checking enabled. - * @param {function(number)} [options.progressCallback] A function that gets called once for each code sample, with the total number of errors found so far + * @param {function(number) : void} [options.progressCallback] A function that gets called once for each code sample, with the total number of errors found so far * @returns {Object[]} A list of problems found. Each problem has the following properties: * type (string): The type of problem. This is either "crash" (a rule crashes) or "autofix" (an autofix produces a syntax error) * text (string): The text that ESLint should be run on to reproduce the problem