From 04b6adb7f1bcb2b6cb3fa377b1ca4cecd810630e Mon Sep 17 00:00:00 2001
From: Kai Cataldo <7041728+kaicataldo@users.noreply.github.com>
Date: Sat, 28 Sep 2019 23:18:59 -0400
Subject: [PATCH] Chore: enable eslint-plugin-jsdoc (refs #11146) (#12332)

* Chore: enable eslint-plugin-jsdoc (refs #11146)

* Chore: enable jsdoc/check-types

* Chore: enable jsdoc/check-param-names

* Chore: enable jsdoc/check-alignment

* Chore: enable jsdoc/check-tag-names

* Chore: enable jsdoc/check-syntax

* Chore: enable jsdoc/implements-on-classes

* Chore: enable jsdoc/require-param-descriptions

* Chore: enable jsdoc/require-param-name

* Chore: enable jsdoc/require-param-type

* Chore: enable jsdoc/require-param

* Chore: enable jsdoc/require-returns-description

* Chore: enable jsdoc/require-returns-type

* Chore: enable jsdoc/require-returns

* Fix: eslint-plugin-jsdoc uses Function by default

* Chore: fix test

* Fix: remove out of date comment
---
 lib/cli-engine/cli-engine.js                  |  6 ++--
 lib/cli-engine/ignored-paths.js               |  6 ++--
 lib/cli-engine/lint-result-cache.js           |  1 -
 lib/init/config-rule.js                       |  4 +--
 lib/init/npm-utils.js                         |  2 +-
 .../code-path-analysis/debug-helpers.js       |  2 +-
 lib/linter/linter.js                          |  1 -
 lib/rule-tester/rule-tester.js                |  1 -
 lib/rules/indent-legacy.js                    |  2 +-
 lib/shared/logging.js                         |  2 ++
 lib/source-code/source-code.js                |  7 ++--
 package.json                                  |  1 +
 packages/eslint-config-eslint/default.yml     | 36 ++++++++++++-------
 packages/eslint-config-eslint/package.json    |  1 +
 tests/lib/_utils.js                           |  2 --
 tests/lib/cli-engine/_utils.js                |  3 --
 .../cascading-config-array-factory.js         |  3 ++
 tests/lib/cli-engine/cli-engine.js            |  7 +++-
 tests/lib/cli-engine/file-enumerator.js       |  1 +
 tests/lib/cli-engine/ignored-paths.js         |  1 +
 tests/lib/cli.js                              |  1 +
 tests/lib/init/config-initializer.js          |  1 +
 tests/lib/init/source-code-utils.js           |  1 +
 tests/tools/loose-parser.js                   |  1 -
 tools/code-sample-minimizer.js                |  1 +
 tools/internal-rules/no-invalid-meta.js       |  1 -
 26 files changed, 56 insertions(+), 39 deletions(-)

diff --git a/lib/cli-engine/cli-engine.js b/lib/cli-engine/cli-engine.js
index 7f80887f086..3c67d33daa6 100644
--- a/lib/cli-engine/cli-engine.js
+++ b/lib/cli-engine/cli-engine.js
@@ -85,8 +85,8 @@ const validFixTypes = new Set(["problem", "suggestion", "layout"]);
  * @property {number} warningCount Number of warnings for the result.
  * @property {number} fixableErrorCount Number of fixable errors for the result.
  * @property {number} fixableWarningCount Number of fixable warnings for the result.
- * @property {string=} [source] The source code of the file that was linted.
- * @property {string=} [output] The source code of the file that was linted, with as many fixes applied as possible.
+ * @property {string} [source] The source code of the file that was linted.
+ * @property {string} [output] The source code of the file that was linted, with as many fixes applied as possible.
  */
 
 /**
@@ -329,7 +329,6 @@ function getRule(ruleId, configArrays) {
 /**
  * Collect used deprecated rules.
  * @param {ConfigArray[]} usedConfigArrays The config arrays which were used.
- * @param {Map<string, Object>} ruleMap The rule definitions which were used (built-ins).
  * @returns {IterableIterator<DeprecatedRuleInfo>} Used deprecated rules.
  */
 function *iterateRuleDeprecationWarnings(usedConfigArrays) {
@@ -530,7 +529,6 @@ class CLIEngine {
     /**
      * Creates a new instance of the core CLI engine.
      * @param {CLIEngineOptions} providedOptions The options for this instance.
-     * @constructor
      */
     constructor(providedOptions) {
         const options = Object.assign(
diff --git a/lib/cli-engine/ignored-paths.js b/lib/cli-engine/ignored-paths.js
index 137d156e9c0..12dfce06665 100644
--- a/lib/cli-engine/ignored-paths.js
+++ b/lib/cli-engine/ignored-paths.js
@@ -78,7 +78,7 @@ function mergeDefaultOptions(options) {
     return Object.assign({}, DEFAULT_OPTIONS, options);
 }
 
-/* eslint-disable valid-jsdoc */
+/* eslint-disable jsdoc/check-param-names, jsdoc/require-param */
 /**
  * Normalize the path separators in a given string.
  * On Windows environment, this replaces `\` by `/`.
@@ -89,7 +89,7 @@ function mergeDefaultOptions(options) {
 const normalizePathSeps = path.sep === "/"
     ? (str => str)
     : ((seps, str) => str.replace(seps, "/")).bind(null, new RegExp(`\\${path.sep}`, "gu"));
-/* eslint-enable valid-jsdoc */
+/* eslint-enable jsdoc/check-param-names, jsdoc/require-param */
 
 /**
  * Converts a glob pattern to a new glob pattern relative to a different directory
@@ -298,7 +298,7 @@ class IgnoredPaths {
 
     /**
      * read ignore filepath
-     * @param {string} filePath, file to add to ig
+     * @param {string} filePath file to add to ig
      * @returns {Array} raw ignore rules
      */
     readIgnoreFile(filePath) {
diff --git a/lib/cli-engine/lint-result-cache.js b/lib/cli-engine/lint-result-cache.js
index 9408780fb02..14e19d9e5a1 100644
--- a/lib/cli-engine/lint-result-cache.js
+++ b/lib/cli-engine/lint-result-cache.js
@@ -47,7 +47,6 @@ class LintResultCache {
 
     /**
      * Creates a new LintResultCache instance.
-     * @constructor
      * @param {string} cacheFileLocation The cache file location.
      *   configuration lookup by file path).
      */
diff --git a/lib/init/config-rule.js b/lib/init/config-rule.js
index fbe9b779ab7..e40feb7145b 100644
--- a/lib/init/config-rule.js
+++ b/lib/init/config-rule.js
@@ -99,7 +99,7 @@ function groupByProperty(objects) {
  * Configs may also have one or more additional elements to specify rule
  * configuration or options.
  *
- * @typedef {array|number} ruleConfig
+ * @typedef {Array|number} ruleConfig
  * @param {number}  0  The rule's severity (0, 1, 2).
  */
 
@@ -185,7 +185,7 @@ class RuleConfigSet {
 
         /**
          * Stored valid rule configurations for this instance
-         * @type {array}
+         * @type {Array}
          */
         this.ruleConfigs = configs || [];
     }
diff --git a/lib/init/npm-utils.js b/lib/init/npm-utils.js
index 7fe7c6e7d59..3d4a896b6f6 100644
--- a/lib/init/npm-utils.js
+++ b/lib/init/npm-utils.js
@@ -163,7 +163,7 @@ function checkDevDeps(packages) {
 /**
  * Check whether package.json is found in current path.
  *
- * @param   {string=} startDir Starting directory
+ * @param   {string} [startDir] Starting directory
  * @returns {boolean} Whether a package.json is found in current path.
  */
 function checkPackageJson(startDir) {
diff --git a/lib/linter/code-path-analysis/debug-helpers.js b/lib/linter/code-path-analysis/debug-helpers.js
index 9af985ce85f..2ca6dbc1e52 100644
--- a/lib/linter/code-path-analysis/debug-helpers.js
+++ b/lib/linter/code-path-analysis/debug-helpers.js
@@ -21,7 +21,7 @@ const debug = require("debug")("eslint:code-path");
  * @returns {string} Id of the segment.
  */
 /* istanbul ignore next */
-function getId(segment) { // eslint-disable-line require-jsdoc
+function getId(segment) { // eslint-disable-line jsdoc/require-jsdoc
     return segment.id + (segment.reachable ? "" : "!");
 }
 
diff --git a/lib/linter/linter.js b/lib/linter/linter.js
index 7d1dc8c8c1c..534181da9e4 100644
--- a/lib/linter/linter.js
+++ b/lib/linter/linter.js
@@ -472,7 +472,6 @@ function normalizeFilename(filename) {
     return index === -1 ? filename : parts.slice(index).join(path.sep);
 }
 
-// eslint-disable-next-line valid-jsdoc
 /**
  * Normalizes the possible options for `linter.verify` and `linter.verifyAndFix` to a
  * consistent shape.
diff --git a/lib/rule-tester/rule-tester.js b/lib/rule-tester/rule-tester.js
index 0d1319c11a2..83b91c45d56 100644
--- a/lib/rule-tester/rule-tester.js
+++ b/lib/rule-tester/rule-tester.js
@@ -177,7 +177,6 @@ class RuleTester {
     /**
      * Creates a new instance of RuleTester.
      * @param {Object} [testerConfig] Optional, extra configuration for the tester
-     * @constructor
      */
     constructor(testerConfig) {
 
diff --git a/lib/rules/indent-legacy.js b/lib/rules/indent-legacy.js
index fb84b732ea3..f1c024c3684 100644
--- a/lib/rules/indent-legacy.js
+++ b/lib/rules/indent-legacy.js
@@ -303,7 +303,7 @@ module.exports = {
          * @param {int} needed Expected indentation character count
          * @param {int} gottenSpaces Indentation space count in the actual node/code
          * @param {int} gottenTabs Indentation tab count in the actual node/code
-         * @param {Object=} loc Error line and column location
+         * @param {Object} [loc] Error line and column location
          * @param {boolean} isLastNodeCheck Is the error for last node check
          * @returns {void}
          */
diff --git a/lib/shared/logging.js b/lib/shared/logging.js
index 3eb898c34f8..6aa1f5a1e59 100644
--- a/lib/shared/logging.js
+++ b/lib/shared/logging.js
@@ -12,6 +12,7 @@ module.exports = {
 
     /**
      * Cover for console.log
+     * @param {...any} args The elements to log.
      * @returns {void}
      */
     info(...args) {
@@ -20,6 +21,7 @@ module.exports = {
 
     /**
      * Cover for console.error
+     * @param {...any} args The elements to log.
      * @returns {void}
      */
     error(...args) {
diff --git a/lib/source-code/source-code.js b/lib/source-code/source-code.js
index 88a9c0a4e43..42e7b0c2f47 100644
--- a/lib/source-code/source-code.js
+++ b/lib/source-code/source-code.js
@@ -93,7 +93,6 @@ class SourceCode extends TokenStore {
      * @param {ScopeManager|null} textOrConfig.scopeManager - The scope of this source code.
      * @param {Object|null} textOrConfig.visitorKeys - The visitor keys to traverse AST.
      * @param {ASTNode} [astIfNoConfig] - The Program node of the AST representing the code. This AST should be created from the text that BOM was stripped.
-     * @constructor
      */
     constructor(textOrConfig, astIfNoConfig) {
         let text, ast, parserServices, scopeManager, visitorKeys;
@@ -206,9 +205,9 @@ 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.
+     * @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.
      * @returns {string} The text representing the AST node.
      * @public
      */
diff --git a/package.json b/package.json
index 9ce1c59b0d9..fa38b0792f8 100644
--- a/package.json
+++ b/package.json
@@ -96,6 +96,7 @@
     "eslint-config-eslint": "file:packages/eslint-config-eslint",
     "eslint-plugin-eslint-plugin": "^2.0.1",
     "eslint-plugin-internal-rules": "file:tools/internal-rules",
+    "eslint-plugin-jsdoc": "^15.9.5",
     "eslint-plugin-node": "^9.0.0",
     "eslint-release": "^1.2.0",
     "eslump": "^2.0.0",
diff --git a/packages/eslint-config-eslint/default.yml b/packages/eslint-config-eslint/default.yml
index 526ce5600ef..1bbc1c57621 100644
--- a/packages/eslint-config-eslint/default.yml
+++ b/packages/eslint-config-eslint/default.yml
@@ -1,6 +1,16 @@
 extends:
     - "eslint:recommended"
     - "plugin:node/recommended"
+plugins:
+    - "jsdoc"
+settings:
+    jsdoc:
+        tagNamePreference:
+            file: "fileoverview"
+            augments: "extends"
+            class: "constructor"
+        preferredTypes:
+            object: "Object"
 rules:
     array-bracket-spacing: "error"
     array-callback-return: "error"
@@ -31,6 +41,20 @@ rules:
     generator-star-spacing: "error"
     guard-for-in: "error"
     handle-callback-err: ["error", "err"]
+    jsdoc/check-alignment: "error"
+    jsdoc/check-param-names: "error"
+    jsdoc/check-syntax: "error"
+    jsdoc/check-tag-names: "error"
+    jsdoc/check-types: "error"
+    jsdoc/implements-on-classes: "error"
+    jsdoc/require-jsdoc: "error"
+    jsdoc/require-param: "error"
+    jsdoc/require-param-description: "error"
+    jsdoc/require-param-name: "error"
+    jsdoc/require-param-type: "error"
+    jsdoc/require-returns: ["error", { forceRequireReturn: true, forceReturnsWithAsync: true }]
+    jsdoc/require-returns-description: "error"
+    jsdoc/require-returns-type: "error"
     key-spacing: ["error", { beforeColon: false, afterColon: true }]
     keyword-spacing: "error"
     lines-around-comment: ["error", {
@@ -154,7 +178,6 @@ rules:
     quotes: ["error", "double", {avoidEscape: true}]
     quote-props: ["error", "as-needed"]
     radix: "error"
-    require-jsdoc: "error"
     require-unicode-regexp: "error"
     rest-spread-spacing: "error"
     semi: "error"
@@ -172,17 +195,6 @@ rules:
     template-curly-spacing: ["error", "never"]
     template-tag-spacing: "error"
     unicode-bom: "error"
-    valid-jsdoc: ["error", {
-        prefer: { "return": "returns"},
-        preferType: {
-            "String": "string",
-            "Number": "number",
-            "Boolean": "boolean",
-            "array": "Array",
-            "object": "Object",
-            "function": "Function"
-        }
-    }]
     wrap-iife: "error"
     yield-star-spacing: "error"
     yoda: ["error", "never"]
diff --git a/packages/eslint-config-eslint/package.json b/packages/eslint-config-eslint/package.json
index 514dbb7ca42..48bfb65f50a 100644
--- a/packages/eslint-config-eslint/package.json
+++ b/packages/eslint-config-eslint/package.json
@@ -20,6 +20,7 @@
   "homepage": "https://eslint.org",
   "bugs": "https://github.com/eslint/eslint/issues/",
   "peerDependencies": {
+    "eslint-plugin-jsdoc": "^15.9.5",
     "eslint-plugin-node": "^9.0.0"
   },
   "keywords": [
diff --git a/tests/lib/_utils.js b/tests/lib/_utils.js
index 3251a602360..2ac119fb732 100644
--- a/tests/lib/_utils.js
+++ b/tests/lib/_utils.js
@@ -25,7 +25,6 @@ function unIndent(strings, ...values) {
     return lines.map(line => line.slice(minLineIndent)).join("\n");
 }
 
-// eslint-disable-next-line valid-jsdoc
 /**
  * Add support of `recursive` option.
  * @param {import("fs")} fs The in-memory file system.
@@ -56,7 +55,6 @@ function supportMkdirRecursiveOption(fs, cwd) {
     };
 }
 
-// eslint-disable-next-line valid-jsdoc
 /**
  * Define in-memory file system.
  * @param {Object} options The options.
diff --git a/tests/lib/cli-engine/_utils.js b/tests/lib/cli-engine/_utils.js
index a3c56484c64..bff1801f342 100644
--- a/tests/lib/cli-engine/_utils.js
+++ b/tests/lib/cli-engine/_utils.js
@@ -53,9 +53,6 @@
  */
 "use strict";
 
-// To use TypeScript type annotations for VSCode intellisense.
-/* eslint-disable valid-jsdoc */
-
 const path = require("path");
 const vm = require("vm");
 const Proxyquire = require("proxyquire/lib/proxyquire");
diff --git a/tests/lib/cli-engine/cascading-config-array-factory.js b/tests/lib/cli-engine/cascading-config-array-factory.js
index e0ca4f06378..22c9b956dda 100644
--- a/tests/lib/cli-engine/cascading-config-array-factory.js
+++ b/tests/lib/cli-engine/cascading-config-array-factory.js
@@ -85,6 +85,7 @@ describe("CascadingConfigArrayFactory", () => {
 
             /**
              * Returns the path inside of the fixture directory.
+             * @param {...string} args file path segments.
              * @returns {string} The path inside the fixture directory.
              * @private
              */
@@ -671,6 +672,7 @@ describe("CascadingConfigArrayFactory", () => {
 
                 /**
                  * Returns the path inside of the fixture directory.
+                 * @param {...string} args file path segments.
                  * @returns {string} The path inside the fixture directory.
                  * @private
                  */
@@ -766,6 +768,7 @@ describe("CascadingConfigArrayFactory", () => {
 
                 /**
                  * Returns the path inside of the fixture directory.
+                 * @param {...string} args file path segments.
                  * @returns {string} The path inside the fixture directory.
                  * @private
                  */
diff --git a/tests/lib/cli-engine/cli-engine.js b/tests/lib/cli-engine/cli-engine.js
index b3039e74314..223cb66073c 100644
--- a/tests/lib/cli-engine/cli-engine.js
+++ b/tests/lib/cli-engine/cli-engine.js
@@ -50,6 +50,7 @@ describe("CLIEngine", () => {
 
     /**
      * Returns the path inside of the fixture directory.
+     * @param {...string} args file path segments.
      * @returns {string} The path inside the fixture directory.
      * @private
      */
@@ -1543,7 +1544,11 @@ describe("CLIEngine", () => {
             engine = new CLIEngine({
                 cwd: originalDir,
                 configFile: ".eslintrc.js",
-                rules: { "indent-legacy": 1 }
+                rules: {
+                    "indent-legacy": 1,
+                    "require-jsdoc": 1,
+                    "valid-jsdoc": 1
+                }
             });
 
             const report = engine.executeOnFiles(["lib/cli*.js"]);
diff --git a/tests/lib/cli-engine/file-enumerator.js b/tests/lib/cli-engine/file-enumerator.js
index 13ff479dba2..d379ac520d6 100644
--- a/tests/lib/cli-engine/file-enumerator.js
+++ b/tests/lib/cli-engine/file-enumerator.js
@@ -173,6 +173,7 @@ describe("FileEnumerator", () => {
 
             /**
              * Returns the path inside of the fixture directory.
+             * @param {...string} args file path segments.
              * @returns {string} The path inside the fixture directory.
              * @private
              */
diff --git a/tests/lib/cli-engine/ignored-paths.js b/tests/lib/cli-engine/ignored-paths.js
index 4870244270a..7fd8e8408ca 100644
--- a/tests/lib/cli-engine/ignored-paths.js
+++ b/tests/lib/cli-engine/ignored-paths.js
@@ -92,6 +92,7 @@ function countDefaultPatterns(ignoredPaths) {
 
 /**
  * Returns the path inside of the fixture directory.
+ * @param {...string} args file path segments.
  * @returns {string} The path inside the fixture directory.
  * @private
  */
diff --git a/tests/lib/cli.js b/tests/lib/cli.js
index 1b98fb137a7..e0f10d5ae4d 100644
--- a/tests/lib/cli.js
+++ b/tests/lib/cli.js
@@ -71,6 +71,7 @@ describe("cli", () => {
 
     /**
      * Returns the path inside of the fixture directory.
+     * @param {...string} args file path segments.
      * @returns {string} The path inside the fixture directory.
      * @private
      */
diff --git a/tests/lib/init/config-initializer.js b/tests/lib/init/config-initializer.js
index ed2388fd568..3393ae2befa 100644
--- a/tests/lib/init/config-initializer.js
+++ b/tests/lib/init/config-initializer.js
@@ -57,6 +57,7 @@ describe("configInitializer", () => {
 
     /**
      * Returns the path inside of the fixture directory.
+     * @param {...string} args file path segments.
      * @returns {string} The path inside the fixture directory.
      * @private
      */
diff --git a/tests/lib/init/source-code-utils.js b/tests/lib/init/source-code-utils.js
index a5c9e90a1b2..8c821de7832 100644
--- a/tests/lib/init/source-code-utils.js
+++ b/tests/lib/init/source-code-utils.js
@@ -31,6 +31,7 @@ describe("SourceCodeUtil", () => {
 
     /**
      * Returns the path inside of the fixture directory.
+     * @param {...string} args file path segments.
      * @returns {string} The path inside the fixture directory.
      * @private
      */
diff --git a/tests/tools/loose-parser.js b/tests/tools/loose-parser.js
index abb3aeb5bd0..98e97cc3687 100644
--- a/tests/tools/loose-parser.js
+++ b/tests/tools/loose-parser.js
@@ -9,7 +9,6 @@
 const acorn = require("acorn");
 const espree = require("espree/lib/espree");
 
-// eslint-disable-next-line valid-jsdoc
 /**
  * Define the parser which ignores recoverable errors.
  * @returns {(parser:acorn.Parser) => acorn.Parser} The function that defines loose parser.
diff --git a/tools/code-sample-minimizer.js b/tools/code-sample-minimizer.js
index 63a687e56fb..2954bf08f10 100644
--- a/tools/code-sample-minimizer.js
+++ b/tools/code-sample-minimizer.js
@@ -30,6 +30,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
  * @param {Parser} [options.parser] The parser used to parse the source text. Defaults to a modified
diff --git a/tools/internal-rules/no-invalid-meta.js b/tools/internal-rules/no-invalid-meta.js
index aeb7862fa2e..016643a8d80 100644
--- a/tools/internal-rules/no-invalid-meta.js
+++ b/tools/internal-rules/no-invalid-meta.js
@@ -104,7 +104,6 @@ function hasMetaSchema(metaPropertyNode) {
  *
  * @param {RuleContext} context The ESLint rule context.
  * @param {ASTNode} exportsNode ObjectExpression node that the rule exports.
- * @param {boolean} ruleIsFixable whether the rule is fixable or not.
  * @returns {void}
  */
 function checkMetaValidity(context, exportsNode) {