Chore: Apply comment require-description and check ClassDeclaration (#…

…14949) * Chore: Apply comment require-description and check ClassDeclaration's * Update Makefile.js Co-authored-by: Bryan Mishkin <698306+bmish@users.noreply.github.com> * Fix: Avoid eslintrc for tests to avoid requiring comment description Co-authored-by: Bryan Mishkin <698306+bmish@users.noreply.github.com>
eslint · Aug 21, 2021 · 9a4ae3b · 9a4ae3b
1 parent 8344675
commit 9a4ae3b
Show file tree

Hide file tree

Showing 64 changed files with 145 additions and 143 deletions.
diff --git a/Makefile.js b/Makefile.js
@@ -3,8 +3,8 @@
  * @author nzakas
  */
 
-/* global target */
-/* eslint no-use-before-define: "off", no-console: "off" */
+/* global target -- TODO: figure out where this is coming from and update this description */
+/* eslint no-use-before-define: "off", no-console: "off" -- CLI */
 "use strict";
 
 //------------------------------------------------------------------------------

diff --git a/bin/eslint.js b/bin/eslint.js
@@ -5,7 +5,7 @@
  * @author Nicholas C. Zakas
  */
 
-/* eslint no-console:off */
+/* eslint no-console:off -- CLI */
 
 "use strict";
 

diff --git a/conf/eslint-recommended.js b/conf/eslint-recommended.js
@@ -6,7 +6,7 @@
 
 "use strict";
 
