Chore: Update jsdoc plugin and tweak rules in effect

.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"],

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) {

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<CascadingConfigArrayFactory["getConfigArrayForFile"]>} ConfigArray */
-/** @typedef {ReturnType<ConfigArray["extractConfig"]>} ExtractedConfig */
+/** @typedef {ReturnType<CascadingConfigArrayFactory.getConfigArrayForFile>} ConfigArray */
+/** @typedef {ReturnType<ConfigArray.extractConfig>} ExtractedConfig */
 
 /**
  * The options to configure a CLI engine with.

lib/cli-engine/file-enumerator.js

@@ -60,7 +60,7 @@ const IGNORED_SILENTLY = 1;
 const IGNORED = 2;
 
 // For VSCode intellisense
-/** @typedef {ReturnType<CascadingConfigArrayFactory["getConfigArrayForFile"]>} ConfigArray */
+/** @typedef {ReturnType<CascadingConfigArrayFactory.getConfigArrayForFile>} ConfigArray */
 
 /**
  * @typedef {Object} FileEnumeratorOptions

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;

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();
     }

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
  */
 
 /**

lib/linter/linter.js

@@ -46,8 +46,8 @@ const parserSymbol = Symbol.for("eslint.RuleTester.parser");
 // Typedefs
 //------------------------------------------------------------------------------
 
-/** @typedef {InstanceType<import("../cli-engine/config-array")["ConfigArray"]>} ConfigArray */
-/** @typedef {InstanceType<import("../cli-engine/config-array")["ExtractedConfig"]>} ExtractedConfig */
+/** @typedef {InstanceType<import("../cli-engine/config-array").ConfigArray>} ConfigArray */
+/** @typedef {InstanceType<import("../cli-engine/config-array").ExtractedConfig>} 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.
  */

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
  */
 
 //------------------------------------------------------------------------------

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.
  */

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

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);`

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 = [];

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) {
 

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

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<string, () => Rule>}
  */

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) {