feat: add ignoreInternal setting to ignore blocks with @internal …

…tags; fixes gajus#639

Not applied to `empty-tags` rule

.README/README.md

@@ -113,12 +113,16 @@ supplied as the second argument in an array after the error level.
 
 ## Settings
 
-### Allow `@private` to disable rules for that comment block
+### Allow tags (`@private` or `@internal`) to disable rules for that comment block
 
 - `settings.jsdoc.ignorePrivate` - Disables all rules for the comment block
   on which a `@private` tag (or `@access private`) occurs. Defaults to
   `false`. Note: This has no effect with the rule `check-access` (whose
-  purpose is to check access modifiers).
+  purpose is to check access modifiers) or `empty-tags` (which checks
+  `@private` itself).
+- `settings.jsdoc.ignoreInternal` - Disables all rules for the comment block
+  on which a `@internal` tag occurs. Defaults to `false`. Note: This has no
+  effect with the rule `empty-tags` (which checks `@internal` itself).
 
 ### `maxLines` and `minLines`
 

.README/rules/empty-tags.md

@@ -27,6 +27,9 @@ Note that `@private` will still be checked for content by this rule even with
 `settings.jsdoc.ignorePrivate` set to `true` (a setting which normally
 causes rules not to take effect).
 
+Similarly, `@internal` will still be checked for content by this rule even with
+`settings.jsdoc.ignoreInternal` set to `true`.
+
 #### Options
 
 ##### `tags`

README.md

@@ -14,7 +14,7 @@ JSDoc linting rules for ESLint.
     * [Configuration](#eslint-plugin-jsdoc-configuration)
     * [Options](#eslint-plugin-jsdoc-options)
     * [Settings](#eslint-plugin-jsdoc-settings)
-        * [Allow `@private` to disable rules for that comment block](#eslint-plugin-jsdoc-settings-allow-private-to-disable-rules-for-that-comment-block)
+        * [Allow tags (`@private` or `@internal`) to disable rules for that comment block](#eslint-plugin-jsdoc-settings-allow-tags-private-or-internal-to-disable-rules-for-that-comment-block)
         * [`maxLines` and `minLines`](#eslint-plugin-jsdoc-settings-maxlines-and-minlines)
         * [Mode](#eslint-plugin-jsdoc-settings-mode)
         * [Alias Preference](#eslint-plugin-jsdoc-settings-alias-preference)
@@ -172,13 +172,17 @@ supplied as the second argument in an array after the error level.
 <a name="eslint-plugin-jsdoc-settings"></a>
 ## Settings
 
-<a name="eslint-plugin-jsdoc-settings-allow-private-to-disable-rules-for-that-comment-block"></a>
-### Allow <code>@private</code> to disable rules for that comment block
+<a name="eslint-plugin-jsdoc-settings-allow-tags-private-or-internal-to-disable-rules-for-that-comment-block"></a>
+### Allow tags (<code>@private</code> or <code>@internal</code>) to disable rules for that comment block
 
 - `settings.jsdoc.ignorePrivate` - Disables all rules for the comment block
   on which a `@private` tag (or `@access private`) occurs. Defaults to
   `false`. Note: This has no effect with the rule `check-access` (whose
-  purpose is to check access modifiers).
+  purpose is to check access modifiers) or `empty-tags` (which checks
+  `@private` itself).
+- `settings.jsdoc.ignoreInternal` - Disables all rules for the comment block
+  on which a `@internal` tag occurs. Defaults to `false`. Note: This has no
+  effect with the rule `empty-tags` (which checks `@internal` itself).
 
 <a name="eslint-plugin-jsdoc-settings-maxlines-and-minlines"></a>
 ### <code>maxLines</code> and <code>minLines</code>
@@ -5102,6 +5106,9 @@ Note that `@private` will still be checked for content by this rule even with
 `settings.jsdoc.ignorePrivate` set to `true` (a setting which normally
 causes rules not to take effect).
 
+Similarly, `@internal` will still be checked for content by this rule even with
+`settings.jsdoc.ignoreInternal` set to `true`.
+
 <a name="eslint-plugin-jsdoc-rules-empty-tags-options-9"></a>
 #### Options
 
@@ -5171,6 +5178,14 @@ function quux () {
 }
 // Message: @private should be empty.
 
+/**
+ * @internal {someType}
+ */
+function quux () {
+
+}
+// Message: @internal should be empty.
+
 /**
  * @private {someType}
  */
@@ -5227,6 +5242,13 @@ function quux () {
  */
 function quux () {
 
+}
+
+/**
+ * @internal
+ */
+function quux () {
+
 }
 ````
 
@@ -12340,6 +12362,14 @@ class A {
 }
 // Settings: {"jsdoc":{"augmentsExtendsReplacesDocs":true}}
 
+/**
+ * @internal
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"ignoreInternal":true}}
+
 /**
  * @private
  */

src/iterateJsdoc.js

@@ -441,6 +441,7 @@ const getSettings = (context) => {
   const settings = {
     // All rules
     ignorePrivate: Boolean(context.settings.jsdoc?.ignorePrivate),
+    ignoreInternal: Boolean(context.settings.jsdoc?.ignoreInternal),
     maxLines: Number(context.settings.jsdoc?.maxLines ?? 1),
     minLines: Number(context.settings.jsdoc?.minLines ?? 0),
 
@@ -560,8 +561,13 @@ const iterate = (
   );
 
   if (
-    settings.ignorePrivate &&
-    !ruleConfig.checkPrivate &&
+    !ruleConfig.checkInternal && settings.ignoreInternal &&
+    utils.hasTag('internal')
+  ) {
+    return;
+  }
+  if (
+    !ruleConfig.checkPrivate && settings.ignorePrivate &&
     (utils.hasTag('private') || _.filter(jsdoc.tags, {
       tag: 'access',
     }).some(({description}) => {

src/rules/emptyTags.js

@@ -7,6 +7,9 @@ const defaultEmptyTags = new Set([
   // jsdoc doesn't use this form in its docs, but allow for compatibility with
   //  TypeScript which allows and Closure which requires
   'inheritDoc',
+
+  // jsdoc doesn't use but allow for TypeScript
+  'internal',
 ]);
 
 const emptyIfNotClosure = new Set([
@@ -45,6 +48,7 @@ export default iterateJsdoc(({
     }
   });
 }, {
+  checkInternal: true,
   checkPrivate: true,
   iterateAllJsdocs: true,
   meta: {

test/rules/assertions/emptyTags.js

@@ -137,6 +137,30 @@ export default {
       }
       `,
     },
+    {
+      code: `
+      /**
+       * @internal {someType}
+       */
+      function quux () {
+
+      }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: '@internal should be empty.',
+        },
+      ],
+      output: `
+      /**
+       * @internal
+       */
+      function quux () {
+
+      }
+      `,
+    },
     {
       code: `
       /**
@@ -232,6 +256,16 @@ export default {
        */
       function quux () {
 
+      }
+      `,
+    },
+    {
+      code: `
+      /**
+       * @internal
+       */
+      function quux () {
+
       }
       `,
     },

test/rules/assertions/requireParam.js

@@ -2593,6 +2593,21 @@ export default {
         },
       },
     },
+    {
+      code: `
+          /**
+           * @internal
+           */
+          function quux (foo) {
+
+          }
+      `,
+      settings: {
+        jsdoc: {
+          ignoreInternal: true,
+        },
+      },
+    },
     {
       code: `
           /**