-/* eslint sort-keys: ["error", "asc"] */
+/* eslint sort-keys: ["error", "asc"] -- Long, so make more readable */
 
 /** @type {import("../lib/shared/types").ConfigData} */
 module.exports = {

diff --git a/lib/cli-engine/cli-engine.js b/lib/cli-engine/cli-engine.js
@@ -562,6 +562,9 @@ function directoryExists(resolvedPath) {
 // Public Interface
 //------------------------------------------------------------------------------
 
+/**
+ * Core CLI.
+ */
 class CLIEngine {
 
     /**

diff --git a/lib/cli-engine/file-enumerator.js b/lib/cli-engine/file-enumerator.js
@@ -175,7 +175,6 @@ function createExtensionRegExp(extensions) {
  */
 class NoFilesFoundError extends Error {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @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.
@@ -192,7 +191,6 @@ class NoFilesFoundError extends Error {
  */
 class AllFilesIgnoredError extends Error {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {string} pattern The glob pattern which was not found.
      */

diff --git a/lib/cli-engine/formatters/html.js b/lib/cli-engine/formatters/html.js
@@ -281,8 +281,8 @@ function resultTemplate(it) {
 `.trimLeft();
 }
 
-// eslint-disable-next-line jsdoc/require-description
 /**
+ * Render the results.
  * @param {Array} results Test results.
  * @param {Object} rulesMeta Dictionary containing metadata for each rule executed by the analysis.
  * @returns {string} HTML string describing the results.

diff --git a/lib/cli-engine/xml-escape.js b/lib/cli-engine/xml-escape.js
@@ -15,7 +15,7 @@
  * @private
  */
 module.exports = function(s) {
-    return (`${s}`).replace(/[<>&"'\x00-\x1F\x7F\u0080-\uFFFF]/gu, c => { // eslint-disable-line no-control-regex
+    return (`${s}`).replace(/[<>&"'\x00-\x1F\x7F\u0080-\uFFFF]/gu, c => { // eslint-disable-line no-control-regex -- Converting controls to entities
         switch (c) {
             case "<":
                 return "&lt;";

diff --git a/lib/config/flat-config-array.js b/lib/config/flat-config-array.js
@@ -61,7 +61,7 @@ class FlatConfigArray extends ConfigArray {
         this.unshift(baseConfig);
     }
 
-    /* eslint-disable class-methods-use-this */
+    /* eslint-disable class-methods-use-this -- Desired as instance method */
     /**
      * Replaces a config with another config to allow us to put strings
      * in the config array that will be replaced by objects before
@@ -118,7 +118,7 @@ class FlatConfigArray extends ConfigArray {
 
         return config;
     }
-    /* eslint-enable class-methods-use-this */
+    /* eslint-enable class-methods-use-this -- Desired as instance method */
 
 }
 

diff --git a/lib/config/flat-config-schema.js b/lib/config/flat-config-schema.js
@@ -336,7 +336,7 @@ const rulesSchema = {
             // avoid hairy edge case
             if (ruleId === "__proto__") {
 
-                /* eslint-disable-next-line no-proto */
+                /* eslint-disable-next-line no-proto -- Though deprecated, may still be present */
                 delete result.__proto__;
                 continue;
             }

diff --git a/lib/eslint/eslint.js b/lib/eslint/eslint.js
@@ -422,6 +422,9 @@ function compareResultsByFilePath(a, b) {
     return 0;
 }
 
+/**
+ * Main API.
+ */
 class ESLint {
 
     /**

diff --git a/lib/init/autoconfig.js b/lib/init/autoconfig.js
@@ -73,7 +73,6 @@ function makeRegistryItems(rulesConfig) {
  */
 class Registry {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {rulesConfig} [rulesConfig] Hash of rule names and arrays of possible configurations
      */
@@ -305,7 +304,7 @@ class Registry {
                 ruleSetIdx += 1;
 
                 if (cb) {
-                    cb(totalFilesLinting); // eslint-disable-line node/callback-return
+                    cb(totalFilesLinting); // eslint-disable-line node/callback-return -- End of function
                 }
             });
 

diff --git a/lib/init/config-rule.js b/lib/init/config-rule.js
@@ -174,7 +174,6 @@ function combinePropertyObjects(objArr1, objArr2) {
  */
 class RuleConfigSet {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {ruleConfig[]} configs Valid rule configurations
      */

diff --git a/lib/init/source-code-utils.js b/lib/init/source-code-utils.js
@@ -23,7 +23,7 @@ const { CLIEngine } = require("../cli-engine");
  * TODO1: Expose the API that enumerates target files.
  * TODO2: Extract the creation logic of `SourceCode` from `Linter` class.
  */
-const { getCLIEngineInternalSlots } = require("../cli-engine/cli-engine"); // eslint-disable-line node/no-restricted-require
+const { getCLIEngineInternalSlots } = require("../cli-engine/cli-engine"); // eslint-disable-line node/no-restricted-require -- Todo
 
 const debug = require("debug")("eslint:source-code-utils");
 
@@ -98,7 +98,7 @@ function getSourceCodeOfFiles(patterns, options, callback) {
             sourceCodes[filename] = sourceCode;
         }
         if (callback) {
-            callback(filenames.length); // eslint-disable-line node/callback-return
+            callback(filenames.length); // eslint-disable-line node/callback-return -- End of function
         }
     });
 

diff --git a/lib/linter/code-path-analysis/code-path-analyzer.js b/lib/linter/code-path-analysis/code-path-analyzer.js
@@ -674,7 +674,6 @@ function postprocess(analyzer, node) {
  */
 class CodePathAnalyzer {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {EventGenerator} eventGenerator An event generator to wrap.
      */

diff --git a/lib/linter/code-path-analysis/code-path-segment.js b/lib/linter/code-path-analysis/code-path-segment.js
@@ -33,7 +33,6 @@ function isReachable(segment) {
  */
 class CodePathSegment {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {string} id An identifier.
      * @param {CodePathSegment[]} allPrevSegments An array of the previous segments.

diff --git a/lib/linter/code-path-analysis/code-path-state.js b/lib/linter/code-path-analysis/code-path-state.js
@@ -219,7 +219,6 @@ function finalizeTestSegmentsOfFor(context, choiceContext, head) {
  */
 class CodePathState {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {IdGenerator} idGenerator An id generator to generate id for code
      *   path segments.

diff --git a/lib/linter/code-path-analysis/code-path.js b/lib/linter/code-path-analysis/code-path.js
@@ -21,7 +21,6 @@ const IdGenerator = require("./id-generator");
  */
 class CodePath {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {string} id An identifier.
      * @param {CodePath|null} upper The code path of the upper function scope.

diff --git 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 jsdoc/require-jsdoc
+function getId(segment) { // eslint-disable-line jsdoc/require-jsdoc -- Ignoring
     return segment.id + (segment.reachable ? "" : "!");
 }
 
@@ -115,7 +115,7 @@ module.exports = {
         const traceMap = Object.create(null);
         const arrows = this.makeDotArrows(codePath, traceMap);
 
-        for (const id in traceMap) { // eslint-disable-line guard-for-in
+        for (const id in traceMap) { // eslint-disable-line guard-for-in -- Want ability to traverse prototype
             const segment = traceMap[id];
 
             text += `${id}[`;

diff --git a/lib/linter/code-path-analysis/fork-context.js b/lib/linter/code-path-analysis/fork-context.js
@@ -97,7 +97,6 @@ function mergeExtraSegments(context, segments) {
  */
 class ForkContext {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {IdGenerator} idGenerator An identifier generator for segments.
      * @param {ForkContext|null} upper An upper fork context.

diff --git a/lib/linter/code-path-analysis/id-generator.js b/lib/linter/code-path-analysis/id-generator.js
@@ -18,7 +18,6 @@
  */
 class IdGenerator {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {string} prefix Optional. A prefix of generated ids.
      */

diff --git a/lib/linter/config-comment-parser.js b/lib/linter/config-comment-parser.js
@@ -3,7 +3,7 @@
  * @author Nicholas C. Zakas
  */
 
-/* eslint class-methods-use-this: off */
+/* eslint class-methods-use-this: off -- Methods desired on instance */
 "use strict";
 
 //------------------------------------------------------------------------------

diff --git a/lib/linter/linter.js b/lib/linter/linter.js
@@ -65,7 +65,7 @@ const parserSymbol = Symbol.for("eslint.RuleTester.parser");
  * @template T
  * @typedef {{ [P in keyof T]-?: T[P] }} Required
  */
-/* eslint-enable jsdoc/valid-types */
+/* eslint-enable jsdoc/valid-types -- https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser/issues/4#issuecomment-778805577 */
 
 /**
  * @typedef {Object} DisableDirective
@@ -1044,7 +1044,7 @@ function normalizeCwd(cwd) {
     }
 
     // It's more explicit to assign the undefined
-    // eslint-disable-next-line no-undefined
+    // eslint-disable-next-line no-undefined -- Consistently returning a value
     return undefined;
 }
 

diff --git a/lib/linter/node-event-generator.js b/lib/linter/node-event-generator.js
@@ -237,7 +237,6 @@ function parseSelector(rawSelector) {
  */
 class NodeEventGenerator {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {SafeEmitter} emitter
      * An SafeEmitter which is the destination of events. This emitter must already

diff --git a/lib/linter/rules.js b/lib/linter/rules.js
@@ -30,6 +30,9 @@ function normalizeRule(rule) {
 // Public Interface
 //------------------------------------------------------------------------------
 
+/**
+ * A storage for rules.
+ */
 class Rules {
     constructor() {
         this._rules = Object.create(null);

diff --git a/lib/linter/timing.js b/lib/linter/timing.js
@@ -116,7 +116,7 @@ function display(data) {
         return ALIGN[index](":", width + extraAlignment, "-");
     }).join("|"));
 
-    console.log(table.join("\n")); // eslint-disable-line no-console
+    console.log(table.join("\n")); // eslint-disable-line no-console -- Debugging function
 }
 
 /* istanbul ignore next */

diff --git a/lib/rule-tester/rule-tester.js b/lib/rule-tester/rule-tester.js
@@ -4,7 +4,7 @@
  */
 "use strict";
 
-/* global describe, it */
+/* eslint-env mocha -- Mocha wrapper */
 
 /*
  * This is a wrapper around mocha to allow for DRY unittests for eslint
@@ -106,7 +106,7 @@ const { SourceCode } = require("../source-code");
  * @property {number} [endLine] The 1-based line number of the reported end location.
  * @property {number} [endColumn] The 1-based column number of the reported end location.
  */
-/* eslint-enable jsdoc/valid-types */
+/* eslint-enable jsdoc/valid-types -- https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser/issues/4#issuecomment-778805577 */
 
 //------------------------------------------------------------------------------
 // Private Members
@@ -214,7 +214,7 @@ function freezeDeeply(x) {
  */
 function sanitize(text) {
     return text.replace(
-        /[\u0000-\u0009\u000b-\u001a]/gu, // eslint-disable-line no-control-regex
+        /[\u0000-\u0009\u000b-\u001a]/gu, // eslint-disable-line no-control-regex -- Escaping controls
         c => `\\u${c.codePointAt(0).toString(16).padStart(4, "0")}`
     );
 }
@@ -338,6 +338,9 @@ function describeDefaultHandler(text, method) {
     return method.call(this);
 }
 
+/**
+ * Mocha test wrapper.
+ */
 class RuleTester {
 
     /**

diff --git a/lib/rules/default-param-last.js b/lib/rules/default-param-last.js
@@ -25,8 +25,8 @@ module.exports = {
 
     create(context) {
 
-        // eslint-disable-next-line jsdoc/require-description
         /**
+         * Handler for function contexts.
          * @param {ASTNode} node function node
          * @returns {void}
          */

diff --git a/lib/rules/indent.js b/lib/rules/indent.js
@@ -190,7 +190,6 @@ class BinarySearchTree {
  */
 class TokenInfo {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {SourceCode} sourceCode A SourceCode object
      */
@@ -240,7 +239,6 @@ class TokenInfo {
  */
 class OffsetStorage {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {TokenInfo} tokenInfo a TokenInfo instance
      * @param {number} indentSize The desired size of each indentation level

diff --git a/lib/rules/index.js b/lib/rules/index.js
@@ -6,7 +6,7 @@
 
 "use strict";
 
-/* eslint sort-keys: ["error", "asc"] */
+/* eslint sort-keys: ["error", "asc"] -- More readable for long list */
 
 const { LazyLoadingRuleMap } = require("./utils/lazy-loading-rule-map");
 

diff --git a/lib/rules/no-dupe-keys.js b/lib/rules/no-dupe-keys.js
@@ -23,7 +23,6 @@ const SET_KIND = /^(?:init|set)$/u;
  */
 class ObjectInfo {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {ObjectInfo|null} upper The information of the outer object.
      * @param {ASTNode} node The ObjectExpression node of this information.

diff --git a/lib/rules/no-restricted-globals.js b/lib/rules/no-restricted-globals.js
@@ -43,7 +43,7 @@ module.exports = {
 
         messages: {
             defaultMessage: "Unexpected use of '{{name}}'.",
-            // eslint-disable-next-line eslint-plugin/report-message-format
+            // eslint-disable-next-line eslint-plugin/report-message-format -- Custom message might not end in a period
             customMessage: "Unexpected use of '{{name}}'. {{customMessage}}"
         }
     },

diff --git a/lib/rules/no-restricted-imports.js b/lib/rules/no-restricted-imports.js
@@ -86,19 +86,19 @@ module.exports = {
 
         messages: {
             path: "'{{importSource}}' import is restricted from being used.",
-            // eslint-disable-next-line eslint-plugin/report-message-format
+            // eslint-disable-next-line eslint-plugin/report-message-format -- Custom message might not end in a period
             pathWithCustomMessage: "'{{importSource}}' import is restricted from being used. {{customMessage}}",
 
             patterns: "'{{importSource}}' import is restricted from being used by a pattern.",
-            // eslint-disable-next-line eslint-plugin/report-message-format
+            // eslint-disable-next-line eslint-plugin/report-message-format -- Custom message might not end in a period
             patternWithCustomMessage: "'{{importSource}}' import is restricted from being used by a pattern. {{customMessage}}",
 
             everything: "* import is invalid because '{{importNames}}' from '{{importSource}}' is restricted.",
-            // eslint-disable-next-line eslint-plugin/report-message-format
+            // eslint-disable-next-line eslint-plugin/report-message-format -- Custom message might not end in a period
             everythingWithCustomMessage: "* import is invalid because '{{importNames}}' from '{{importSource}}' is restricted. {{customMessage}}",
 
             importName: "'{{importName}}' import from '{{importSource}}' is restricted.",
-            // eslint-disable-next-line eslint-plugin/report-message-format
+            // eslint-disable-next-line eslint-plugin/report-message-format -- Custom message might not end in a period
             importNameWithCustomMessage: "'{{importName}}' import from '{{importSource}}' is restricted. {{customMessage}}"
         },
 

diff --git a/lib/rules/no-restricted-modules.js b/lib/rules/no-restricted-modules.js
@@ -73,7 +73,7 @@ module.exports = {
 
         messages: {
             defaultMessage: "'{{name}}' module is restricted from being used.",
-            // eslint-disable-next-line eslint-plugin/report-message-format
+            // eslint-disable-next-line eslint-plugin/report-message-format -- Custom message might not end in a period
             customMessage: "'{{name}}' module is restricted from being used. {{customMessage}}",
             patternMessage: "'{{name}}' module is restricted from being used by a pattern."
         }