Chore: enable additional eslint-plugin-jsdoc rules (#12336)

* Chore: enable jsdoc/newline-after-description

* Chore: enable jsdoc/require-hyphen-before-param-description

Makefile.js

@@ -941,7 +941,7 @@ target.checkLicenses = function() {
 /**
  * Downloads a repository which has many js files to test performance with multi files.
  * Here, it's eslint@1.10.3 (450 files)
- * @param {Function} cb - A callback function.
+ * @param {Function} cb A callback function.
  * @returns {void}
  */
 function downloadMultifilesTestTarget(cb) {
@@ -1017,11 +1017,10 @@ function time(cmd, runs, runNumber, results, cb) {
 
 /**
  * Run a performance test.
- *
- * @param {string} title - A title.
- * @param {string} targets - Test targets.
- * @param {number} multiplier - A multiplier for limitation.
- * @param {Function} cb - A callback function.
+ * @param {string} title A title.
+ * @param {string} targets Test targets.
+ * @param {number} multiplier A multiplier for limitation.
+ * @param {Function} cb A callback function.
  * @returns {void}
  */
 function runPerformanceTest(title, targets, multiplier, cb) {

lib/cli-engine/cascading-config-array-factory.js

@@ -153,7 +153,7 @@ function createCLIConfigArray({
 class ConfigurationNotFoundError extends Error {
 
     /**
-     * @param {string} directoryPath - The directory path.
+     * @param {string} directoryPath The directory path.
      */
     constructor(directoryPath) {
         super(`No ESLint configuration found in ${directoryPath}.`);

lib/cli-engine/cli-engine.js

@@ -145,7 +145,7 @@ function validateFixTypes(fixTypes) {
 
 /**
  * It will calculate the error and warning count for collection of messages per file
- * @param {LintMessage[]} messages - Collection of messages
+ * @param {LintMessage[]} messages Collection of messages
  * @returns {Object} Contains the stats
  * @private
  */
@@ -173,7 +173,7 @@ function calculateStatsPerFile(messages) {
 
 /**
  * It will calculate the error and warning count for collection of results from all files
- * @param {LintResult[]} results - Collection of messages from all the files
+ * @param {LintResult[]} results Collection of messages from all the files
  * @returns {Object} Contains the stats
  * @private
  */
@@ -272,8 +272,8 @@ function verifyText({
 
 /**
  * Returns result with warning by ignore settings
- * @param {string} filePath - File path of checked code
- * @param {string} baseDir  - Absolute path of base directory
+ * @param {string} filePath File path of checked code
+ * @param {string} baseDir  Absolute path of base directory
  * @returns {LintResult} Result with single warning
  * @private
  */
@@ -387,7 +387,6 @@ function isErrorMessage(message) {
  * name will be the `cacheFile/.cache_hashOfCWD`
  *
  * if cacheFile points to a file or looks like a file then in will just use that file
- *
  * @param {string} cacheFile The name of file to be used to store the cache
  * @param {string} cwd Current working directory
  * @returns {string} the resolved path to the cache file

lib/cli-engine/config-array/config-array.js

@@ -126,7 +126,6 @@ function isNonNullObject(x) {
  *
  * Assign every property values of `y` to `x` if `x` doesn't have the property.
  * If `x`'s property value is an object, it does recursive.
- *
  * @param {Object} target The destination to merge
  * @param {Object|undefined} source The source to merge.
  * @returns {void}
@@ -157,7 +156,6 @@ function mergeWithoutOverwrite(target, source) {
 /**
  * Merge plugins.
  * `target`'s definition is prior to `source`'s.
- *
  * @param {Record<string, DependentPlugin>} target The destination to merge
  * @param {Record<string, DependentPlugin>|undefined} source The source to merge.
  * @returns {void}
@@ -187,7 +185,6 @@ function mergePlugins(target, source) {
 /**
  * Merge rule configs.
  * `target`'s definition is prior to `source`'s.
- *
  * @param {Record<string, Array>} target The destination to merge
  * @param {Record<string, RuleConf>|undefined} source The source to merge.
  * @returns {void}
@@ -382,7 +379,6 @@ function ensurePluginMemberMaps(instance) {
  * You need to call `ConfigArray#extractConfig(filePath)` method in order to
  * extract, merge and get only the config data which is related to an arbitrary
  * file.
- *
  * @extends {Array<ConfigArrayElement>}
  */
 class ConfigArray extends Array {

lib/cli-engine/file-enumerator.js

@@ -150,8 +150,8 @@ function readdirSafeSync(directoryPath) {
 class NoFilesFoundError extends Error {
 
     /**
-     * @param {string} pattern - The glob pattern which was not found.
-     * @param {boolean} globDisabled - If `true` then the pattern was a glob pattern, but glob was disabled.
+     * @param {string} pattern The glob pattern which was not found.
+     * @param {boolean} globDisabled If `true` then the pattern was a glob pattern, but glob was disabled.
      */
     constructor(pattern, globDisabled) {
         super(`No files matching '${pattern}' were found${globDisabled ? " (glob was disabled)" : ""}.`);
@@ -166,7 +166,7 @@ class NoFilesFoundError extends Error {
 class AllFilesIgnoredError extends Error {
 
     /**
-     * @param {string} pattern - The glob pattern which was not found.
+     * @param {string} pattern The glob pattern which was not found.
      */
     constructor(pattern) {
         super(`All files matched by '${pattern}' are ignored.`);

lib/init/autoconfig.js

@@ -31,7 +31,6 @@ 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
@@ -82,7 +81,6 @@ class Registry {
      *
      * It will set the registry's `rule` property to an object having rule names
      * as keys and an array of registryItems as values.
-     *
      * @returns {void}
      */
     populateFromCoreRules() {
@@ -101,7 +99,6 @@ class Registry {
      * configurations.
      *
      * The length of the returned array will be <= MAX_CONFIG_COMBINATIONS.
-     *
      * @returns {Object[]}          "rules" configurations to use for linting
      */
     buildRuleSets() {
@@ -114,7 +111,6 @@ class Registry {
          *
          * This is broken out into its own function so that it doesn't need to be
          * created inside of the while loop.
-         *
          * @param   {string} rule The ruleId to add.
          * @returns {void}
          */
@@ -162,7 +158,6 @@ class Registry {
      *
      * Note: this also removes rule configurations which were not linted
      * (meaning, they have an undefined errorCount).
-     *
      * @returns {void}
      */
     stripFailingConfigs() {
@@ -185,7 +180,6 @@ class Registry {
 
     /**
      * Removes rule configurations which were not included in a ruleSet
-     *
      * @returns {void}
      */
     stripExtraConfigs() {
@@ -204,7 +198,6 @@ class Registry {
      * Creates a registry of rules which had no error-free configs.
      * The new registry is intended to be analyzed to determine whether its rules
      * should be disabled or set to warning.
-     *
      * @returns {Registry}  A registry of failing rules.
      */
     getFailingRulesRegistry() {
@@ -225,7 +218,6 @@ class Registry {
     /**
      * Create an eslint config for any rules which only have one configuration
      * in the registry.
-     *
      * @returns {Object} An eslint config with rules section populated
      */
     createConfig() {
@@ -243,7 +235,6 @@ class Registry {
 
     /**
      * Return a cloned registry containing only configs with a desired specificity
-     *
      * @param   {number} specificity Only keep configs with this specificity
      * @returns {Registry}           A registry of rules
      */
@@ -261,7 +252,6 @@ class Registry {
 
     /**
      * Lint SourceCodes against all configurations in the registry, and record results
-     *
      * @param   {Object[]} sourceCodes  SourceCode objects for each filename
      * @param   {Object}   config       ESLint config object
      * @param   {progressCallback} [cb] Optional callback for reporting execution status
@@ -327,7 +317,6 @@ class Registry {
  *
  * This will return a new config with `"extends": "eslint:recommended"` and
  * only the rules which have configurations different from the recommended config.
- *
  * @param   {Object} config config object
  * @returns {Object}        config object using `"extends": "eslint:recommended"`
  */

lib/init/config-file.js

@@ -23,7 +23,6 @@ const debug = require("debug")("eslint:config-file");
  * Determines sort order for object keys for json-stable-stringify
  *
  * see: https://github.com/samn/json-stable-stringify#cmp
- *
  * @param   {Object} a The first comparison object ({key: akey, value: avalue})
  * @param   {Object} b The second comparison object ({key: bkey, value: bvalue})
  * @returns {number}   1 or -1, used in stringify cmp method

lib/init/config-initializer.js

@@ -147,7 +147,6 @@ 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

lib/init/config-rule.js

@@ -33,7 +33,6 @@ function explodeArray(xs) {
  *
  * For example:
  * combineArrays([a, [b, c]], [x, y]); // -> [[a, x], [a, y], [b, c, x], [b, c, y]]
- *
  * @param   {Array} arr1 The first array to combine.
  * @param   {Array} arr2 The second array to combine.
  * @returns {Array}      A mixture of the elements of the first and second arrays.
@@ -71,7 +70,6 @@ function combineArrays(arr1, arr2) {
  *     [{before: true}, {before: false}],
  *     [{after: true}, {after: false}]
  * ]
- *
  * @param   {Object[]} objects Array of objects, each with one property/value pair
  * @returns {Array[]}          Array of arrays of objects grouped by property
  */
@@ -98,7 +96,6 @@ function groupByProperty(objects) {
  * element in the array is the severity, and is the only required element.
  * Configs may also have one or more additional elements to specify rule
  * configuration or options.
- *
  * @typedef {Array|number} ruleConfig
  * @param {number}  0  The rule's severity (0, 1, 2).
  */
@@ -134,7 +131,6 @@ function groupByProperty(objects) {
  *     {before: false, after: true},
  *     {before: false, after: false}
  * ]
- *
  * @param   {Object[]} objArr1 Single key/value objects, all with the same key
  * @param   {Object[]} objArr2 Single key/value objects, all with another key
  * @returns {Object[]}         Combined objects for each combination of input properties and values
@@ -193,7 +189,6 @@ class RuleConfigSet {
     /**
      * Add a severity level to the front of all configs in the instance.
      * This should only be called after all configs have been added to the instance.
-     *
      * @returns {void}
      */
     addErrorSeverity() {

lib/init/npm-utils.js

@@ -21,7 +21,6 @@ const fs = require("fs"),
 /**
  * Find the closest package.json file, starting at process.cwd (by default),
  * and working up to root.
- *
  * @param   {string} [startDir=process.cwd()] Starting directory
  * @returns {string}                          Absolute path to closest package.json file
  */
@@ -88,7 +87,6 @@ function fetchPeerDependencies(packageName) {
 
 /**
  * Check whether node modules are include in a project's package.json.
- *
  * @param   {string[]} packages           Array of node module names
  * @param   {Object}  opt                 Options Object
  * @param   {boolean} opt.dependencies    Set to true to check for direct dependencies
@@ -136,7 +134,6 @@ function check(packages, opt) {
  * package.json.
  *
  * Convenience wrapper around check().
- *
  * @param   {string[]} packages  Array of node modules to check.
  * @param   {string}   rootDir   The directory contianing a package.json
  * @returns {Object}             An object whose keys are the module names
@@ -151,7 +148,6 @@ function checkDeps(packages, rootDir) {
  * package.json.
  *
  * Convenience wrapper around check().
- *
  * @param   {string[]} packages  Array of node modules to check.
  * @returns {Object}             An object whose keys are the module names
  *                               and values are booleans indicating installation.
@@ -162,7 +158,6 @@ function checkDevDeps(packages) {
 
 /**
  * Check whether package.json is found in current path.
- *
  * @param   {string} [startDir] Starting directory
  * @returns {boolean} Whether a package.json is found in current path.
  */