feat: add ignoreReplacesDocs setting (defaulting to true); fixes #780…

… (#781)
gajus · Sep 7, 2021 · f8297aa · f8297aa
1 parent 98a6d35
commit f8297aa
Show file tree

Hide file tree

Showing 10 changed files with 176 additions and 19 deletions.
diff --git a/.README/README.md b/.README/README.md
@@ -316,13 +316,14 @@ This setting is utilized by the the rule for tag name checking
 - `require-returns-description`
 - `require-returns-type`
 
-### `@override`/`@augments`/`@extends`/`@implements` Without Accompanying `@param`/`@description`/`@example`/`@returns`
+### `@override`/`@augments`/`@extends`/`@implements`/`@ignore` Without Accompanying `@param`/`@description`/`@example`/`@returns`/`@throws`/`@yields`
 
 The following settings allows the element(s) they reference to be omitted
 on the JSDoc comment block of the function or that of its parent class
 for any of the "require" rules (i.e., `require-param`, `require-description`,
-`require-example`, or `require-returns`).
+`require-example`, `require-returns`, `require-throws`, `require-yields`).
 
+* `settings.jsdoc.ignoreReplacesDocs` (`@ignore`) - Defaults to `true`
 * `settings.jsdoc.overrideReplacesDocs` (`@override`) - Defaults to `true`
 * `settings.jsdoc.augmentsExtendsReplacesDocs` (`@augments` or its alias
     `@extends`) - Defaults to `false`.
