feat(require-description, require-example, require-param, `requ…

…ire-returns`): cause `exemptedBy` to overwrite `inheritdoc` exempting; closes #510

BREAKING CHANGE:

While still defaulting to having `inheritdoc` exempt rules, for the impacted rules,
if one has defined an `exemptedBy` options array one must now explicitly add
back `"inheritdoc"` to get the exemption for that tag as well. This change allows
users to omit `inheritdoc` from the array so as to cause its presence not to
trigger exemption of the rule.

.README/rules/require-description.md

@@ -18,7 +18,9 @@ An options object may have any of the following properties:
   you want the rule to apply to any jsdoc block throughout your files.
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the
     document block avoids the need for a `@description`. Defaults to an
-    empty array.
+    array with `inheritdoc`. If you set this array, it will overwrite the
+    default, so be sure to add back `inheritdoc` if you wish its presence
+    to cause exemption of the rule.
 - `descriptionStyle` - Whether to accept implicit descriptions (`"body"`) or
     `@description` tags (`"tag"`) as satisfying the rule. Set to `"any"` to
     accept either style. Defaults to `"body"`.

.README/rules/require-example.md

@@ -12,7 +12,10 @@ This rule has an object option.
 ##### `exemptedBy`
 
 Array of tags (e.g., `['type']`) whose presence on the document
-block avoids the need for an `@example`. Defaults to an empty array.
+block avoids the need for an `@example`. Defaults to an array with
+`inheritdoc`. If you set this array, it will overwrite the default,
+so be sure to add back `inheritdoc` if you wish its presence to cause
+exemption of the rule.
 
 ##### `avoidExampleOnConstructors`
 

.README/rules/require-param.md

@@ -9,7 +9,10 @@ An options object accepts two optional properties:
 ##### `exemptedBy`
 
 Array of tags (e.g., `['type']`) whose presence on the document block
-avoids the need for a `@param`. Defaults to an empty array.
+avoids the need for a `@param`. Defaults to an array with
+`inheritdoc`. If you set this array, it will overwrite the default,
+so be sure to add back `inheritdoc` if you wish its presence to cause
+exemption of the rule.
 
 ##### `contexts`
 

.README/rules/require-returns.md

@@ -9,7 +9,10 @@ Will also report if multiple `@returns` tags are present.
 - `checkGetters` - Boolean to determine whether getter methods should
   be checked for `@returns` tags. Defaults to `true`.
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-    block avoids the need for a `@returns`. Defaults to an empty array.
+    block avoids the need for a `@returns`. Defaults to an array with
+    `inheritdoc`. If you set this array, it will overwrite the default,
+    so be sure to add back `inheritdoc` if you wish its presence to cause
+    exemption of the rule.
 - `forceRequireReturn` - Set to `true` to always insist on
   `@returns` documentation regardless of implicit or explicit `return`'s
   in the function. May be desired to flag that a project is aware of an

README.md

@@ -6421,7 +6421,9 @@ An options object may have any of the following properties:
   you want the rule to apply to any jsdoc block throughout your files.
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the
     document block avoids the need for a `@description`. Defaults to an
-    empty array.
+    array with `inheritdoc`. If you set this array, it will overwrite the
+    default, so be sure to add back `inheritdoc` if you wish its presence
+    to cause exemption of the rule.
 - `descriptionStyle` - Whether to accept implicit descriptions (`"body"`) or
     `@description` tags (`"tag"`) as satisfying the rule. Set to `"any"` to
     accept either style. Defaults to `"body"`.
@@ -6715,7 +6717,10 @@ This rule has an object option.
 ##### <code>exemptedBy</code>
 
 Array of tags (e.g., `['type']`) whose presence on the document
-block avoids the need for an `@example`. Defaults to an empty array.
+block avoids the need for an `@example`. Defaults to an array with
+`inheritdoc`. If you set this array, it will overwrite the default,
+so be sure to add back `inheritdoc` if you wish its presence to cause
+exemption of the rule.
 
 <a name="eslint-plugin-jsdoc-rules-require-example-options-16-avoidexampleonconstructors"></a>
 ##### <code>avoidExampleOnConstructors</code>
@@ -8769,7 +8774,10 @@ An options object accepts two optional properties:
 ##### <code>exemptedBy</code>
 
 Array of tags (e.g., `['type']`) whose presence on the document block
-avoids the need for a `@param`. Defaults to an empty array.
+avoids the need for a `@param`. Defaults to an array with
+`inheritdoc`. If you set this array, it will overwrite the default,
+so be sure to add back `inheritdoc` if you wish its presence to cause
+exemption of the rule.
 
 <a name="eslint-plugin-jsdoc-rules-require-param-options-23-contexts-7"></a>
 ##### <code>contexts</code>
@@ -9000,6 +9008,15 @@ function quux (foo) {
 // Options: [{"exemptedBy":["notPresent"]}]
 // Message: Missing JSDoc @param "foo" declaration.
 
+/**
+ * @inheritdoc
+ */
+function quux (foo) {
+
+}
+// Options: [{"exemptedBy":[]}]
+// Message: Missing JSDoc @param "foo" declaration.
+
 /**
  * Assign the project to a list of employees.
  * @param {object[]} employees - The employees who are responsible for the project.
@@ -10328,7 +10345,10 @@ Will also report if multiple `@returns` tags are present.
 - `checkGetters` - Boolean to determine whether getter methods should
   be checked for `@returns` tags. Defaults to `true`.
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-    block avoids the need for a `@returns`. Defaults to an empty array.
+    block avoids the need for a `@returns`. Defaults to an array with
+    `inheritdoc`. If you set this array, it will overwrite the default,
+    so be sure to add back `inheritdoc` if you wish its presence to cause
+    exemption of the rule.
 - `forceRequireReturn` - Set to `true` to always insist on
   `@returns` documentation regardless of implicit or explicit `return`'s
   in the function. May be desired to flag that a project is aware of an

src/iterateJsdoc.js

@@ -238,18 +238,15 @@ const getUtils = (
       implementsReplacesDocs !== false &&
         (utils.hasTag('implements') || utils.classHasTag('implements')) ||
 
-      // inheritdoc implies that all documentation is inherited; see https://jsdoc.app/tags-inheritdoc.html
-      utils.hasTag('inheritdoc') ||
-
       augmentsExtendsReplacesDocs &&
         (utils.hasATag(['augments', 'extends']) ||
           utils.classHasTag('augments') ||
             utils.classHasTag('extends'))) {
       return true;
     }
 
-    const exemptedBy = _.get(context, 'options[0].exemptedBy');
-    if (exemptedBy && exemptedBy.length && utils.getPresentTags(exemptedBy).length) {
+    const exemptedBy = _.get(context, 'options[0].exemptedBy', ['inheritdoc']);
+    if (exemptedBy.length && utils.getPresentTags(exemptedBy).length) {
       return true;
     }
 

test/rules/assertions/requireParam.js

@@ -520,6 +520,27 @@ export default {
         },
       ],
     },
+    {
+      code: `
+          /**
+           * @inheritdoc
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @param "foo" declaration.',
+        },
+      ],
+      options: [
+        {
+          exemptedBy: [],
+        },
+      ],
+    },
     {
       code: `
           /**