feat(require-template-description): add rule; fixes #1540

Author: brettz9

.README/rules/require-template-description.md

@@ -0,0 +1,21 @@
+# `require-template-description`
+
+## Options
+
+{"gitdown": "options"}
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|`template`|
+|Recommended|false|
+|Settings||
+|Options||
+
+## Failing examples
+
+<!-- assertions-failing requireTemplateDescription -->
+
+## Passing examples
+
+<!-- assertions-passing requireTemplateDescription -->

README.md

@@ -483,6 +483,7 @@ non-default-recommended fixer).
 |: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-template-description](./docs/rules/require-template-description.md#readme) | Requires a description for `@template` tags |
 ||| [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 |
 |:heavy_check_mark:|| [require-throws-type](./docs/rules/require-throws-type.md#readme) | Requires a type for `@throws` tags |

docs/rules/require-template-description.md

@@ -0,0 +1,49 @@
+<a name="user-content-require-template-description"></a>
+<a name="require-template-description"></a>
+# <code>require-template-description</code>
+
+<a name="user-content-require-template-description-options"></a>
+<a name="require-template-description-options"></a>
+## Options
+
+
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|`template`|
+|Recommended|false|
+|Settings||
+|Options||
+
+<a name="user-content-require-template-description-failing-examples"></a>
+<a name="require-template-description-failing-examples"></a>
+## Failing examples
+
+The following patterns are considered problems:
+
+````ts
+/**
+ * @template {SomeType}
+ */
+// Message: @template should have a description
+````
+
+
+
+<a name="user-content-require-template-description-passing-examples"></a>
+<a name="require-template-description-passing-examples"></a>
+## Passing examples
+
+The following patterns are not considered problems:
+
+````ts
+/**
+ * @template {SomeType} Has a description
+ */
+
+/**
+ * @template Has a description
+ */
+````
+

src/index-cjs.js

@@ -188,6 +188,17 @@ index.rules = {
   'require-returns-type': requireReturnsType,
   'require-tags': requireTags,
   'require-template': requireTemplate,
+  'require-template-description': buildForbidRuleDefinition({
+    contexts: [
+      {
+        comment: 'JsdocBlock:has(JsdocTag[tag=template]:not([description!=""]))',
+        context: 'any',
+        message: '@template should have a description',
+      },
+    ],
+    description: 'Requires a description for `@template` tags',
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-template-description.md#repos-sticky-header',
+  }),
   'require-throws': requireThrows,
   'require-throws-description': buildForbidRuleDefinition({
     contexts: [
@@ -316,6 +327,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-returns-type': warnOrError,
       'jsdoc/require-tags': 'off',
       'jsdoc/require-template': 'off',
+      'jsdoc/require-template-description': 'off',
       'jsdoc/require-throws': 'off',
       'jsdoc/require-throws-description': 'off',
       'jsdoc/require-throws-type': warnOrError,

src/index.js

@@ -194,6 +194,17 @@ index.rules = {
   'require-returns-type': requireReturnsType,
   'require-tags': requireTags,
   'require-template': requireTemplate,
+  'require-template-description': buildForbidRuleDefinition({
+    contexts: [
+      {
+        comment: 'JsdocBlock:has(JsdocTag[tag=template]:not([description!=""]))',
+        context: 'any',
+        message: '@template should have a description',
+      },
+    ],
+    description: 'Requires a description for `@template` tags',
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-template-description.md#repos-sticky-header',
+  }),
   'require-throws': requireThrows,
   'require-throws-description': buildForbidRuleDefinition({
     contexts: [
@@ -322,6 +333,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-returns-type': warnOrError,
       'jsdoc/require-tags': 'off',
       'jsdoc/require-template': 'off',
+      'jsdoc/require-template-description': 'off',
       'jsdoc/require-throws': 'off',
       'jsdoc/require-throws-description': 'off',
       'jsdoc/require-throws-type': warnOrError,

src/rules.d.ts

@@ -2444,6 +2444,9 @@ export interface Rules {
         }
       ];
 
+  /** Requires a description for `@template` tags */
+  "jsdoc/require-template-description": [];
+
   /** Requires that throw statements are documented with `@throws` tags. */
   "jsdoc/require-throws": 
     | []

test/rules/assertions/requireTemplateDescription.js

@@ -0,0 +1,33 @@
+export default /** @type {import('../index.js').TestCases} */ ({
+  invalid: [
+    {
+      code: `
+        /**
+         * @template {SomeType}
+         */
+      `,
+      errors: [
+        {
+          line: 2,
+          message: '@template should have a description',
+        },
+      ],
+    },
+  ],
+  valid: [
+    {
+      code: `
+        /**
+         * @template {SomeType} Has a description
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * @template Has a description
+         */
+      `,
+    },
+  ],
+});

test/rules/ruleNames.json

@@ -53,15 +53,16 @@
   "require-returns-check",
   "require-returns-description",
   "require-returns-type",
+  "require-tags",
   "require-template",
+  "require-template-description",
   "require-throws",
   "require-throws-description",
   "require-throws-type",
   "require-yields",
   "require-yields-check",
   "require-yields-description",
   "require-yields-type",
-  "require-tags",
   "sort-tags",
   "tag-lines",
   "text-escaping",