@@ -335,6 +336,7 @@ The format of the configuration is as follows:
     "rules": {},
     "settings": {
         "jsdoc": {
+            "ignoreReplacesDocs": true,
             "overrideReplacesDocs": true,
             "augmentsExtendsReplacesDocs": true,
             "implementsReplacesDocs": true

diff --git a/.README/rules/require-description.md b/.README/rules/require-description.md
@@ -39,6 +39,6 @@ An options object may have any of the following properties:
 | Aliases  | `desc`                                                                                                        |
 | Recommended | false |
 | Options  | `contexts`, `exemptedBy`, `descriptionStyle`, `checkConstructors`, `checkGetters`, `checkSetters`             |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`                               |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`                               |
 
 <!-- assertions requireDescription -->
diff --git a/.README/rules/require-example.md b/.README/rules/require-example.md
@@ -58,6 +58,6 @@ report a missing example description after this is added.
 |Tags|`example`|
 |Recommended|false|
 |Options|`exemptedBy`, `exemptNoArguments`, `avoidExampleOnConstructors`, `contexts`|
-|Settings|`overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
+|Settings|`ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 <!-- assertions requireExample -->
diff --git a/.README/rules/require-param.md b/.README/rules/require-param.md
@@ -374,6 +374,6 @@ supplied as default values. Defaults to `false`.
 | Aliases  | `arg`, `argument` |
 |Recommended | true|
 | Options  | `autoIncrementBase`, `checkDestructured`, `checkDestructuredRoots`, `contexts`, `enableFixer`, `enableRootFixer`, `enableRestElementFixer`, `checkRestProperty`, `exemptedBy`, `checkConstructors`, `checkGetters`, `checkSetters`, `checkTypesPattern`, `unnamedRootBase`, `useDefaultObjectProperties`|
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 <!-- assertions requireParam -->
diff --git a/.README/rules/require-returns.md b/.README/rules/require-returns.md
@@ -48,6 +48,6 @@ Will also report if multiple `@returns` tags are present.
 | Aliases  | `return` |
 |Recommended|true|
 | Options  | `checkConstructors`, `checkGetters`, `contexts`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync` |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 <!-- assertions requireReturns -->
diff --git a/.README/rules/require-throws.md b/.README/rules/require-throws.md
@@ -29,6 +29,6 @@ Requires that throw statements are documented.
 | Aliases  | `exception` |
 |Recommended|true|
 | Options  | `contexts`, `exemptedBy` |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 <!-- assertions requireThrows -->
diff --git a/.README/rules/require-yields.md b/.README/rules/require-yields.md
@@ -62,6 +62,6 @@ option to expect a non-standard `@next` tag.
 |Aliases|`yield`|
 |Recommended|true|
 | Options  | `contexts`,  `exemptedBy`, `withGeneratorTag`, `nextWithGeneratorTag`, `forceRequireYields`, `next` |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 <!-- assertions requireYields -->
diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@ JSDoc linting rules for ESLint.
         * [`maxLines` and `minLines`](#eslint-plugin-jsdoc-settings-maxlines-and-minlines)
         * [Mode](#eslint-plugin-jsdoc-settings-mode)
         * [Alias Preference](#eslint-plugin-jsdoc-settings-alias-preference)
-        * [`@override`/`@augments`/`@extends`/`@implements` Without Accompanying `@param`/`@description`/`@example`/`@returns`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns)
+        * [`@override`/`@augments`/`@extends`/`@implements`/`@ignore` Without Accompanying `@param`/`@description`/`@example`/`@returns`/`@throws`/`@yields`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-ignore-without-accompanying-param-description-example-returns-throws-yields)
         * [Settings to Configure `check-types` and `no-undefined-types`](#eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types)
         * [`structuredTags`](#eslint-plugin-jsdoc-settings-structuredtags)
     * [Advanced](#eslint-plugin-jsdoc-advanced)
@@ -389,14 +389,15 @@ This setting is utilized by the the rule for tag name checking
 - `require-returns-description`
 - `require-returns-type`
 
-<a name="eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns"></a>
-### <code>@override</code>/<code>@augments</code>/<code>@extends</code>/<code>@implements</code> Without Accompanying <code>@param</code>/<code>@description</code>/<code>@example</code>/<code>@returns</code>
+<a name="eslint-plugin-jsdoc-settings-override-augments-extends-implements-ignore-without-accompanying-param-description-example-returns-throws-yields"></a>
+### <code>@override</code>/<code>@augments</code>/<code>@extends</code>/<code>@implements</code>/<code>@ignore</code> Without Accompanying <code>@param</code>/<code>@description</code>/<code>@example</code>/<code>@returns</code>/<code>@throws</code>/<code>@yields</code>
 
 The following settings allows the element(s) they reference to be omitted
 on the JSDoc comment block of the function or that of its parent class
 for any of the "require" rules (i.e., `require-param`, `require-description`,
-`require-example`, or `require-returns`).
+`require-example`, `require-returns`, `require-throws`, `require-yields`).
 
+* `settings.jsdoc.ignoreReplacesDocs` (`@ignore`) - Defaults to `true`
 * `settings.jsdoc.overrideReplacesDocs` (`@override`) - Defaults to `true`
 * `settings.jsdoc.augmentsExtendsReplacesDocs` (`@augments` or its alias
     `@extends`) - Defaults to `false`.
@@ -409,6 +410,7 @@ The format of the configuration is as follows:
     "rules": {},
     "settings": {
         "jsdoc": {
+            "ignoreReplacesDocs": true,
             "overrideReplacesDocs": true,
             "augmentsExtendsReplacesDocs": true,
             "implementsReplacesDocs": true
@@ -10747,7 +10749,7 @@ An options object may have any of the following properties:
 | Aliases  | `desc`                                                                                                        |
 | Recommended | false |
 | Options  | `contexts`, `exemptedBy`, `descriptionStyle`, `checkConstructors`, `checkGetters`, `checkSetters`             |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`                               |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`                               |
 
 The following patterns are considered problems:
 
@@ -11326,7 +11328,7 @@ report a missing example description after this is added.
 |Tags|`example`|
 |Recommended|false|
 |Options|`exemptedBy`, `exemptNoArguments`, `avoidExampleOnConstructors`, `contexts`|
-|Settings|`overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
+|Settings|`ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 The following patterns are considered problems:
 
@@ -14531,7 +14533,7 @@ supplied as default values. Defaults to `false`.
 | Aliases  | `arg`, `argument` |
 |Recommended | true|
 | Options  | `autoIncrementBase`, `checkDestructured`, `checkDestructuredRoots`, `contexts`, `enableFixer`, `enableRootFixer`, `enableRestElementFixer`, `checkRestProperty`, `exemptedBy`, `checkConstructors`, `checkGetters`, `checkSetters`, `checkTypesPattern`, `unnamedRootBase`, `useDefaultObjectProperties`|
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 The following patterns are considered problems:
 
@@ -14723,6 +14725,15 @@ function quux (foo) {
 // Settings: {"jsdoc":{"overrideReplacesDocs":false}}
 // Message: Missing JSDoc @param "foo" declaration.
 
+/**
+ * @ignore
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"ignoreReplacesDocs":false}}
+// Message: Missing JSDoc @param "foo" declaration.
+
 /**
  * @implements
  */
@@ -14762,6 +14773,20 @@ class A {
 // Settings: {"jsdoc":{"overrideReplacesDocs":false}}
 // Message: Missing JSDoc @param "foo" declaration.
 
+/**
+ * @ignore
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Settings: {"jsdoc":{"ignoreReplacesDocs":false}}
+// Message: Missing JSDoc @param "foo" declaration.
+
 /**
  * @implements
  */
@@ -15302,6 +15327,14 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"overrideReplacesDocs":true}}
 
+/**
+ * @ignore
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"ignoreReplacesDocs":true}}
+
 /**
  * @implements
  */
@@ -15410,6 +15443,19 @@ class A {
 }
 // Settings: {"jsdoc":{"overrideReplacesDocs":true}}
 
+/**
+ * @ignore
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Settings: {"jsdoc":{"ignoreReplacesDocs":true}}
+
 /**
  * @implements
  */
@@ -17011,7 +17057,7 @@ Will also report if multiple `@returns` tags are present.
 | Aliases  | `return` |
 |Recommended|true|
 | Options  | `checkConstructors`, `checkGetters`, `contexts`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync` |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 The following patterns are considered problems:
 
@@ -18055,7 +18101,7 @@ Requires that throw statements are documented.
 | Aliases  | `exception` |
 |Recommended|true|
 | Options  | `contexts`, `exemptedBy` |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 The following patterns are considered problems:
 
@@ -18365,7 +18411,7 @@ option to expect a non-standard `@next` tag.
 |Aliases|`yield`|
 |Recommended|true|
 | Options  | `contexts`,  `exemptedBy`, `withGeneratorTag`, `nextWithGeneratorTag`, `forceRequireYields`, `next` |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 The following patterns are considered problems:
 

diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js
@@ -78,6 +78,7 @@ const getUtils = (
   const {
     tagNamePreference,
     overrideReplacesDocs,
+    ignoreReplacesDocs,
     implementsReplacesDocs,
     augmentsExtendsReplacesDocs,
     maxLines,
@@ -439,6 +440,8 @@ const getUtils = (
 
   utils.avoidDocs = () => {
     if (
+      ignoreReplacesDocs !== false &&
+        (utils.hasTag('ignore') || utils.classHasTag('ignore')) ||
       overrideReplacesDocs !== false &&
         (utils.hasTag('override') || utils.classHasTag('override')) ||
       implementsReplacesDocs !== false &&
@@ -651,8 +654,10 @@ const getSettings = (context) => {
     // `check-types`, `no-undefined-types`, `valid-types`
     structuredTags: context.settings.jsdoc?.structuredTags ?? {},
 
-    // `require-param`, `require-description`, `require-example`, `require-returns`
+    // `require-param`, `require-description`, `require-example`,
+    // `require-returns`, `require-throw`, `require-yields`
     overrideReplacesDocs: context.settings.jsdoc?.overrideReplacesDocs,
+    ignoreReplacesDocs: context.settings.jsdoc?.ignoreReplacesDocs,
     implementsReplacesDocs: context.settings.jsdoc?.implementsReplacesDocs,
     augmentsExtendsReplacesDocs: context.settings.jsdoc?.augmentsExtendsReplacesDocs,
 

diff --git a/test/rules/assertions/requireParam.js b/test/rules/assertions/requireParam.js
@@ -700,6 +700,36 @@ export default {
         },
       },
     },
+    {
+      code: `
+          /**
+           * @ignore
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @param "foo" declaration.',
+        },
+      ],
+      output: `
+          /**
+           * @param foo
+           * @ignore
+           */
+          function quux (foo) {
+
+          }
+      `,
+      settings: {
+        jsdoc: {
+          ignoreReplacesDocs: false,
+        },
+      },
+    },
     {
       code: `
           /**
@@ -819,6 +849,45 @@ export default {
         },
       },
     },
+    {
+      code: `
+          /**
+           * @ignore
+           */
+          class A {
+            /**
+             *
+             */
+            quux (foo) {
+
+            }
+          }
+      `,
+      errors: [
+        {
+          line: 6,
+          message: 'Missing JSDoc @param "foo" declaration.',
+        },
+      ],
+      output: `
+          /**
+           * @ignore
+           */
+          class A {
+            /**
+             * @param foo
+             */
+            quux (foo) {
+
+            }
+          }
+      `,
+      settings: {
+        jsdoc: {
+          ignoreReplacesDocs: false,
+        },
+      },
+    },
     {
       code: `
           /**
@@ -2412,6 +2481,21 @@ export default {
         },
       },
     },
+    {
+      code: `
+          /**
+           * @ignore
+           */
+          function quux (foo) {
+
+          }
+      `,
+      settings: {
+        jsdoc: {
+          ignoreReplacesDocs: true,
+        },
+      },
+    },
     {
       code: `
           /**
@@ -2580,6 +2664,26 @@ export default {
         },
       },
     },
+    {
+      code: `
+          /**
+           * @ignore
+           */
+          class A {
+            /**
+             *
+             */
+            quux (foo) {
+
+            }
+          }
+      `,
+      settings: {
+        jsdoc: {
+          ignoreReplacesDocs: true,
+        },
+      },
+    },
     {
       code: `
           /**