feat(check-tag-names, require-template, check-template-names): make typeParam a non-preferred alias for template

Author: brettz9

docs/rules/check-tag-names.md

@@ -1157,5 +1157,10 @@ interface WebTwain {
  * @param {AnotherType} anotherName And yet {@another}
  */
 // "jsdoc/check-tag-names": ["error"|"warn", {"inlineTags":["inline","another","inlineTag","link"]}]
+
+/**
+ * @typeParam T
+ */
+// Settings: {"jsdoc":{"tagNamePreference":{"template":"typeParam"}}}
 ````
 

docs/rules/check-template-names.md

@@ -214,6 +214,12 @@ export default class <NumType> {
  * @param {[X, Y | undefined]} someParam
  */
 // Message: @template D not in use
+
+/**
+ * @template
+ */
+// Settings: {"jsdoc":{"tagNamePreference":{"template":false}}}
+// Message: Unexpected tag `@template`
 ````
 
 

docs/rules/require-template.md

@@ -236,6 +236,12 @@ function foo<T>(bar: T, baz: number | boolean): T {
   return bar;
 }
 // Message: Missing @template T
+
+/**
+ * @template
+ */
+// Settings: {"jsdoc":{"tagNamePreference":{"template":false}}}
+// Message: Unexpected tag `@template`
 ````
 
 
@@ -399,5 +405,18 @@ type Pairs<D, V> = [D, V | undefined];
  * @typedef {[D, V | undefined]} Pairs
  */
 // "jsdoc/require-template": ["error"|"warn", {"exemptedBy":["inheritdoc"]}]
+
+/**
+ * Test interface for type definitions.
+ *
+ * @typeParam Foo - dummy type param
+ */
+export interface Test<Foo extends string> {
+  /**
+   *
+   */
+  bar: Foo;
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"template":"typeParam"}}}
 ````
 

src/rules/checkTemplateNames.js

@@ -23,7 +23,14 @@ export default iterateJsdoc(({
     mode,
   } = settings;
 
-  const templateTags = utils.getTags('template');
+  const tgName = /** @type {string} */ (utils.getPreferredTagName({
+    tagName: 'template',
+  }));
+  if (!tgName) {
+    return;
+  }
+
+  const templateTags = utils.getTags(tgName);
 
   const usedNames = new Set();
   /**
@@ -73,7 +80,7 @@ export default iterateJsdoc(({
       const names = utils.parseClosureTemplateTag(tag);
       for (const nme of names) {
         if (!usedNames.has(nme)) {
-          report(`@template ${nme} not in use`, null, tag);
+          report(`@${tgName} ${nme} not in use`, null, tag);
         }
       }
     }

src/rules/requireTemplate.js

@@ -25,7 +25,16 @@ export default iterateJsdoc(({
   } = settings;
 
   const usedNames = new Set();
-  const templateTags = utils.getTags('template');
+
+  const tgName = /** @type {string} */ (utils.getPreferredTagName({
+    tagName: 'template',
+  }));
+  if (!tgName) {
+    return;
+  }
+
+  const templateTags = utils.getTags(tgName);
+
   const templateNames = templateTags.flatMap((tag) => {
     return utils.parseClosureTemplateTag(tag);
   });
@@ -34,7 +43,7 @@ export default iterateJsdoc(({
     for (const tag of templateTags) {
       const names = utils.parseClosureTemplateTag(tag);
       if (names.length > 1) {
-        report(`Missing separate @template for ${names[1]}`, null, tag);
+        report(`Missing separate @${tgName} for ${names[1]}`, null, tag);
       }
     }
   }
@@ -64,7 +73,7 @@ export default iterateJsdoc(({
 
     for (const usedName of usedNames) {
       if (!templateNames.includes(usedName)) {
-        report(`Missing @template ${usedName}`);
+        report(`Missing @${tgName} ${usedName}`);
       }
     }
   };
@@ -156,7 +165,7 @@ export default iterateJsdoc(({
     // Could check against whitelist/blacklist
     for (const usedName of usedNames) {
       if (!templateNames.includes(usedName)) {
-        report(`Missing @template ${usedName}`, null, usedNameToTag.get(usedName));
+        report(`Missing @${tgName} ${usedName}`, null, usedNameToTag.get(usedName));
       }
     }
   };

src/tagNames.js

@@ -150,8 +150,11 @@ const typeScriptTags = {
   satisfies: [],
 
   // `@template` is also in TypeScript per:
-  //      https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc
-  template: [],
+  //      https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template
+  template: [
+    // Alias as per https://typedoc.org/documents/Tags._typeParam.html
+    'typeParam',
+  ],
 };
 
 /**

test/rules/assertions/checkTagNames.js

@@ -1499,5 +1499,19 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    {
+      code: `
+        /**
+         * @typeParam T
+         */
+      `,
+      settings: {
+        jsdoc: {
+          tagNamePreference: {
+            template: 'typeParam',
+          },
+        },
+      },
+    },
   ],
 });

test/rules/assertions/checkTemplateNames.js

@@ -464,6 +464,26 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    {
+      code: `
+        /**
+         * @template
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Unexpected tag `@template`',
+        },
+      ],
+      settings: {
+        jsdoc: {
+          tagNamePreference: {
+            template: false,
+          },
+        },
+      },
+    },
   ],
   valid: [
     {

test/rules/assertions/requireTemplate.js

@@ -426,6 +426,26 @@ export default /** @type {import('../index.js').TestCases} */ ({
         parser: typescriptEslintParser,
       },
     },
+    {
+      code: `
+        /**
+         * @template
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Unexpected tag `@template`',
+        },
+      ],
+      settings: {
+        jsdoc: {
+          tagNamePreference: {
+            template: false,
+          },
+        },
+      },
+    },
   ],
   valid: [
     {
@@ -701,5 +721,30 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    {
+      code: `
+        /**
+         * Test interface for type definitions.
+         *
+         * @typeParam Foo - dummy type param
+         */
+        export interface Test<Foo extends string> {
+          /**
+           *
+           */
+          bar: Foo;
+        }
+      `,
+      languageOptions: {
+        parser: typescriptEslintParser,
+      },
+      settings: {
+        jsdoc: {
+          tagNamePreference: {
+            template: 'typeParam',
+          },
+        },
+      },
+    },
   ],
 });