fix(require-tags): change rule name to be consistent with other rules (#1535)

BREAKING CHANGE:

Changes `required-tags` to `require-tags`.

Author: brettz9

.README/rules/required-tags.md renamed to .README/rules/require-tags.md

@@ -1,4 +1,4 @@
-# `required-tags`
+# `require-tags`
 
 Requires tags be present, optionally for specific contexts.
 
@@ -16,8 +16,8 @@ Requires tags be present, optionally for specific contexts.
 
 ## Failing examples
 
-<!-- assertions-failing requiredTags -->
+<!-- assertions-failing requireTags -->
 
 ## Passing examples
 
-<!-- assertions-passing requiredTags -->
+<!-- assertions-passing requireTags -->

README.md

@@ -479,6 +479,7 @@ non-default-recommended fixer).
 |:heavy_check_mark:|| [require-returns-check](./docs/rules/require-returns-check.md#readme) | Requires a return statement in function body if a `@returns` tag is specified in JSDoc comment(and reports if multiple `@returns` tags are present). |
 |:heavy_check_mark:|| [require-returns-description](./docs/rules/require-returns-description.md#readme) | Requires that the `@returns` tag has a `description` value (not including `void`/`undefined` type returns). |
 |:heavy_check_mark: (Off in TS; On in TS flavor)|| [require-returns-type](./docs/rules/require-returns-type.md#readme) | Requires that `@returns` tag has type value (in curly brackets). |
+||| [require-tags](./docs/rules/require-tags.md#readme) | Requires tags be present, optionally for specific contexts |
 ||| [require-template](./docs/rules/require-template.md#readme) | Requires `@template` tags be present when type parameters are used. |
 ||| [require-throws](./docs/rules/require-throws.md#readme) | Requires that throw statements are documented with `@throws` tags. |
 ||| [require-throws-description](./docs/rules/require-throws-description.md#readme) | Requires a description for `@throws` tags |
@@ -487,7 +488,6 @@ non-default-recommended fixer).
 |:heavy_check_mark:|| [require-yields-check](./docs/rules/require-yields-check.md#readme) | Ensures that if a `@yields` is present that a `yield` (or `yield` with a value) is present in the function body (or that if a `@next` is present that there is a yield with a return value present). |
 ||| [require-yields-description](./docs/rules/require-yields-description.md#readme) | Requires a description for `@yields` tags |
 |:heavy_check_mark:|| [require-yields-type](./docs/rules/require-yields-type.md#readme) | Requires a type for `@yields` tags |
-||| [required-tags](./docs/rules/required-tags.md#readme) | Requires tags be present, optionally for specific contexts |
 ||:wrench:| [sort-tags](./docs/rules/sort-tags.md#readme) | Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. |
 |:heavy_check_mark:|:wrench:| [tag-lines](./docs/rules/tag-lines.md#readme) | Enforces lines (or no lines) between tags. |
 ||:wrench:| [text-escaping](./docs/rules/text-escaping.md#readme) | Auto-escape certain characters that are input within block and tag descriptions. |

docs/rules/require-tags.md

@@ -0,0 +1,85 @@
+<a name="user-content-require-tags"></a>
+<a name="require-tags"></a>
+# <code>require-tags</code>
+
+Requires tags be present, optionally for specific contexts.
+
+<a name="user-content-require-tags-options"></a>
+<a name="require-tags-options"></a>
+## Options
+
+A single options object has the following properties.
+
+<a name="user-content-require-tags-options-tags"></a>
+<a name="require-tags-options-tags"></a>
+### <code>tags</code>
+
+May be an array of either strings or objects with
+a string `tag` property and `context` string property.
+
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|(Any)|
+|Recommended|false|
+|Settings||
+|Options|`tags`|
+
+<a name="user-content-require-tags-failing-examples"></a>
+<a name="require-tags-failing-examples"></a>
+## Failing examples
+
+The following patterns are considered problems:
+
+````ts
+/**
+ *
+ */
+function quux () {}
+// "jsdoc/require-tags": ["error"|"warn", {"tags":["see"]}]
+// Message: Missing required tag "see"
+
+/**
+ *
+ */
+function quux () {}
+// "jsdoc/require-tags": ["error"|"warn", {"tags":[{"context":"FunctionDeclaration","tag":"see"}]}]
+// Message: Missing required tag "see"
+
+/**
+ * @type {SomeType}
+ */
+function quux () {}
+// "jsdoc/require-tags": ["error"|"warn", {"tags":[{"context":"FunctionDeclaration","tag":"see"}]}]
+// Message: Missing required tag "see"
+
+/**
+ * @type {SomeType}
+ */
+function quux () {}
+// Message: Rule `require-tags` is missing a `tags` option.
+````
+
+
+
+<a name="user-content-require-tags-passing-examples"></a>
+<a name="require-tags-passing-examples"></a>
+## Passing examples
+
+The following patterns are not considered problems:
+
+````ts
+/**
+ * @see
+ */
+function quux () {}
+// "jsdoc/require-tags": ["error"|"warn", {"tags":["see"]}]
+
+/**
+ *
+ */
+class Quux {}
+// "jsdoc/require-tags": ["error"|"warn", {"tags":[{"context":"FunctionDeclaration","tag":"see"}]}]
+````
+

src/index-cjs.js

@@ -40,7 +40,6 @@ import noUndefinedTypes from './rules/noUndefinedTypes.js';
 import requireAsteriskPrefix from './rules/requireAsteriskPrefix.js';
 import requireDescription from './rules/requireDescription.js';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence.js';
-import requiredTags from './rules/requiredTags.js';
 import requireExample from './rules/requireExample.js';
 import requireFileOverview from './rules/requireFileOverview.js';
 import requireHyphenBeforeParamDescription from './rules/requireHyphenBeforeParamDescription.js';
@@ -57,6 +56,7 @@ import requireReturns from './rules/requireReturns.js';
 import requireReturnsCheck from './rules/requireReturnsCheck.js';
 import requireReturnsDescription from './rules/requireReturnsDescription.js';
 import requireReturnsType from './rules/requireReturnsType.js';
+import requireTags from './rules/requireTags.js';
 import requireTemplate from './rules/requireTemplate.js';
 import requireThrows from './rules/requireThrows.js';
 import requireYields from './rules/requireYields.js';
@@ -179,6 +179,7 @@ index.rules = {
   'require-returns-check': requireReturnsCheck,
   'require-returns-description': requireReturnsDescription,
   'require-returns-type': requireReturnsType,
+  'require-tags': requireTags,
   'require-template': requireTemplate,
   'require-throws': requireThrows,
   'require-throws-description': buildForbidRuleDefinition({
@@ -227,7 +228,6 @@ index.rules = {
     description: 'Requires a type for `@yields` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-type.md#repos-sticky-header',
   }),
-  'required-tags': requiredTags,
   'sort-tags': sortTags,
   'tag-lines': tagLines,
   'text-escaping': textEscaping,
@@ -306,6 +306,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-returns-check': warnOrError,
       'jsdoc/require-returns-description': warnOrError,
       'jsdoc/require-returns-type': warnOrError,
+      'jsdoc/require-tags': 'off',
       'jsdoc/require-template': 'off',
       'jsdoc/require-throws': 'off',
       'jsdoc/require-throws-description': 'off',
@@ -314,7 +315,6 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-yields-check': warnOrError,
       'jsdoc/require-yields-description': 'off',
       'jsdoc/require-yields-type': warnOrError,
-      'jsdoc/required-tags': 'off',
       'jsdoc/sort-tags': 'off',
       'jsdoc/tag-lines': warnOrError,
       'jsdoc/text-escaping': 'off',

src/index.js

@@ -46,7 +46,6 @@ import noUndefinedTypes from './rules/noUndefinedTypes.js';
 import requireAsteriskPrefix from './rules/requireAsteriskPrefix.js';
 import requireDescription from './rules/requireDescription.js';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence.js';
-import requiredTags from './rules/requiredTags.js';
 import requireExample from './rules/requireExample.js';
 import requireFileOverview from './rules/requireFileOverview.js';
 import requireHyphenBeforeParamDescription from './rules/requireHyphenBeforeParamDescription.js';
@@ -63,6 +62,7 @@ import requireReturns from './rules/requireReturns.js';
 import requireReturnsCheck from './rules/requireReturnsCheck.js';
 import requireReturnsDescription from './rules/requireReturnsDescription.js';
 import requireReturnsType from './rules/requireReturnsType.js';
+import requireTags from './rules/requireTags.js';
 import requireTemplate from './rules/requireTemplate.js';
 import requireThrows from './rules/requireThrows.js';
 import requireYields from './rules/requireYields.js';
@@ -185,6 +185,7 @@ index.rules = {
   'require-returns-check': requireReturnsCheck,
   'require-returns-description': requireReturnsDescription,
   'require-returns-type': requireReturnsType,
+  'require-tags': requireTags,
   'require-template': requireTemplate,
   'require-throws': requireThrows,
   'require-throws-description': buildForbidRuleDefinition({
@@ -233,7 +234,6 @@ index.rules = {
     description: 'Requires a type for `@yields` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-type.md#repos-sticky-header',
   }),
-  'required-tags': requiredTags,
   'sort-tags': sortTags,
   'tag-lines': tagLines,
   'text-escaping': textEscaping,
@@ -312,6 +312,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-returns-check': warnOrError,
       'jsdoc/require-returns-description': warnOrError,
       'jsdoc/require-returns-type': warnOrError,
+      'jsdoc/require-tags': 'off',
       'jsdoc/require-template': 'off',
       'jsdoc/require-throws': 'off',
       'jsdoc/require-throws-description': 'off',
@@ -320,7 +321,6 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-yields-check': warnOrError,
       'jsdoc/require-yields-description': 'off',
       'jsdoc/require-yields-type': warnOrError,
-      'jsdoc/required-tags': 'off',
       'jsdoc/sort-tags': 'off',
       'jsdoc/tag-lines': warnOrError,
       'jsdoc/text-escaping': 'off',

src/rules.d.ts

@@ -2370,6 +2370,26 @@ export interface Rules {
         }
       ];
 
+  /** Requires tags be present, optionally for specific contexts */
+  "jsdoc/require-tags": 
+    | []
+    | [
+        {
+          /**
+           * May be an array of either strings or objects with
+           * a string `tag` property and `context` string property.
+           */
+          tags?: (
+            | string
+            | {
+                context?: string;
+                tag?: string;
+                [k: string]: unknown;
+              }
+          )[];
+        }
+      ];
+
   /** Requires `@template` tags be present when type parameters are used. */
   "jsdoc/require-template": 
     | []
@@ -2580,26 +2600,6 @@ export interface Rules {
   /** Requires a type for `@yields` tags */
   "jsdoc/require-yields-type": [];
 
-  /** Requires tags be present, optionally for specific contexts */
-  "jsdoc/required-tags": 
-    | []
-    | [
-        {
-          /**
-           * May be an array of either strings or objects with
-           * a string `tag` property and `context` string property.
-           */
-          tags?: (
-            | string
-            | {
-                context?: string;
-                tag?: string;
-                [k: string]: unknown;
-              }
-          )[];
-        }
-      ];
-
   /** Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. */
   "jsdoc/sort-tags": 
     | []

src/rules/requiredTags.js renamed to src/rules/requireTags.js

@@ -7,7 +7,7 @@ export default buildForbidRuleDefinition({
   getContexts (context, report) {
     // Transformed options to this option in `modifyContext`:
     if (!context.options[0].contexts) {
-      report('Rule `required-tags` is missing a `tags` option.');
+      report('Rule `require-tags` is missing a `tags` option.');
       return false;
     }
 
@@ -81,5 +81,5 @@ a string \`tag\` property and \`context\` string property.`,
       type: 'object',
     },
   ],
-  url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/required-tags.md#repos-sticky-header',
+  url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-tags.md#repos-sticky-header',
 });

test/rules/assertions/requiredTags.js renamed to test/rules/assertions/requireTags.js

@@ -79,7 +79,7 @@ export default {
       errors: [
         {
           line: 2,
-          message: 'Rule `required-tags` is missing a `tags` option.',
+          message: 'Rule `require-tags` is missing a `tags` option.',
         },
       ],
     },

test/rules/ruleNames.json

@@ -60,7 +60,7 @@
   "require-yields-check",
   "require-yields-description",
   "require-yields-type",
-  "required-tags",
+  "require-tags",
   "sort-tags",
   "tag-lines",
   "text-escaping",