diff --git a/.changeset/hip-boxes-speak.md b/.changeset/hip-boxes-speak.md new file mode 100644 index 00000000..e0cf87e3 --- /dev/null +++ b/.changeset/hip-boxes-speak.md @@ -0,0 +1,34 @@ +--- +'@cloudfour/eslint-plugin': major +--- + +Update `eslint-plugin-jsdoc` from `v39` to `v46` + +**Reconfigured Rules** + +The `@cloudfour/jsdoc/tag-lines` rule is now configured to enforce one blank line in JSDoc comments between the description of a function and the `@param`/other tags. + +For example, the blank line after the description is enforced here: + +```js +/** + * This is the description for the function, the blank line below this is enforced + * + * @param {string} name A parameter called name + */ +function someFunction(name) {} +``` + +**New Rules** + +- [`@cloudfour/jsdoc/informative-docs`](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/informative-docs.md#repos-sticky-header) +- [`@cloudfour/jsdoc/no-blank-block-descriptions`](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-blank-block-descriptions.md#repos-sticky-header) +- [`@cloudfour/jsdoc/no-blank-blocks`](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-blank-blocks.md#repos-sticky-header) + +**Deleted Rules** + +- [`@cloudfour/jsdoc/newline-after-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-newline-after-description) + +**Newly Enabled Rules** + +- [`@cloudfour/jsdoc/no-defaults`](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-defaults.md#repos-sticky-header) diff --git a/fixtures/eslint/lib/cli-engine/cascading-config-array-factory.js b/fixtures/eslint/lib/cli-engine/cascading-config-array-factory.js index a0a05911..1951981a 100644 --- a/fixtures/eslint/lib/cli-engine/cascading-config-array-factory.js +++ b/fixtures/eslint/lib/cli-engine/cascading-config-array-factory.js @@ -81,6 +81,7 @@ const internalSlotsMap = new WeakMap(); /** * Create the config array from `baseConfig` and `rulePaths`. + * * @param {CascadingConfigArrayFactoryInternalSlots} slots The slots. * @returns {ConfigArray} The config array of the base configs. */ @@ -139,6 +140,7 @@ function createBaseConfigArray({ /** * Create the config array from CLI options. + * * @param {CascadingConfigArrayFactoryInternalSlots} slots The slots. * @returns {ConfigArray} The config array of the base configs. */ @@ -192,6 +194,7 @@ class ConfigurationNotFoundError extends Error { class CascadingConfigArrayFactory { /** * Initialize this enumerator. + * * @param {CascadingConfigArrayFactoryOptions} options The options. */ constructor({ @@ -241,6 +244,7 @@ class CascadingConfigArrayFactory { /** * The path to the current working directory. * This is used by tests. + * * @type {string} */ get cwd() { @@ -253,6 +257,7 @@ class CascadingConfigArrayFactory { * Get the config array of a given file. * If `filePath` was not given, it returns the config which contains only * `baseConfigData` and `cliConfigData`. + * * @param {string} [filePath] The file path to a file. * @param {object} [options] The options. * @param {boolean} [options.ignoreNotFoundError] If `true` then it doesn't throw `ConfigurationNotFoundError`. @@ -278,6 +283,7 @@ class CascadingConfigArrayFactory { /** * Clear config cache. + * * @returns {void} */ clearCache() { @@ -290,6 +296,7 @@ class CascadingConfigArrayFactory { /** * Load and normalize config files from the ancestor directories. + * * @param {string} directoryPath The path to a leaf directory. * @param {boolean} configsExistInSubdirs `true` if configurations exist in subdirectories. * @returns {ConfigArray} The loaded config. @@ -376,6 +383,7 @@ class CascadingConfigArrayFactory { /** * Freeze and cache a given config. + * * @param {string} directoryPath The path to a directory as a cache key. * @param {ConfigArray} configArray The config array as a cache value. * @returns {ConfigArray} The `configArray` (frozen). @@ -392,6 +400,7 @@ class CascadingConfigArrayFactory { /** * Finalize a given config array. * Concatenate `--config` and other CLI options. + * * @param {ConfigArray} configArray The parent config array. * @param {string} directoryPath The path to the leaf directory to find config files. * @param {boolean} ignoreNotFoundError If `true` then it doesn't throw `ConfigurationNotFoundError`. diff --git a/fixtures/eslint/lib/cli-engine/config-array-factory.js b/fixtures/eslint/lib/cli-engine/config-array-factory.js index 00e1126e..5061aaaa 100644 --- a/fixtures/eslint/lib/cli-engine/config-array-factory.js +++ b/fixtures/eslint/lib/cli-engine/config-array-factory.js @@ -111,6 +111,7 @@ const internalSlotsMap = new WeakMap(); /** * Check if a given string is a file path. + * * @param {string} nameOrPath A module name or file path. * @returns {boolean} `true` if the `nameOrPath` is a file path. */ @@ -120,6 +121,7 @@ function isFilePath(nameOrPath) { /** * Convenience wrapper for synchronously reading file contents. + * * @param {string} filePath The filename to read. * @returns {string} The file contents, with the BOM removed. * @private @@ -130,6 +132,7 @@ function readFile(filePath) { /** * Loads a YAML configuration from a file. + * * @param {string} filePath The filename to load. * @returns {ConfigData} The configuration object from the file. * @throws {Error} If the file cannot be read. @@ -153,6 +156,7 @@ function loadYAMLConfigFile(filePath) { /** * Loads a JSON configuration from a file. + * * @param {string} filePath The filename to load. * @returns {ConfigData} The configuration object from the file. * @throws {Error} If the file cannot be read. @@ -177,6 +181,7 @@ function loadJSONConfigFile(filePath) { /** * Loads a legacy (.eslintrc) configuration from a file. + * * @param {string} filePath The filename to load. * @returns {ConfigData} The configuration object from the file. * @throws {Error} If the file cannot be read. @@ -202,6 +207,7 @@ function loadLegacyConfigFile(filePath) { /** * Loads a JavaScript configuration from a file. + * * @param {string} filePath The filename to load. * @returns {ConfigData} The configuration object from the file. * @throws {Error} If the file cannot be read. @@ -220,6 +226,7 @@ function loadJSConfigFile(filePath) { /** * Loads a configuration from a package.json file. + * * @param {string} filePath The filename to load. * @returns {ConfigData} The configuration object from the file. * @throws {Error} If the file cannot be read. @@ -247,6 +254,7 @@ function loadPackageJSONConfigFile(filePath) { /** * Loads a `.eslintignore` from a file. + * * @param {string} filePath The filename to load. * @returns {string[]} The ignore patterns from the file. * @private @@ -267,6 +275,7 @@ function loadESLintIgnoreFile(filePath) { /** * Creates an error to notify about a missing config to extend from. + * * @param {string} configName The name of the missing config. * @param {string} importerName The name of the config that imported the missing config * @returns {Error} The error object to throw @@ -285,6 +294,7 @@ function configMissingError(configName, importerName) { /** * Loads a configuration file regardless of the source. Inspects the file path * to determine the correctly way to load the config file. + * * @param {string} filePath The path to the configuration. * @returns {ConfigData|null} The configuration information. * @private @@ -317,6 +327,7 @@ function loadConfigFile(filePath) { /** * Write debug log. + * * @param {string} request The requested module name. * @param {string} relativeTo The file path to resolve the request relative to. * @param {string} filePath The resolved file path. @@ -345,6 +356,7 @@ function writeDebugLogForLoading(request, relativeTo, filePath) { /** * Create a new context with default values. + * * @param {string | undefined} cwd The current working directory. * @param {"config" | "ignore" | "implicit-processor" | undefined} providedType The type of the current configuration. Default is `"config"`. * @param {string | undefined} providedName The name of the current configuration. Default is the relative path from `cwd` to `filePath`. @@ -373,6 +385,7 @@ function createContext( * Normalize a given plugin. * - Ensure the object to have four properties: configs, environments, processors, and rules. * - Ensure the object to not have other properties. + * * @param {Plugin} plugin The plugin to normalize. * @returns {Plugin} The normalized plugin. */ @@ -395,6 +408,7 @@ function normalizePlugin(plugin) { class ConfigArrayFactory { /** * Initialize this instance. + * * @param {ConfigArrayFactoryOptions} [options] The map for additional plugins. */ constructor({ @@ -411,6 +425,7 @@ class ConfigArrayFactory { /** * Create `ConfigArray` instance from a config data. + * * @param {ConfigData|null} configData The config data to create. * @param {object} [options] The options. * @param {string} [options.basePath] The base path to resolve relative paths in `overrides[].files`, `overrides[].excludedFiles`, and `ignorePatterns`. @@ -432,6 +447,7 @@ class ConfigArrayFactory { /** * Load a config file. + * * @param {string} filePath The path to a config file. * @param {object} [options] The options. * @param {string} [options.basePath] The base path to resolve relative paths in `overrides[].files`, `overrides[].excludedFiles`, and `ignorePatterns`. @@ -447,6 +463,7 @@ class ConfigArrayFactory { /** * Load the config file on a given directory if exists. + * * @param {string} directoryPath The path to a directory. * @param {object} [options] The options. * @param {string} [options.basePath] The base path to resolve relative paths in `overrides[].files`, `overrides[].excludedFiles`, and `ignorePatterns`. @@ -489,6 +506,7 @@ class ConfigArrayFactory { /** * Check if a config file on a given directory exists or not. + * * @param {string} directoryPath The path to a directory. * @returns {string | null} The path to the found config file. If not found then null. */ @@ -515,6 +533,7 @@ class ConfigArrayFactory { /** * Load `.eslintignore` file. + * * @param {string} filePath The path to a `.eslintignore` file to load. * @returns {ConfigArray} Loaded config. An empty `ConfigArray` if any config doesn't exist. */ @@ -531,6 +550,7 @@ class ConfigArrayFactory { /** * Load `.eslintignore` file in the current working directory. + * * @returns {ConfigArray} Loaded config. An empty `ConfigArray` if any config doesn't exist. */ loadDefaultESLintIgnore() { @@ -571,6 +591,7 @@ class ConfigArrayFactory { /** * Load a given config file. + * * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @returns {IterableIterator} Loaded config. * @private @@ -581,6 +602,7 @@ class ConfigArrayFactory { /** * Normalize a given `.eslintignore` data to config array elements. + * * @param {string[]} ignorePatterns The patterns to ignore files. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @yields {ConfigArrayElement} The normalized config. @@ -601,6 +623,7 @@ class ConfigArrayFactory { /** * Normalize a given config to an array. + * * @param {ConfigData} configData The config data to normalize. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @returns {IterableIterator} The normalized config. @@ -613,6 +636,7 @@ class ConfigArrayFactory { /** * Normalize a given config to an array. + * * @param {ConfigData|OverrideConfigData} configData The config data to normalize. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @yields {ConfigArrayElement} The normalized config. @@ -650,6 +674,7 @@ class ConfigArrayFactory { /** * Normalize a given config to an array. + * * @param {ConfigData} configData The config data to normalize. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @yields {ConfigArrayElement} The normalized config. @@ -730,6 +755,7 @@ class ConfigArrayFactory { /** * Load configs of an element in `extends`. + * * @param {string} extendName The name of a base config. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @returns {IterableIterator} The normalized config. @@ -755,6 +781,7 @@ class ConfigArrayFactory { /** * Load configs of an element in `extends`. + * * @param {string} extendName The name of a base config. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @returns {IterableIterator} The normalized config. @@ -782,6 +809,7 @@ class ConfigArrayFactory { /** * Load configs of an element in `extends`. + * * @param {string} extendName The name of a base config. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @returns {IterableIterator} The normalized config. @@ -813,6 +841,7 @@ class ConfigArrayFactory { /** * Load configs of an element in `extends`. + * * @param {string} extendName The name of a base config. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @returns {IterableIterator} The normalized config. @@ -854,6 +883,7 @@ class ConfigArrayFactory { /** * Load given plugins. + * * @param {string[]} names The plugin names to load. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @returns {Record} The loaded parser. @@ -873,6 +903,7 @@ class ConfigArrayFactory { /** * Load a given parser. + * * @param {string} nameOrPath The package name or the path to a parser file. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @returns {DependentParser} The loaded parser. @@ -926,6 +957,7 @@ class ConfigArrayFactory { /** * Load a given plugin. + * * @param {string} name The plugin name to load. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @returns {DependentPlugin} The loaded plugin. @@ -1025,6 +1057,7 @@ class ConfigArrayFactory { /** * Take file expression processors as config array elements. + * * @param {Record} plugins The plugin definitions. * @param {ConfigArrayFactoryLoadingContext} ctx The loading context. * @yields {ConfigArrayElement} The config array elements of file expression processors. diff --git a/fixtures/eslint/lib/cli-engine/config-array/ignore-pattern.js b/fixtures/eslint/lib/cli-engine/config-array/ignore-pattern.js index 2e1ddaac..826f1760 100644 --- a/fixtures/eslint/lib/cli-engine/config-array/ignore-pattern.js +++ b/fixtures/eslint/lib/cli-engine/config-array/ignore-pattern.js @@ -46,6 +46,7 @@ const ignore = require('ignore'); /** * Get the path to the common ancestor directory of given paths. + * * @param {string[]} sourcePaths The paths to calculate the common ancestor. * @returns {string} The path to the common ancestor directory. */ @@ -77,6 +78,7 @@ function getCommonAncestorPath(sourcePaths) { /** * Make relative path. + * * @param {string} from The source path to get relative path. * @param {string} to The destination path to get relative path. * @returns {string} The relative path. @@ -93,6 +95,7 @@ function relative(from, to) { /** * Get the trailing slash if existed. + * * @param {string} filePath The path to check. * @returns {string} The trailing slash if existed. */ @@ -114,6 +117,7 @@ const DotPatterns = Object.freeze(['.*', '!.eslintrc.*', '!../']); class IgnorePattern { /** * The default patterns. + * * @type {string[]} */ static get DefaultPatterns() { @@ -122,6 +126,7 @@ class IgnorePattern { /** * Create the default predicate function. + * * @param {string} cwd The current working directory. * @returns {((filePath:string, dot:boolean) => boolean) & {basePath:string; patterns:string[]}} * The preficate function. @@ -135,6 +140,7 @@ class IgnorePattern { /** * Create the predicate function from multiple `IgnorePattern` objects. + * * @param {IgnorePattern[]} ignorePatterns The list of ignore patterns. * @returns {((filePath:string, dot?:boolean) => boolean) & {basePath:string; patterns:string[]}} * The preficate function. @@ -176,6 +182,7 @@ class IgnorePattern { /** * Initialize a new `IgnorePattern` instance. + * * @param {string[]} patterns The glob patterns that ignore to lint. * @param {string} basePath The base path of `patterns`. */ @@ -184,12 +191,14 @@ class IgnorePattern { /** * The glob patterns that ignore to lint. + * * @type {string[]} */ this.patterns = patterns; /** * The base path of `patterns`. + * * @type {string} */ this.basePath = basePath; @@ -199,6 +208,7 @@ class IgnorePattern { * * It's set `true` for `.eslintignore`, `package.json`, and `--ignore-path` for backward compatibility. * It's `false` as-is for `ignorePatterns` property in config files. + * * @type {boolean} */ this.loose = false; @@ -208,6 +218,7 @@ class IgnorePattern { * Get `patterns` as modified for a given base path. It modifies the * absolute paths in the patterns as prepending the difference of two base * paths. + * * @param {string} newBasePath The base path. * @returns {string[]} Modifired patterns. */ diff --git a/fixtures/eslint/lib/cli-engine/file-enumerator.js b/fixtures/eslint/lib/cli-engine/file-enumerator.js index 1cfcf7ea..c95ebca6 100644 --- a/fixtures/eslint/lib/cli-engine/file-enumerator.js +++ b/fixtures/eslint/lib/cli-engine/file-enumerator.js @@ -101,6 +101,7 @@ const internalSlotsMap = new WeakMap(); /** * Check if a string is a glob pattern or not. + * * @param {string} pattern A glob pattern. * @returns {boolean} `true` if the string is a glob pattern. */ @@ -110,6 +111,7 @@ function isGlobPattern(pattern) { /** * Get stats of a given path. + * * @param {string} filePath The path to target file. * @returns {fs.Stats|null} The stats. * @private @@ -129,6 +131,7 @@ function statSafeSync(filePath) { /** * Get filenames in a given path to a directory. + * * @param {string} directoryPath The path to target directory. * @returns {import("fs").Dirent[]} The filenames. * @private @@ -148,6 +151,7 @@ function readdirSafeSync(directoryPath) { /** * Create a `RegExp` object to detect extensions. + * * @param {string[] | null} extensions The extensions to create. * @returns {RegExp | null} The created `RegExp` object or null. */ @@ -203,6 +207,7 @@ class AllFilesIgnoredError extends Error { class FileEnumerator { /** * Initialize this enumerator. + * * @param {FileEnumeratorOptions} options The options. */ constructor({ @@ -226,6 +231,7 @@ class FileEnumerator { /** * Check if a given file is target or not. + * * @param {string} filePath The path to a candidate file. * @param {ConfigArray} [providedConfig] Optional. The configuration for the file. * @returns {boolean} `true` if the file is a target. @@ -255,6 +261,7 @@ class FileEnumerator { /** * Iterate files which are matched by given glob patterns. + * * @param {string|string[]} patternOrPatterns The glob patterns to iterate files. * @yields {FileAndConfig} The found files. */ @@ -319,6 +326,7 @@ class FileEnumerator { /** * Iterate files which are matched by a given glob pattern. + * * @param {string} pattern The glob pattern to iterate files. * @returns {IterableIterator} The found files. */ @@ -345,6 +353,7 @@ class FileEnumerator { /** * Iterate a file which is matched by a given path. + * * @param {string} filePath The path to the target file. * @returns {IterableIterator} The found files. * @private @@ -362,6 +371,7 @@ class FileEnumerator { /** * Iterate files in a given path. + * * @param {string} directoryPath The path to the target directory. * @param {boolean} dotfiles If `true` then it doesn't skip dot files by default. * @returns {IterableIterator} The found files. @@ -379,6 +389,7 @@ class FileEnumerator { /** * Iterate files which are matched by a given glob pattern. + * * @param {string} pattern The glob pattern to iterate files. * @param {boolean} dotfiles If `true` then it doesn't skip dot files by default. * @returns {IterableIterator} The found files. @@ -408,6 +419,7 @@ class FileEnumerator { /** * Iterate files in a given path. + * * @param {string} directoryPath The path to the target directory. * @param {object} options The options to iterate files. * @param {boolean} [options.dotfiles] If `true` then it doesn't skip dot files by default. @@ -486,6 +498,7 @@ class FileEnumerator { /** * Check if a given file should be ignored. + * * @param {string} filePath The path to a file to check. * @param {object} options Options * @param {ConfigArray} [options.config] The config for this file. diff --git a/fixtures/eslint/lib/init/config-initializer.js b/fixtures/eslint/lib/init/config-initializer.js index 322b98e7..f4f9bc09 100644 --- a/fixtures/eslint/lib/init/config-initializer.js +++ b/fixtures/eslint/lib/init/config-initializer.js @@ -37,6 +37,7 @@ const DEFAULT_ECMA_VERSION = 2018; /* istanbul ignore next: hard to test fs function */ /** * Create .eslintrc file in the current working directory + * * @param {object} config object that contains user's answers * @param {string} format The file format to write to. * @returns {void} @@ -69,6 +70,7 @@ function writeFile(config, format) { * Get the peer dependencies of the given module. * This adds the gotten value to cache at the first time, then reuses it. * In a process, this function is called twice, but `npmUtils.fetchPeerDependencies` needs to access network which is relatively slow. + * * @param {string} moduleName The module name to get. * @returns {object} The peer dependencies of the given module. * This object is the object of `peerDependencies` field of `package.json`. @@ -91,8 +93,9 @@ getPeerDependencies.cache = new Map(); /** * Return necessary plugins, configs, parsers, etc. based on the config + * * @param {object} config config object - * @param {boolean} [installESLint=true] If `false` is given, it does not install eslint. + * @param {boolean} [installESLint] If `false` is given, it does not install eslint. * @returns {string[]} An array of modules to be installed. */ function getModulesList(config, installESLint) { @@ -152,6 +155,7 @@ function getModulesList(config, installESLint) { * * Note: This clones the config object and returns a new config to avoid mutating * the original config parameter. + * * @param {object} answers answers received from inquirer * @param {object} config config object * @returns {object} config object with configured rules @@ -279,6 +283,7 @@ function configureRules(answers, config) { /** * Process user's answers and create config object + * * @param {object} answers answers received from inquirer * @returns {object} config object */ @@ -369,6 +374,7 @@ function processAnswers(answers) { /** * Get the version of the local ESLint. + * * @returns {string|null} The version. If the local ESLint was not found, returns null. */ function getLocalESLintVersion() { @@ -387,6 +393,7 @@ function getLocalESLintVersion() { /** * Get the shareable config name of the chosen style guide. + * * @param {object} answers The answers object. * @returns {string} The shareable config name. */ @@ -400,6 +407,7 @@ function getStyleGuideName(answers) { /** * Check whether the local ESLint version conflicts with the required version of the chosen shareable config. + * * @param {object} answers The answers object. * @returns {boolean} `true` if the local ESLint is found then it conflicts with the required version of the chosen shareable config. */ @@ -435,6 +443,7 @@ function hasESLintVersionConflict(answers) { /** * Install modules. + * * @param {string[]} modules Modules to be installed. * @returns {void} */ @@ -446,6 +455,7 @@ function installModules(modules) { /* istanbul ignore next: no need to test inquirer */ /** * Ask user to install modules. + * * @param {string[]} modules Array of modules to be installed. * @param {boolean} packageJsonExists Indicates if package.json is existed. * @returns {Promise} Answer that indicates if user wants to install. @@ -482,6 +492,7 @@ function askInstallModules(modules, packageJsonExists) { /* istanbul ignore next: no need to test inquirer */ /** * Ask use a few questions on command prompt + * * @returns {Promise} The promise with the result of the prompt */ function promptUser() { diff --git a/fixtures/eslint/lib/linter/apply-disable-directives.js b/fixtures/eslint/lib/linter/apply-disable-directives.js index fb97fe99..737908e5 100644 --- a/fixtures/eslint/lib/linter/apply-disable-directives.js +++ b/fixtures/eslint/lib/linter/apply-disable-directives.js @@ -9,6 +9,7 @@ const lodash = require('lodash'); /** * Compares the locations of two objects in a source file + * * @param {{line: number, column: number}} itemA The first object * @param {{line: number, column: number}} itemB The second object * @returns {number} A value less than 1 if itemA appears before itemB in the source file, greater than 1 if @@ -22,6 +23,7 @@ function compareLocations(itemA, itemB) { * This is the same as the exported function, except that it * doesn't handle disable-line and disable-next-line directives, and it always reports unused * disable directives. + * * @param {object} options options for applying directives. This is the same as the options * for the exported function, except that `reportUnusedDisableDirectives` is not supported * (this function always reports unused disable directives). @@ -113,6 +115,7 @@ function applyDirectives(options) { /** * Given a list of directive comments (i.e. metadata about eslint-disable and eslint-enable comments) and a list * of reported problems, determines which problems should be reported. + * * @param {object} options Information about directives and problems * @param {{ * type: ("disable"|"enable"|"disable-line"|"disable-next-line"), diff --git a/fixtures/eslint/lib/linter/node-event-generator.js b/fixtures/eslint/lib/linter/node-event-generator.js index c172758f..4e79e719 100644 --- a/fixtures/eslint/lib/linter/node-event-generator.js +++ b/fixtures/eslint/lib/linter/node-event-generator.js @@ -18,6 +18,7 @@ const lodash = require('lodash'); /** * An object describing an AST selector + * * @typedef {object} ASTSelector * @property {string} rawSelector The string that was parsed into this selector * @property {boolean} isExit `true` if this should be emitted when exiting the node rather than when entering @@ -34,6 +35,7 @@ const lodash = require('lodash'); /** * Gets the possible types of a selector + * * @param {object} parsedSelector An object (from esquery) describing the matching behavior of the selector * @returns {string[]|null} The node types that could possibly trigger this selector, or `null` if all node types could trigger it */ @@ -85,6 +87,7 @@ function getPossibleTypes(parsedSelector) { /** * Counts the number of class, pseudo-class, and attribute queries in this selector + * * @param {object} parsedSelector An object (from esquery) describing the selector's matching behavior * @returns {number} The number of class, pseudo-class, and attribute queries in this selector */ @@ -124,6 +127,7 @@ function countClassAttributes(parsedSelector) { /** * Counts the number of identifier queries in this selector + * * @param {object} parsedSelector An object (from esquery) describing the selector's matching behavior * @returns {number} The number of identifier queries */ @@ -160,6 +164,7 @@ function countIdentifiers(parsedSelector) { /** * Compares the specificity of two selector objects, with CSS-like rules. + * * @param {ASTSelector} selectorA An AST selector descriptor * @param {ASTSelector} selectorB Another AST selector descriptor * @returns {number} @@ -178,6 +183,7 @@ function compareSpecificity(selectorA, selectorB) { /** * Parses a raw selector string, and throws a useful error if parsing fails. + * * @param {string} rawSelector A raw AST selector * @returns {object} An object (from esquery) describing the matching behavior of this selector * @throws {Error} An error if the selector is invalid @@ -202,6 +208,7 @@ function tryParseSelector(rawSelector) { /** * Parses a raw selector string, and returns the parsed selector along with specificity and type information. + * * @param {string} rawSelector A raw AST selector * @returns {ASTSelector} A selector descriptor */ @@ -286,6 +293,7 @@ class NodeEventGenerator { /** * Checks a selector against a node, and emits it if it matches + * * @param {ASTNode} node The node to check * @param {ASTSelector} selector An AST selector descriptor * @returns {void} @@ -298,6 +306,7 @@ class NodeEventGenerator { /** * Applies all appropriate selectors to a node, in specificity order + * * @param {ASTNode} node The node to check * @param {boolean} isExit `false` if the node is currently being entered, `true` if it's currently being exited * @returns {void} @@ -340,6 +349,7 @@ class NodeEventGenerator { /** * Emits an event of entering AST node. + * * @param {ASTNode} node A node which was entered. * @returns {void} */ @@ -353,6 +363,7 @@ class NodeEventGenerator { /** * Emits an event of leaving AST node. + * * @param {ASTNode} node A node which was left. * @returns {void} */ diff --git a/fixtures/eslint/lib/rules/keyword-spacing.js b/fixtures/eslint/lib/rules/keyword-spacing.js index 3dc5768e..2fbc42af 100644 --- a/fixtures/eslint/lib/rules/keyword-spacing.js +++ b/fixtures/eslint/lib/rules/keyword-spacing.js @@ -52,6 +52,7 @@ const KEYS = [ /** * Checks whether or not a given token is a "Template" token ends with "${". + * * @param {Token} token A token to check. * @returns {boolean} `true` if the token is a "Template" token ends with "${". */ @@ -61,6 +62,7 @@ function isOpenParenOfTemplate(token) { /** * Checks whether or not a given token is a "Template" token starts with "}". + * * @param {Token} token A token to check. * @returns {boolean} `true` if the token is a "Template" token starts with "}". */ @@ -125,6 +127,7 @@ module.exports = { /** * Reports a given token if there are not space(s) before the token. + * * @param {Token} token A token to report. * @param {RegExp} pattern A pattern of the previous token to check. * @returns {void} @@ -152,6 +155,7 @@ module.exports = { /** * Reports a given token if there are space(s) before the token. + * * @param {Token} token A token to report. * @param {RegExp} pattern A pattern of the previous token to check. * @returns {void} @@ -179,6 +183,7 @@ module.exports = { /** * Reports a given token if there are not space(s) after the token. + * * @param {Token} token A token to report. * @param {RegExp} pattern A pattern of the next token to check. * @returns {void} @@ -206,6 +211,7 @@ module.exports = { /** * Reports a given token if there are space(s) after the token. + * * @param {Token} token A token to report. * @param {RegExp} pattern A pattern of the next token to check. * @returns {void} @@ -233,6 +239,7 @@ module.exports = { /** * Parses the option object and determines check methods for each keyword. + * * @param {object|undefined} options The option object to parse. * @returns {object} - Normalized option object. * Keys are keywords (there are for every keyword). @@ -272,6 +279,7 @@ module.exports = { /** * Reports a given token if usage of spacing followed by the token is * invalid. + * * @param {Token} token A token to report. * @param {RegExp} [pattern] Optional. A pattern of the previous * token to check. @@ -284,6 +292,7 @@ module.exports = { /** * Reports a given token if usage of spacing preceded by the token is * invalid. + * * @param {Token} token A token to report. * @param {RegExp} [pattern] Optional. A pattern of the next * token to check. @@ -295,6 +304,7 @@ module.exports = { /** * Reports a given token if usage of spacing around the token is invalid. + * * @param {Token} token A token to report. * @returns {void} */ @@ -306,6 +316,7 @@ module.exports = { /** * Reports the first token of a given node if the first token is a keyword * and usage of spacing around the token is invalid. + * * @param {ASTNode|null} node A node to report. * @returns {void} */ @@ -323,6 +334,7 @@ module.exports = { * * This is used for unary operators (e.g. `typeof`), `function`, and `super`. * Other rules are handling usage of spacing preceded by those keywords. + * * @param {ASTNode|null} node A node to report. * @returns {void} */ @@ -337,6 +349,7 @@ module.exports = { /** * Reports the previous token of a given node if the token is a keyword and * usage of spacing around the token is invalid. + * * @param {ASTNode|null} node A node to report. * @returns {void} */ @@ -351,6 +364,7 @@ module.exports = { /** * Reports `async` or `function` keywords of a given node if usage of * spacing around those keywords is invalid. + * * @param {ASTNode} node A node to report. * @returns {void} */ @@ -369,6 +383,7 @@ module.exports = { /** * Reports `class` and `extends` keywords of a given node if usage of * spacing around those keywords is invalid. + * * @param {ASTNode} node A node to report. * @returns {void} */ @@ -380,6 +395,7 @@ module.exports = { /** * Reports `if` and `else` keywords of a given node if usage of spacing * around those keywords is invalid. + * * @param {ASTNode} node A node to report. * @returns {void} */ @@ -391,6 +407,7 @@ module.exports = { /** * Reports `try`, `catch`, and `finally` keywords of a given node if usage * of spacing around those keywords is invalid. + * * @param {ASTNode} node A node to report. * @returns {void} */ @@ -403,6 +420,7 @@ module.exports = { /** * Reports `do` and `while` keywords of a given node if usage of spacing * around those keywords is invalid. + * * @param {ASTNode} node A node to report. * @returns {void} */ @@ -414,6 +432,7 @@ module.exports = { /** * Reports `for` and `in` keywords of a given node if usage of spacing * around those keywords is invalid. + * * @param {ASTNode} node A node to report. * @returns {void} */ @@ -425,6 +444,7 @@ module.exports = { /** * Reports `for` and `of` keywords of a given node if usage of spacing * around those keywords is invalid. + * * @param {ASTNode} node A node to report. * @returns {void} */ @@ -447,8 +467,9 @@ module.exports = { * * This rule handles the `*` token in module declarations. * - * import*as A from "./a"; /*error Expected space(s) after "import". - * error Expected space(s) before "as". + * import*as A from "./a"; /*error Expected space(s) after "import". + * error Expected space(s) before "as". + * * @param {ASTNode} node A node to report. * @returns {void} */ @@ -473,6 +494,7 @@ module.exports = { /** * Reports `as` keyword of a given node if usage of spacing around this * keyword is invalid. + * * @param {ASTNode} node A node to report. * @returns {void} */ @@ -485,6 +507,7 @@ module.exports = { /** * Reports `static`, `get`, and `set` keywords of a given node if usage of * spacing around those keywords is invalid. + * * @param {ASTNode} node A node to report. * @returns {void} */ @@ -524,6 +547,7 @@ module.exports = { /** * Reports `await` keyword of a given node if usage of spacing before * this keyword is invalid. + * * @param {ASTNode} node A node to report. * @returns {void} */ diff --git a/fixtures/eslint/lib/rules/padding-line-between-statements.js b/fixtures/eslint/lib/rules/padding-line-between-statements.js index aa49041d..c1d96ac0 100644 --- a/fixtures/eslint/lib/rules/padding-line-between-statements.js +++ b/fixtures/eslint/lib/rules/padding-line-between-statements.js @@ -25,6 +25,7 @@ const CJS_IMPORT = /^require\(/u; /** * Creates tester which check if a node starts with specific keyword. + * * @param {string} keyword The keyword to test. * @returns {object} the created tester. * @private @@ -38,6 +39,7 @@ function newKeywordTester(keyword) { /** * Creates tester which check if a node starts with specific keyword and spans a single line. + * * @param {string} keyword The keyword to test. * @returns {object} the created tester. * @private @@ -52,6 +54,7 @@ function newSinglelineKeywordTester(keyword) { /** * Creates tester which check if a node starts with specific keyword and spans multiple lines. + * * @param {string} keyword The keyword to test. * @returns {object} the created tester. * @private @@ -66,6 +69,7 @@ function newMultilineKeywordTester(keyword) { /** * Creates tester which check if a node is specific type. + * * @param {string} type The node type to test. * @returns {object} the created tester. * @private @@ -78,6 +82,7 @@ function newNodeTypeTester(type) { /** * Checks the given node is an expression statement of IIFE. + * * @param {ASTNode} node The node to check. * @returns {boolean} `true` if the node is an expression statement of IIFE. * @private @@ -99,6 +104,7 @@ function isIIFEStatement(node) { /** * Checks whether the given node is a block-like statement. * This checks the last token of the node is the closing brace of a block. + * * @param {SourceCode} sourceCode The source code to get tokens. * @param {ASTNode} node The node to check. * @returns {boolean} `true` if the node is a block-like statement. @@ -134,6 +140,7 @@ function isBlockLikeStatement(sourceCode, node) { /** * Check whether the given node is a directive or not. + * * @param {ASTNode} node The node to check. * @param {SourceCode} sourceCode The source code object to get tokens. * @returns {boolean} `true` if the node is a directive. @@ -152,6 +159,7 @@ function isDirective(node, sourceCode) { /** * Check whether the given node is a part of directive prologue or not. + * * @param {ASTNode} node The node to check. * @param {SourceCode} sourceCode The source code object to get tokens. * @returns {boolean} `true` if the node is a part of directive prologue. @@ -180,8 +188,9 @@ function isDirectivePrologue(node, sourceCode) { * If a semicolon is semicolon-less style's semicolon, this ignores it. * For example: * - * foo() - * ;[1, 2, 3].forEach(bar) + * foo() + * ;[1, 2, 3].forEach(bar) + * * @param {SourceCode} sourceCode The source code to get tokens. * @param {ASTNode} node The node to get. * @returns {Token} The actual last token. @@ -205,6 +214,7 @@ function getActualLastToken(sourceCode, node) { /** * This returns the concatenation of the first 2 captured strings. + * * @param {string} _ Unused. Whole matched string. * @param {string} trailingSpaces The trailing spaces of the first line. * @param {string} indentSpaces The indentation spaces of the last line. @@ -218,6 +228,7 @@ function replacerToRemovePaddingLines(_, trailingSpaces, indentSpaces) { /** * Check and report statements for `any` configuration. * It does nothing. + * * @returns {void} * @private */ @@ -228,6 +239,7 @@ function verifyForAny() {} * This autofix removes blank lines between the given 2 statements. * However, if comments exist between 2 blank lines, it does not remove those * blank lines automatically. + * * @param {RuleContext} context The rule context to report. * @param {ASTNode} _ Unused. The previous node to check. * @param {ASTNode} nextNode The next node to check. @@ -268,6 +280,7 @@ function verifyForNever(context, _, nextNode, paddingLines) { * This autofix inserts a blank line between the given 2 statements. * If the `prevNode` has trailing comments, it inserts a blank line after the * trailing comments. + * * @param {RuleContext} context The rule context to report. * @param {ASTNode} prevNode The previous node to check. * @param {ASTNode} nextNode The next node to check. @@ -297,16 +310,17 @@ function verifyForAlways(context, prevNode, nextNode, paddingLines) { * * For example: * - * foo(); // trailing comment. - * // comment. - * bar(); + * foo(); // trailing comment. + * // comment. + * bar(); * * Get fixed to: * - * foo(); // trailing comment. + * foo(); // trailing comment. + * + * // comment. + * bar(); * - * // comment. - * bar(); * @param {Token} token The token to check. * @returns {boolean} `true` if the token is not a trailing comment. * @private @@ -333,6 +347,7 @@ function verifyForAlways(context, prevNode, nextNode, paddingLines) { * Types of blank lines. * `any`, `never`, and `always` are defined. * Those have `verify` method to check and report statements. + * * @private */ const PaddingTypes = { @@ -344,6 +359,7 @@ const PaddingTypes = { /** * Types of statements. * Those have `test` method to check it matches to the given statement. + * * @private */ const StatementTypes = { @@ -483,6 +499,7 @@ module.exports = { /** * Processes to enter to new scope. * This manages the current previous statement. + * * @returns {void} * @private */ @@ -495,6 +512,7 @@ module.exports = { /** * Processes to exit from the current scope. + * * @returns {void} * @private */ @@ -504,6 +522,7 @@ module.exports = { /** * Checks whether the given node matches the given type. + * * @param {ASTNode} node The statement node to check. * @param {string|string[]} type The statement type to check. * @returns {boolean} `true` if the statement node matched the type. @@ -525,6 +544,7 @@ module.exports = { /** * Finds the last matched configure from configureList. + * * @param {ASTNode} prevNode The previous statement to match. * @param {ASTNode} nextNode The current statement to match. * @returns {object} The tester of the last matched configure. @@ -547,6 +567,7 @@ module.exports = { /** * Gets padding line sequences between the given 2 statements. * Comments are separators of the padding line sequences. + * * @param {ASTNode} prevNode The previous statement to count. * @param {ASTNode} nextNode The current statement to count. * @returns {Array} The array of token pairs. @@ -575,6 +596,7 @@ module.exports = { /** * Verify padding lines between the given node and the previous node. + * * @param {ASTNode} node The node to verify. * @returns {void} * @private @@ -606,6 +628,7 @@ module.exports = { /** * Verify padding lines between the given node and the previous node. * Then process to enter to new scope. + * * @param {ASTNode} node The node to verify. * @returns {void} * @private diff --git a/fixtures/eslint/lib/rules/prefer-arrow-callback.js b/fixtures/eslint/lib/rules/prefer-arrow-callback.js index b0838771..acac7b38 100644 --- a/fixtures/eslint/lib/rules/prefer-arrow-callback.js +++ b/fixtures/eslint/lib/rules/prefer-arrow-callback.js @@ -11,6 +11,7 @@ /** * Checks whether or not a given variable is a function name. + * * @param {eslint-scope.Variable} variable A variable to check. * @returns {boolean} `true` if the variable is a function name. */ @@ -20,6 +21,7 @@ function isFunctionName(variable) { /** * Checks whether or not a given MetaProperty node equals to a given value. + * * @param {ASTNode} node A MetaProperty node to check. * @param {string} metaName The name of `MetaProperty.meta`. * @param {string} propertyName The name of `MetaProperty.property`. @@ -31,6 +33,7 @@ function checkMetaProperty(node, metaName, propertyName) { /** * Gets the variable object of `arguments` which is defined implicitly. + * * @param {eslint-scope.Scope} scope A scope to get. * @returns {eslint-scope.Variable} The found variable object. */ @@ -54,6 +57,7 @@ function getVariableOfArguments(scope) { /** * Checks whether or not a given node is a callback. + * * @param {ASTNode} node A node to check. * @returns {object} * {boolean} retv.isCallback - `true` if the node is a callback. @@ -121,6 +125,7 @@ function getCallbackInfo(node) { * Checks whether a simple list of parameters contains any duplicates. This does not handle complex * parameter lists (e.g. with destructuring), since complex parameter lists are a SyntaxError with duplicate * parameter names anyway. Instead, it always returns `false` for complex parameter lists. + * * @param {ASTNode[]} paramsList The list of parameters for a function * @returns {boolean} `true` if the list of parameters contains any duplicates */ @@ -187,6 +192,7 @@ module.exports = { /** * Pushes new function scope with all `false` flags. + * * @returns {void} */ function enterScope() { @@ -195,6 +201,7 @@ module.exports = { /** * Pops a function scope from the stack. + * * @returns {{this: boolean, super: boolean, meta: boolean}} The information of the last scope. */ function exitScope() { diff --git a/fixtures/eslint/lib/rules/require-atomic-updates.js b/fixtures/eslint/lib/rules/require-atomic-updates.js index 8e3ac7f4..2b0a5660 100644 --- a/fixtures/eslint/lib/rules/require-atomic-updates.js +++ b/fixtures/eslint/lib/rules/require-atomic-updates.js @@ -7,6 +7,7 @@ /** * Make the map from identifiers to each reference. + * * @param {escope.Scope} scope The scope to get references. * @param {Map} [outReferenceMap] The map from identifier nodes to each reference object. * @returns {Map} `referenceMap`. @@ -28,6 +29,7 @@ function createReferenceMap(scope, outReferenceMap = new Map()) { /** * Get `reference.writeExpr` of a given reference. * If it's the read reference of MemberExpression in LHS, returns RHS in order to address `a.b = await a` + * * @param {escope.Reference} reference The reference to get. * @returns {Expression|null} The `reference.writeExpr`. */ @@ -58,6 +60,7 @@ function getWriteExpr(reference) { /** * Checks if an expression is a variable that can only be observed within the given function. + * * @param {Variable|null} variable The variable to check * @param {boolean} isMemberAccess If `true` then this is a member access. * @returns {boolean} `true` if the variable is local to the given function, and is never referenced in a closure. @@ -86,6 +89,7 @@ class SegmentInfo { /** * Initialize the segment information. + * * @param {PathSegment} segment The segment to initialize. * @returns {void} */ @@ -115,6 +119,7 @@ class SegmentInfo { /** * Mark a given variable as read on given segments. + * * @param {PathSegment[]} segments The segments that it read the variable on. * @param {string} variableName The variable name to be read. * @returns {void} @@ -131,6 +136,7 @@ class SegmentInfo { /** * Move `freshReadVariableNames` to `outdatedReadVariableNames`. + * * @param {PathSegment[]} segments The segments to process. * @returns {void} */ @@ -150,6 +156,7 @@ class SegmentInfo { /** * Check if a given variable is outdated on the current segments. + * * @param {PathSegment[]} segments The current segments. * @param {string} variableName The variable name to check. * @returns {boolean} `true` if the variable is outdated on the segments. diff --git a/fixtures/eslint/lib/rules/utils/ast-utils.js b/fixtures/eslint/lib/rules/utils/ast-utils.js index c4b07b14..1336a58f 100644 --- a/fixtures/eslint/lib/rules/utils/ast-utils.js +++ b/fixtures/eslint/lib/rules/utils/ast-utils.js @@ -50,6 +50,7 @@ const OCTAL_ESCAPE_PATTERN = /** * Checks reference if is non initializer and writable. + * * @param {Reference} reference A reference to check. * @param {int} index The index of the reference in the references. * @param {Reference[]} references The array that the reference belongs to. @@ -77,6 +78,7 @@ function isModifyingReference(reference, index, references) { /** * Checks whether the given string starts with uppercase or not. + * * @param {string} s The string to check. * @returns {boolean} `true` if the string starts with uppercase. */ @@ -86,6 +88,7 @@ function startsWithUpperCase(s) { /** * Checks whether or not a node is a constructor. + * * @param {ASTNode} node A function node to check. * @returns {boolean} Wehether or not a node is a constructor. */ @@ -95,6 +98,7 @@ function isES5Constructor(node) { /** * Finds a function node from ancestors of a node. + * * @param {ASTNode} node A start node to find. * @returns {Node|null} A found function node. */ @@ -115,6 +119,7 @@ function getUpperFunction(node) { * - ArrowFunctionExpression * - FunctionDeclaration * - FunctionExpression + * * @param {ASTNode|null} node A node to check. * @returns {boolean} `true` if the node is a function node. */ @@ -131,6 +136,7 @@ function isFunction(node) { * - ForOfStatement * - ForStatement * - WhileStatement + * * @param {ASTNode|null} node A node to check. * @returns {boolean} `true` if the node is a loop node. */ @@ -140,6 +146,7 @@ function isLoop(node) { /** * Checks whether the given node is in a loop or not. + * * @param {ASTNode} node The node to check. * @returns {boolean} `true` if the node is in a loop. */ @@ -159,6 +166,7 @@ function isInLoop(node) { /** * Checks whether or not a node is `null` or `undefined`. + * * @param {ASTNode} node A node to check. * @returns {boolean} Whether or not the node is a `null` or `undefined`. * @public @@ -173,6 +181,7 @@ function isNullOrUndefined(node) { /** * Checks whether or not a node is callee. + * * @param {ASTNode} node A node to check. * @returns {boolean} Whether or not the node is callee. */ @@ -182,6 +191,7 @@ function isCallee(node) { /** * Checks whether or not a node is `Reflect.apply`. + * * @param {ASTNode} node A node to check. * @returns {boolean} Whether or not the node is a `Reflect.apply`. */ @@ -198,6 +208,7 @@ function isReflectApply(node) { /** * Checks whether or not a node is `Array.from`. + * * @param {ASTNode} node A node to check. * @returns {boolean} Whether or not the node is a `Array.from`. */ @@ -214,6 +225,7 @@ function isArrayFromMethod(node) { /** * Checks whether or not a node is a method which has `thisArg`. + * * @param {ASTNode} node A node to check. * @returns {boolean} Whether or not the node is a method which has `thisArg`. */ @@ -233,6 +245,7 @@ function isMethodWhichHasThisArg(node) { /** * Creates the negate function of the given function. + * * @param {() => void} f The function to negate. * @returns {() => void} Negated function. */ @@ -242,6 +255,7 @@ function negate(f) { /** * Checks whether or not a node has a `@this` tag in its comments. + * * @param {ASTNode} node A node to check. * @param {SourceCode} sourceCode A SourceCode instance to get comments. * @returns {boolean} Whether or not the node has a `@this` tag in its comments. @@ -264,6 +278,7 @@ function hasJSDocThisTag(node, sourceCode) { /** * Determines if a node is surrounded by parentheses. + * * @param {SourceCode} sourceCode The ESLint source code object * @param {ASTNode} node The node to be checked. * @returns {boolean} True if the node is parenthesised. @@ -284,6 +299,7 @@ function isParenthesised(sourceCode, node) { /** * Checks if the given token is an arrow token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is an arrow token. */ @@ -293,6 +309,7 @@ function isArrowToken(token) { /** * Checks if the given token is a comma token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is a comma token. */ @@ -302,6 +319,7 @@ function isCommaToken(token) { /** * Checks if the given token is a dot token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is a dot token. */ @@ -311,6 +329,7 @@ function isDotToken(token) { /** * Checks if the given token is a semicolon token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is a semicolon token. */ @@ -320,6 +339,7 @@ function isSemicolonToken(token) { /** * Checks if the given token is a colon token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is a colon token. */ @@ -329,6 +349,7 @@ function isColonToken(token) { /** * Checks if the given token is an opening parenthesis token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is an opening parenthesis token. */ @@ -338,6 +359,7 @@ function isOpeningParenToken(token) { /** * Checks if the given token is a closing parenthesis token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is a closing parenthesis token. */ @@ -347,6 +369,7 @@ function isClosingParenToken(token) { /** * Checks if the given token is an opening square bracket token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is an opening square bracket token. */ @@ -356,6 +379,7 @@ function isOpeningBracketToken(token) { /** * Checks if the given token is a closing square bracket token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is a closing square bracket token. */ @@ -365,6 +389,7 @@ function isClosingBracketToken(token) { /** * Checks if the given token is an opening brace token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is an opening brace token. */ @@ -374,6 +399,7 @@ function isOpeningBraceToken(token) { /** * Checks if the given token is a closing brace token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is a closing brace token. */ @@ -383,6 +409,7 @@ function isClosingBraceToken(token) { /** * Checks if the given token is a comment token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is a comment token. */ @@ -394,6 +421,7 @@ function isCommentToken(token) { /** * Checks if the given token is a keyword token or not. + * * @param {Token} token The token to check. * @returns {boolean} `true` if the token is a keyword token. */ @@ -403,6 +431,7 @@ function isKeywordToken(token) { /** * Gets the `(` token of the given function node. + * * @param {ASTNode} node The function node to get. * @param {SourceCode} sourceCode The source code object to get tokens. * @returns {Token} `(` token. @@ -415,6 +444,7 @@ function getOpeningParenOfParams(node, sourceCode) { /** * Checks whether or not the tokens of two given nodes are same. + * * @param {ASTNode} left A node 1 to compare. * @param {ASTNode} right A node 2 to compare. * @param {SourceCode} sourceCode The ESLint source code object. @@ -453,6 +483,7 @@ module.exports = { /** * Determines whether two adjacent tokens are on the same line. + * * @param {object} left The left token object. * @param {object} right The right token object. * @returns {boolean} Whether or not the tokens are on the same line. @@ -500,6 +531,7 @@ module.exports = { /** * Checks whether or not a given node is a string literal. + * * @param {ASTNode} node A node to check. * @returns {boolean} `true` if the node is a string literal. */ @@ -520,6 +552,7 @@ module.exports = { * - ForStatement * - SwitchStatement * - WhileStatement + * * @param {ASTNode} node A node to check. * @returns {boolean} `true` if the node is breakable. */ @@ -529,6 +562,7 @@ module.exports = { /** * Gets references which are non initializer and writable. + * * @param {Reference[]} references An array of references. * @returns {Reference[]} An array of only references which are non initializer and writable. * @public @@ -539,6 +573,7 @@ module.exports = { /** * Validate that a string passed in is surrounded by the specified character + * * @param {string} val The text to check. * @param {string} character The character to see if it's surrounded by. * @returns {boolean} True if the text is surrounded by the character, false if not. @@ -550,6 +585,7 @@ module.exports = { /** * Returns whether the provided node is an ESLint directive comment or not + * * @param {Line|Block} node The comment token to be checked * @returns {boolean} `true` if the node is an ESLint directive comment */ @@ -568,10 +604,11 @@ module.exports = { /** * Gets the trailing statement of a given node. * - * if (code) - * consequent; + * if (code) + * consequent; * * When taking this `IfStatement`, returns `consequent;` statement. + * * @param {ASTNode} A node to get. * @returns {ASTNode|null} The trailing statement's node. */ @@ -579,6 +616,7 @@ module.exports = { /** * Finds the variable by a given name in a given scope and its upper scopes. + * * @param {eslint-scope.Scope} initScope A scope to start find. * @param {string} name A variable name to find. * @returns {eslint-scope.Variable|null} A found variable or `null`. @@ -605,7 +643,7 @@ module.exports = { * First, this checks the node: * * - The function name does not start with uppercase. It's a convention to capitalize the names - * of constructor functions. This check is not performed if `capIsConstructor` is set to `false`. + * of constructor functions. This check is not performed if `capIsConstructor` is set to `false`. * - The function does not have a JSDoc comment that has a @this tag. * * Next, this checks the location of the node. @@ -613,14 +651,15 @@ module.exports = { * * - The location is not on an object literal. * - The location is not assigned to a variable which starts with an uppercase letter. Applies to anonymous - * functions only, as the name of the variable is considered to be the name of the function in this case. - * This check is not performed if `capIsConstructor` is set to `false`. + * functions only, as the name of the variable is considered to be the name of the function in this case. + * This check is not performed if `capIsConstructor` is set to `false`. * - The location is not on an ES2015 class. * - Its `bind`/`call`/`apply` method is not called directly. * - The function is not a callback of array methods (such as `.forEach()`) if `thisArg` is given. + * * @param {ASTNode} node A function node to check. * @param {SourceCode} sourceCode A SourceCode instance to get comments. - * @param {boolean} [capIsConstructor = true] `false` disables the assumption that functions which name starts + * @param {boolean} [capIsConstructor] `false` disables the assumption that functions which name starts * with an uppercase or are assigned to a variable which name starts with an uppercase are constructors. * @returns {boolean} The function node is the default `this` binding. */ @@ -799,6 +838,7 @@ module.exports = { /** * Get the precedence level based on the node type + * * @param {ASTNode} node node to evaluate * @returns {int} precedence level * @private @@ -910,6 +950,7 @@ module.exports = { /** * Checks whether the given node is an empty block node or not. + * * @param {ASTNode|null} node The node to check. * @returns {boolean} `true` if the node is an empty block. */ @@ -921,6 +962,7 @@ module.exports = { /** * Checks whether the given node is an empty function node or not. + * * @param {ASTNode|null} node The node to check. * @returns {boolean} `true` if the node is an empty function. */ @@ -934,6 +976,7 @@ module.exports = { * * This function returns a `string` value for all `Literal` nodes and simple `TemplateLiteral` nodes only. * In all other cases, this function returns `null`. + * * @param {ASTNode} node Expression node. * @returns {string|null} String value if it can be determined. Otherwise, `null`. */ @@ -982,25 +1025,26 @@ module.exports = { * * For examples: * - * a.b // => "b" - * a["b"] // => "b" - * a['b'] // => "b" - * a[`b`] // => "b" - * a[100] // => "100" - * a[b] // => null - * a["a" + "b"] // => null - * a[tag`b`] // => null - * a[`${b}`] // => null + * a.b // => "b" + * a["b"] // => "b" + * a['b'] // => "b" + * a[`b`] // => "b" + * a[100] // => "100" + * a[b] // => null + * a["a" + "b"] // => null + * a[tag`b`] // => null + * a[`${b}`] // => null + * + * let a = {b: 1} // => "b" + * let a = {["b"]: 1} // => "b" + * let a = {['b']: 1} // => "b" + * let a = {[`b`]: 1} // => "b" + * let a = {[100]: 1} // => "100" + * let a = {[b]: 1} // => null + * let a = {["a" + "b"]: 1} // => null + * let a = {[tag`b`]: 1} // => null + * let a = {[`${b}`]: 1} // => null * - * let a = {b: 1} // => "b" - * let a = {["b"]: 1} // => "b" - * let a = {['b']: 1} // => "b" - * let a = {[`b`]: 1} // => "b" - * let a = {[100]: 1} // => "100" - * let a = {[b]: 1} // => null - * let a = {["a" + "b"]: 1} // => null - * let a = {[tag`b`]: 1} // => null - * let a = {[`${b}`]: 1} // => null * @param {ASTNode} node The node to get. * @returns {string|null} The property name if static. Otherwise, null. */ @@ -1035,6 +1079,7 @@ module.exports = { /** * Get directives from directive prologue of a Program or Function node. + * * @param {ASTNode} node The node to check. * @returns {ASTNode[]} The directives found in the directive prologue. */ @@ -1073,6 +1118,7 @@ module.exports = { /** * Determines whether this node is a decimal integer literal. If a node is a decimal integer literal, a dot added * after the node will be parsed as a decimal point, rather than a property-access dot. + * * @param {ASTNode} node The node to check. * @returns {boolean} `true` if this node is a decimal integer. * @example @@ -1099,6 +1145,7 @@ module.exports = { /** * Determines whether this token is a decimal integer numeric token. * This is similar to isDecimalInteger(), but for tokens. + * * @param {Token} token The token to check. * @returns {boolean} `true` if this token is a decimal integer. */ @@ -1153,6 +1200,7 @@ module.exports = { * - `class A { static async foo() {} }` .... `static async method 'foo'` * - `class A { static get foo() {} }` ...... `static getter 'foo'` * - `class A { static set foo(a) {} }` ..... `static setter 'foo'` + * * @param {ASTNode} node The function node to get. * @returns {string} The name and kind of the function node. */ @@ -1210,89 +1258,90 @@ module.exports = { * Gets the location of the given function node for reporting. * * - `function foo() {}` - * ^^^^^^^^^^^^ + * ^^^^^^^^^^^^ * - `(function foo() {})` - * ^^^^^^^^^^^^ + * ^^^^^^^^^^^^ * - `(function() {})` - * ^^^^^^^^ + * ^^^^^^^^ * - `function* foo() {}` - * ^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^ * - `(function* foo() {})` - * ^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^ * - `(function*() {})` - * ^^^^^^^^^ + * ^^^^^^^^^ * - `() => {}` - * ^^ + * ^^ * - `async () => {}` - * ^^ + * ^^ * - `({ foo: function foo() {} })` - * ^^^^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^^^^ * - `({ foo: function() {} })` - * ^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^ * - `({ ['foo']: function() {} })` - * ^^^^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^^^^ * - `({ [foo]: function() {} })` - * ^^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^^ * - `({ foo() {} })` - * ^^^ + * ^^^ * - `({ foo: function* foo() {} })` - * ^^^^^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^^^^^ * - `({ foo: function*() {} })` - * ^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^ * - `({ ['foo']: function*() {} })` - * ^^^^^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^^^^^ * - `({ [foo]: function*() {} })` - * ^^^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^^^ * - `({ *foo() {} })` - * ^^^^ + * ^^^^ * - `({ foo: async function foo() {} })` - * ^^^^^^^^^^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^^^^^^^^^^ * - `({ foo: async function() {} })` - * ^^^^^^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^^^^^^ * - `({ ['foo']: async function() {} })` - * ^^^^^^^^^^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^^^^^^^^^^ * - `({ [foo]: async function() {} })` - * ^^^^^^^^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^^^^^^^^ * - `({ async foo() {} })` - * ^^^^^^^^^ + * ^^^^^^^^^ * - `({ get foo() {} })` - * ^^^^^^^ + * ^^^^^^^ * - `({ set foo(a) {} })` - * ^^^^^^^ + * ^^^^^^^ * - `class A { constructor() {} }` - * ^^^^^^^^^^^ + * ^^^^^^^^^^^ * - `class A { foo() {} }` - * ^^^ + * ^^^ * - `class A { *foo() {} }` - * ^^^^ + * ^^^^ * - `class A { async foo() {} }` - * ^^^^^^^^^ + * ^^^^^^^^^ * - `class A { ['foo']() {} }` - * ^^^^^^^ + * ^^^^^^^ * - `class A { *['foo']() {} }` - * ^^^^^^^^ + * ^^^^^^^^ * - `class A { async ['foo']() {} }` - * ^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^ * - `class A { [foo]() {} }` - * ^^^^^ + * ^^^^^ * - `class A { *[foo]() {} }` - * ^^^^^^ + * ^^^^^^ * - `class A { async [foo]() {} }` - * ^^^^^^^^^^^ + * ^^^^^^^^^^^ * - `class A { get foo() {} }` - * ^^^^^^^ + * ^^^^^^^ * - `class A { set foo(a) {} }` - * ^^^^^^^ + * ^^^^^^^ * - `class A { static foo() {} }` - * ^^^^^^^^^^ + * ^^^^^^^^^^ * - `class A { static *foo() {} }` - * ^^^^^^^^^^^ + * ^^^^^^^^^^^ * - `class A { static async foo() {} }` - * ^^^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^^^ * - `class A { static get foo() {} }` - * ^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^ * - `class A { static set foo(a) {} }` - * ^^^^^^^^^^^^^^ + * ^^^^^^^^^^^^^^ + * * @param {ASTNode} node The function node to get. * @param {SourceCode} sourceCode The source code object to get tokens. * @returns {string} The location of the function node for reporting. @@ -1326,6 +1375,7 @@ module.exports = { /** * Gets next location when the result is not out of bound, otherwise returns null. + * * @param {SourceCode} sourceCode The sourceCode * @param {{line: number, column: number}} location The location * @returns {{line: number, column: number} | null} Next location @@ -1344,6 +1394,7 @@ module.exports = { /** * Gets the parenthesized text of a node. This is similar to sourceCode.getText(node), but it also includes any parentheses * surrounding the node. + * * @param {SourceCode} sourceCode The source code object * @param {ASTNode} node An expression node * @returns {string} The text representing the node, with all surrounding parentheses included @@ -1419,6 +1470,7 @@ module.exports = { /** * Determines whether the given node is a `null` literal. + * * @param {ASTNode} node The node to check * @returns {boolean} `true` if the node is a `null` literal */ @@ -1440,6 +1492,7 @@ module.exports = { /** * Check if a given node is a numeric literal or not. + * * @param {ASTNode} node The node to check. * @returns {boolean} `true` if the node is a number or bigint literal. */ @@ -1452,6 +1505,7 @@ module.exports = { /** * Determines whether two tokens can safely be placed next to each other without merging into a single token + * * @param {Token|string} leftValue The left token. If this is a string, it will be tokenized and the last token will be used. * @param {Token|string} rightValue The right token. If this is a string, it will be tokenized and the first token will be used. * @returns {boolean} If the tokens cannot be safely placed next to each other, returns `false`. If the tokens can be placed @@ -1571,6 +1625,7 @@ module.exports = { /** * Get the `loc` object of a given name in a `/*globals` directive comment. + * * @param {SourceCode} sourceCode The source code to convert index to loc. * @param {Comment} comment The `/*globals` directive comment which include the name. * @param {string} name The name to find. @@ -1601,6 +1656,7 @@ module.exports = { * "\00", "\01" ... "\09" * * "\0", when not followed by a digit, is not an octal escape sequence. + * * @param {string} rawString A string in its raw representation. * @returns {boolean} `true` if the string contains at least one octal escape sequence. */ diff --git a/fixtures/eslint/lib/source-code/source-code.js b/fixtures/eslint/lib/source-code/source-code.js index d247dfe2..c53016d4 100644 --- a/fixtures/eslint/lib/source-code/source-code.js +++ b/fixtures/eslint/lib/source-code/source-code.js @@ -22,6 +22,7 @@ const TokenStore = require('./token-store'); /** * Validates that the given AST has the required information. + * * @param {ASTNode} ast The Program node of the AST to check. * @throws {Error} If the AST doesn't contain the correct information. * @returns {void} @@ -47,6 +48,7 @@ function validate(ast) { /** * Check to see if its a ES6 export declaration. + * * @param {ASTNode} astNode An AST node. * @returns {boolean} whether the given node represents an export declaration. * @private @@ -62,6 +64,7 @@ function looksLikeExport(astNode) { /** * Merges two sorted lists into a larger sorted list in O(n) time. + * * @param {Token[]} tokens The list of tokens. * @param {Token[]} comments The list of comments. * @returns {Token[]} A sorted list of tokens and comments. @@ -89,6 +92,7 @@ function sortedMerge(tokens, comments) { /** * Determines if two nodes or tokens overlap. + * * @param {ASTNode|Token} first The first node or token to check. * @param {ASTNode|Token} second The second node or token to check. * @returns {boolean} True if the two nodes or tokens overlap. @@ -105,6 +109,7 @@ function nodesOrTokensOverlap(first, second) { * Determines if two nodes or tokens have at least one whitespace character * between them. Order does not matter. Returns false if the given nodes or * tokens overlap. + * * @param {SourceCode} sourceCode The source code object. * @param {ASTNode|Token} first The first node or token to check between. * @param {ASTNode|Token} second The second node or token to check between. @@ -158,6 +163,7 @@ function isSpaceBetween(sourceCode, first, second, checkInsideOfJSXText) { class SourceCode extends TokenStore { /** * Represents parsed source code. + * * @param {string|object} textOrConfig The source code text or config object. * @param {string} textOrConfig.text The source code text. * @param {ASTNode} textOrConfig.ast The Program node of the AST representing the code. This AST should be created from the text that BOM was stripped. @@ -186,6 +192,7 @@ class SourceCode extends TokenStore { /** * The flag to indicate that the source code has Unicode BOM. + * * @type boolean */ this.hasBOM = text.codePointAt(0) === 0xfe_ff; @@ -193,30 +200,35 @@ class SourceCode extends TokenStore { /** * The original text source code. * BOM was stripped from this text. + * * @type string */ this.text = this.hasBOM ? text.slice(1) : text; /** * The parsed AST for the source code. + * * @type ASTNode */ this.ast = ast; /** * The parser services of this source code. + * * @type {object} */ this.parserServices = parserServices || {}; /** * The scope of this source code. + * * @type {ScopeManager|null} */ this.scopeManager = scopeManager || null; /** * The visitor keys to traverse AST. + * * @type {object} */ this.visitorKeys = visitorKeys || Traverser.DEFAULT_VISITOR_KEYS; @@ -237,6 +249,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[] */ this.lines = []; @@ -278,6 +291,7 @@ class SourceCode extends TokenStore { /** * Split the source code into multiple lines based on the line delimiters. + * * @param {string} text Source code as a string. * @returns {string[]} Array of source code lines. * @public @@ -288,6 +302,7 @@ class SourceCode extends TokenStore { /** * Gets the source code for the given node. + * * @param {ASTNode} [node] The AST node to get the text for. * @param {int} [beforeCount] The number of characters before the node to retrieve. * @param {int} [afterCount] The number of characters after the node to retrieve. @@ -307,6 +322,7 @@ class SourceCode extends TokenStore { /** * Gets the entire source text split into an array of lines. + * * @returns {Array} The source text as an array of lines. * @public */ @@ -316,6 +332,7 @@ class SourceCode extends TokenStore { /** * Retrieves an array containing all comments in the source code. + * * @returns {ASTNode[]} An array of comment nodes. * @public */ @@ -325,6 +342,7 @@ class SourceCode extends TokenStore { /** * Gets all comments for the given node. + * * @param {ASTNode} node The AST node to get the comments for. * @returns {object} An object containing a leading and trailing array * of comments indexed by their position. @@ -407,6 +425,7 @@ class SourceCode extends TokenStore { /** * Retrieves the JSDoc comment for a given node. + * * @param {ASTNode} node The AST node to get the comment for. * @returns {Token|null} The Block comment token containing the JSDoc comment * for the given node or null if not found. @@ -416,6 +435,7 @@ class SourceCode extends TokenStore { getJSDocComment(node) { /** * Checks for the presence of a JSDoc comment for the given node and returns it. + * * @param {ASTNode} astNode The AST node to get the comment for. * @returns {Token|null} The Block comment token containing the JSDoc comment * for the given node or null if not found. @@ -492,6 +512,7 @@ class SourceCode extends TokenStore { /** * Gets the deepest node containing a range index. + * * @param {int} index Range index of the desired node. * @returns {ASTNode} The node if found or null if not found. * @public @@ -522,6 +543,7 @@ class SourceCode extends TokenStore { * Determines if two nodes or tokens have at least one whitespace character * between them. Order does not matter. Returns false if the given nodes or * tokens overlap. + * * @param {ASTNode|Token} first The first node or token to check between. * @param {ASTNode|Token} second The second node or token to check between. * @returns {boolean} True if there is a whitespace character between @@ -538,6 +560,7 @@ class SourceCode extends TokenStore { * tokens overlap. * For backward compatibility, this method returns true if there are * `JSXText` tokens that contain whitespaces between the two. + * * @param {ASTNode|Token} first The first node or token to check between. * @param {ASTNode|Token} second The second node or token to check between. * @returns {boolean} True if there is a whitespace character between @@ -551,6 +574,7 @@ class SourceCode extends TokenStore { /** * Converts a source text index into a (line, column) pair. + * * @param {number} index The index of a character in a file * @returns {object} A {line, column} location object with a 0-indexed column * @public @@ -594,6 +618,7 @@ class SourceCode extends TokenStore { /** * Converts a (line, column) pair into a range index. + * * @param {object} loc A line/column location * @param {number} loc.line The line number of the location (1-indexed) * @param {number} loc.column The column number of the location (0-indexed) diff --git a/fixtures/eslint/tools/code-sample-minimizer.js b/fixtures/eslint/tools/code-sample-minimizer.js index d4635abc..bb3d93c8 100644 --- a/fixtures/eslint/tools/code-sample-minimizer.js +++ b/fixtures/eslint/tools/code-sample-minimizer.js @@ -8,6 +8,7 @@ const recast = require('recast'); /** * Determines whether an AST node could be an expression, based on the type + * * @param {ASTNode} node The node * @returns {boolean} `true` if the node could be an expression */ @@ -22,6 +23,7 @@ function isMaybeExpression(node) { /** * Determines whether an AST node is a statement + * * @param {ASTNode} node The node * @returns {boolean} `true` if the node is a statement */ @@ -33,6 +35,7 @@ function isStatement(node) { * Given "bad" source text (e.g. an code sample that causes a rule to crash), tries to return a smaller * piece of source text which is also "bad", to make it easier for a human to figure out where the * problem is. + * * @param {object} options Options to process * @param {string} options.sourceText Initial piece of "bad" source text * @param {function(string): boolean} options.predicate A predicate that returns `true` for bad source text and `false` for good source text @@ -65,6 +68,7 @@ function reduceBadExampleSize({ /** * Returns a new unique identifier + * * @returns {string} A name for a new identifier */ function generateNewIdentifierName() { @@ -73,6 +77,7 @@ function reduceBadExampleSize({ /** * Determines whether a source text sample is "bad" + * * @param {string} updatedSourceText The sample * @returns {boolean} `true` if the sample is "bad" */ @@ -95,6 +100,7 @@ function reduceBadExampleSize({ /** * Recursively removes descendant subtrees of the given AST node and replaces * them with simplified variants to produce a simplified AST which is still considered "bad". + * * @param {ASTNode} node An AST node to prune. May be mutated by this call, but the * resulting AST will still produce "bad" source code. * @returns {void} @@ -139,6 +145,7 @@ function reduceBadExampleSize({ /** * Recursively tries to extract a descendant node from the AST that is "bad" on its own + * * @param {ASTNode} node A node which produces "bad" source code * @returns {ASTNode} A descendent of `node` which is also bad */ @@ -174,6 +181,7 @@ function reduceBadExampleSize({ /** * Removes and simplifies comments from the source text + * * @param {string} text A piece of "bad" source text * @returns {string} A piece of "bad" source text with fewer and/or simpler comments. */ diff --git a/fixtures/load-repo.mjs b/fixtures/load-repo.mjs index 2e19c570..15641ca3 100755 --- a/fixtures/load-repo.mjs +++ b/fixtures/load-repo.mjs @@ -33,6 +33,7 @@ process.on('unhandledRejection', (error) => { /** * Wraps child_process.spawn to make it promise-friendly and output to stderr/stdout + * * @param {string} command * @param {readonly string[]} args * @param {import("child_process").SpawnOptionsWithoutStdio} [opts] diff --git a/fixtures/mocha/lib/cli/one-and-dones.js b/fixtures/mocha/lib/cli/one-and-dones.js index 7e3f8ddb..7bbc7096 100644 --- a/fixtures/mocha/lib/cli/one-and-dones.js +++ b/fixtures/mocha/lib/cli/one-and-dones.js @@ -4,6 +4,7 @@ * Contains "command" code for "one-and-dones"--options passed * to Mocha which cause it to just dump some info and exit. * See {@link module:lib/cli/one-and-dones.ONE_AND_DONE_ARGS ONE_AND_DONE_ARGS} for more info. + * * @module * @private */ @@ -15,6 +16,7 @@ const Mocha = require('../mocha'); /** * Dumps a sorted list of the enumerable, lower-case keys of some object * to `STDOUT`. + * * @param {object} obj - Object, ostensibly having some enumerable keys * @ignore * @private @@ -41,12 +43,14 @@ const showKeys = (obj) => { /** * Handlers for one-and-done options + * * @namespace * @private */ exports.ONE_AND_DONES = { /** * Dump list of built-in interfaces + * * @private */ 'list-interfaces': () => { @@ -54,6 +58,7 @@ exports.ONE_AND_DONES = { }, /** * Dump list of built-in reporters + * * @private */ 'list-reporters': () => { @@ -63,6 +68,7 @@ exports.ONE_AND_DONES = { /** * A Set of all one-and-done options + * * @type Set * @private */ diff --git a/fixtures/mocha/lib/cli/options.js b/fixtures/mocha/lib/cli/options.js index 70053cd5..3435f442 100644 --- a/fixtures/mocha/lib/cli/options.js +++ b/fixtures/mocha/lib/cli/options.js @@ -3,6 +3,7 @@ /** * Main entry point for handling filesystem-based configuration, * whether that's a config file or `package.json` or whatever. + * * @module */ @@ -23,18 +24,21 @@ const { types, aliases } = require('./run-option-metadata'); /** * The `yargs-parser` namespace + * * @external yargsParser * @see {@link https://npm.im/yargs-parser} */ /** * An object returned by a configured `yargs-parser` representing arguments + * * @memberof external:yargsParser * @interface Arguments */ /** * Base yargs parser configuration + * * @private */ const YARGS_PARSER_CONFIG = { @@ -48,6 +52,7 @@ const YARGS_PARSER_CONFIG = { * `package.json`, but it also disables camel case expansion as to * avoid outputting non-canonical keynames, as we need to do some * lookups. + * * @private * @ignore */ @@ -58,6 +63,7 @@ const configuration = { ...YARGS_PARSER_CONFIG, 'camel-case-expansion': false }; * - ensure unique values for `array`-type options * - use its array's last element for `boolean`/`number`/`string`- options given multiple times * This is passed as the `coerce` option to `yargs-parser` + * * @private * @ignore */ @@ -78,6 +84,7 @@ const coerceOpts = Object.assign( * (e.g., `--foo bar baz quux`), so we fix the number of arguments to 1 across * the board of non-boolean options. * This is passed as the `narg` option to `yargs-parser` + * * @private * @ignore */ @@ -87,6 +94,7 @@ const nargOpts = Object.fromEntries( /** * Wrapper around `yargs-parser` which applies our settings + * * @param {string|string[]} args - Arguments to parse * @param {object} defaultValues - Default values of mocharc.json * @param {...object} configObjects - `configObjects` for yargs-parser @@ -144,6 +152,7 @@ const parse = (args = [], defaultValues = {}, ...configObjects) => { /** * Given path to config file in `args.config`, attempt to load & parse config file. + * * @param {object} [args] - Arguments object * @param {string|boolean} [args.config] - Path to config file or `false` to skip * @public @@ -161,6 +170,7 @@ module.exports.loadRc = loadRc; /** * Given path to `package.json` in `args.package`, attempt to load config from `mocha` prop. + * * @param {object} [args] - Arguments object * @param {string|boolean} [args.config] - Path to `package.json` or `false` to skip * @public @@ -207,6 +217,7 @@ module.exports.loadPkgRc = loadPkgRc; * 4. default configuration (`lib/mocharc.json`) * * If a {@link module:lib/cli/one-and-dones.ONE_AND_DONE_ARGS "one-and-done" option} is present in the `argv` array, no external config files will be read. + * * @summary Parses options read from `.mocharc.*` and `package.json`. * @param {string|string[]} [argv] - Arguments to parse * @public diff --git a/fixtures/mocha/lib/growl.js b/fixtures/mocha/lib/growl.js index 3bcb2852..8eecf8ca 100644 --- a/fixtures/mocha/lib/growl.js +++ b/fixtures/mocha/lib/growl.js @@ -2,6 +2,7 @@ /** * Desktop Notifications module. + * * @module Growl */ diff --git a/fixtures/mocha/scripts/markdown-magic.config.js b/fixtures/mocha/scripts/markdown-magic.config.js index 9f0be435..c7b6bdbf 100644 --- a/fixtures/mocha/scripts/markdown-magic.config.js +++ b/fixtures/mocha/scripts/markdown-magic.config.js @@ -2,6 +2,7 @@ /** * Add autogenerated stuff to our docs (`docs/index.md`) + * * @see https://npm.im/markdown-magic * @private * @module diff --git a/generate-changeset.mjs b/generate-changeset.mjs index 16cbacbc..688ad4f7 100644 --- a/generate-changeset.mjs +++ b/generate-changeset.mjs @@ -14,6 +14,7 @@ const writeChangeset = _writeChangeset.default; /** * Wraps child_process.spawn to make it promise-friendly and output to stderr/stdout + * * @param {string} command * @param {readonly string[]} args * @param {import("child_process").SpawnOptionsWithoutStdio} [opts] diff --git a/package-lock.json b/package-lock.json index a5f766b9..38441f88 100644 --- a/package-lock.json +++ b/package-lock.json @@ -13,7 +13,7 @@ "@typescript-eslint/eslint-plugin": "^5.0.0", "@typescript-eslint/parser": "^5.0.0", "eslint-plugin-import": "^2.25.4", - "eslint-plugin-jsdoc": "^39.0.0", + "eslint-plugin-jsdoc": "^46.0.0", "eslint-plugin-n": "^15.2.3", "eslint-plugin-promise": "^6.0.0", "eslint-plugin-unicorn": "^47.0.0" @@ -725,16 +725,16 @@ "dev": true }, "node_modules/@es-joy/jsdoccomment": { - "version": "0.36.1", - "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.36.1.tgz", - "integrity": "sha512-922xqFsTpHs6D0BUiG4toiyPOMc8/jafnWKxz1KWgS4XzKPy2qXf1Pe6UFuNSCQqt6tOuhAWXBNuuyUhJmw9Vg==", + "version": "0.39.4", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.39.4.tgz", + "integrity": "sha512-Jvw915fjqQct445+yron7Dufix9A+m9j1fCJYlCo1FWlRvTxa3pjJelxdSTdaLWcTwRU6vbL+NYjO4YuNIS5Qg==", "dependencies": { "comment-parser": "1.3.1", - "esquery": "^1.4.0", - "jsdoc-type-pratt-parser": "~3.1.0" + "esquery": "^1.5.0", + "jsdoc-type-pratt-parser": "~4.0.0" }, "engines": { - "node": "^14 || ^16 || ^17 || ^18 || ^19" + "node": ">=16" } }, "node_modules/@eslint-community/eslint-utils": { @@ -1356,6 +1356,14 @@ "node": ">=4" } }, + "node_modules/are-docs-informative": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/are-docs-informative/-/are-docs-informative-0.0.2.tgz", + "integrity": "sha512-ixiS0nLNNG5jNQzgZJNoUpBKdo9yTYZMGJ+QgT2jmjR7G7+QHRCc4v6LQ3NgE7EBJq+o0ams3waJwkrlBom8Ig==", + "engines": { + "node": ">=14" + } + }, "node_modules/argparse": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", @@ -2375,20 +2383,21 @@ } }, "node_modules/eslint-plugin-jsdoc": { - "version": "39.9.1", - "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-39.9.1.tgz", - "integrity": "sha512-Rq2QY6BZP2meNIs48aZ3GlIlJgBqFCmR55+UBvaDkA3ZNQ0SvQXOs2QKkubakEijV8UbIVbVZKsOVN8G3MuqZw==", + "version": "46.0.0", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-46.0.0.tgz", + "integrity": "sha512-xmB5WleBcPCFYlrFfdjrcfSKOJBLwyGmKa+i+fVqlIHp8g5aAoeQpBGugUzToFtQgd4hNZYlfIcP7QSxC9NYWQ==", "dependencies": { - "@es-joy/jsdoccomment": "~0.36.1", + "@es-joy/jsdoccomment": "~0.39.4", + "are-docs-informative": "^0.0.2", "comment-parser": "1.3.1", "debug": "^4.3.4", "escape-string-regexp": "^4.0.0", - "esquery": "^1.4.0", - "semver": "^7.3.8", + "esquery": "^1.5.0", + "semver": "^7.5.1", "spdx-expression-parse": "^3.0.1" }, "engines": { - "node": "^14 || ^16 || ^17 || ^18 || ^19" + "node": ">=16" }, "peerDependencies": { "eslint": "^7.0.0 || ^8.0.0" @@ -3701,9 +3710,9 @@ } }, "node_modules/jsdoc-type-pratt-parser": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-3.1.0.tgz", - "integrity": "sha512-MgtD0ZiCDk9B+eI73BextfRrVQl0oyzRG8B2BjORts6jbunj4ScKPcyXGTbB6eXL4y9TzxCm6hyeLq/2ASzNdw==", + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz", + "integrity": "sha512-YtOli5Cmzy3q4dP26GraSOeAhqecewG04hoO8DY56CH4KJ9Fvv5qKWUCCo3HZob7esJQHCv6/+bnTy72xZZaVQ==", "engines": { "node": ">=12.0.0" } @@ -6386,13 +6395,13 @@ } }, "@es-joy/jsdoccomment": { - "version": "0.36.1", - "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.36.1.tgz", - "integrity": "sha512-922xqFsTpHs6D0BUiG4toiyPOMc8/jafnWKxz1KWgS4XzKPy2qXf1Pe6UFuNSCQqt6tOuhAWXBNuuyUhJmw9Vg==", + "version": "0.39.4", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.39.4.tgz", + "integrity": "sha512-Jvw915fjqQct445+yron7Dufix9A+m9j1fCJYlCo1FWlRvTxa3pjJelxdSTdaLWcTwRU6vbL+NYjO4YuNIS5Qg==", "requires": { "comment-parser": "1.3.1", - "esquery": "^1.4.0", - "jsdoc-type-pratt-parser": "~3.1.0" + "esquery": "^1.5.0", + "jsdoc-type-pratt-parser": "~4.0.0" } }, "@eslint-community/eslint-utils": { @@ -6825,6 +6834,11 @@ "color-convert": "^1.9.0" } }, + "are-docs-informative": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/are-docs-informative/-/are-docs-informative-0.0.2.tgz", + "integrity": "sha512-ixiS0nLNNG5jNQzgZJNoUpBKdo9yTYZMGJ+QgT2jmjR7G7+QHRCc4v6LQ3NgE7EBJq+o0ams3waJwkrlBom8Ig==" + }, "argparse": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", @@ -7698,16 +7712,17 @@ } }, "eslint-plugin-jsdoc": { - "version": "39.9.1", - "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-39.9.1.tgz", - "integrity": "sha512-Rq2QY6BZP2meNIs48aZ3GlIlJgBqFCmR55+UBvaDkA3ZNQ0SvQXOs2QKkubakEijV8UbIVbVZKsOVN8G3MuqZw==", + "version": "46.0.0", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-46.0.0.tgz", + "integrity": "sha512-xmB5WleBcPCFYlrFfdjrcfSKOJBLwyGmKa+i+fVqlIHp8g5aAoeQpBGugUzToFtQgd4hNZYlfIcP7QSxC9NYWQ==", "requires": { - "@es-joy/jsdoccomment": "~0.36.1", + "@es-joy/jsdoccomment": "~0.39.4", + "are-docs-informative": "^0.0.2", "comment-parser": "1.3.1", "debug": "^4.3.4", "escape-string-regexp": "^4.0.0", - "esquery": "^1.4.0", - "semver": "^7.3.8", + "esquery": "^1.5.0", + "semver": "^7.5.1", "spdx-expression-parse": "^3.0.1" }, "dependencies": { @@ -8477,9 +8492,9 @@ } }, "jsdoc-type-pratt-parser": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-3.1.0.tgz", - "integrity": "sha512-MgtD0ZiCDk9B+eI73BextfRrVQl0oyzRG8B2BjORts6jbunj4ScKPcyXGTbB6eXL4y9TzxCm6hyeLq/2ASzNdw==" + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz", + "integrity": "sha512-YtOli5Cmzy3q4dP26GraSOeAhqecewG04hoO8DY56CH4KJ9Fvv5qKWUCCo3HZob7esJQHCv6/+bnTy72xZZaVQ==" }, "jsesc": { "version": "2.5.2", diff --git a/package.json b/package.json index bfc11f96..0079aa2a 100644 --- a/package.json +++ b/package.json @@ -34,7 +34,7 @@ "@typescript-eslint/eslint-plugin": "^5.0.0", "@typescript-eslint/parser": "^5.0.0", "eslint-plugin-import": "^2.25.4", - "eslint-plugin-jsdoc": "^39.0.0", + "eslint-plugin-jsdoc": "^46.0.0", "eslint-plugin-n": "^15.2.3", "eslint-plugin-promise": "^6.0.0", "eslint-plugin-unicorn": "^47.0.0" diff --git a/src/config.js b/src/config.js index 9074c48a..9c28d315 100644 --- a/src/config.js +++ b/src/config.js @@ -218,6 +218,7 @@ module.exports.configs = { 'jsdoc/require-returns-description': 'off', 'jsdoc/require-jsdoc': 'off', 'jsdoc/require-returns-check': 'off', // Does not handle @returns with void or undefined + 'jsdoc/tag-lines': ['error', 'any', { startLines: 1 }], }) ), overrides: [