eslint-plugin-jsdoc 60.4.0 → 60.5.0

package/package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.61.0",
+    "@es-joy/jsdoccomment": "~0.62.0",
     "are-docs-informative": "^0.0.2",
     "comment-parser": "1.4.1",
     "debug": "^4.4.3",
@@ -27,8 +27,8 @@
     "@babel/plugin-syntax-class-properties": "^7.12.13",
     "@babel/plugin-transform-flow-strip-types": "^7.27.1",
     "@babel/preset-env": "^7.28.3",
-    "@es-joy/escodegen": "^3.5.1",
-    "@es-joy/jsdoc-eslint-parser": "^0.23.0",
+    "@es-joy/escodegen": "^4.0.3",
+    "@es-joy/jsdoc-eslint-parser": "^0.24.0",
     "@eslint/core": "^0.16.0",
     "@hkdobrev/run-if-changed": "^0.6.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
@@ -50,7 +50,7 @@
     "babel-plugin-transform-import-meta": "^2.3.3",
     "c8": "^10.1.3",
     "camelcase": "^8.0.0",
-    "chai": "^6.0.1",
+    "chai": "^6.2.0",
     "decamelize": "^6.0.1",
     "eslint": "9.36.0",
     "eslint-config-canonical": "^45.0.0",
@@ -58,7 +58,7 @@
     "glob": "^11.0.3",
     "globals": "^16.4.0",
     "husky": "^9.1.7",
-    "jsdoc-type-pratt-parser": "^5.8.0",
+    "jsdoc-type-pratt-parser": "^5.9.2",
     "json-schema": "^0.4.0",
     "json-schema-to-typescript": "^15.0.4",
     "lint-staged": "^16.2.1",
@@ -178,5 +178,5 @@
     "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
     "test-index": "pnpm run test-no-cov test/rules/index.js"
   },
-  "version": "60.4.0"
+  "version": "60.5.0"
 }

package/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,

package/src/index-esm.js

@@ -16,7 +16,6 @@ import {
 export default index;
 // END REPLACE
 
-/* eslint-disable jsdoc/valid-types -- Bug */
 /**
  * @type {((
  *   cfg?: import('eslint').Linter.Config & {
@@ -54,7 +53,6 @@ export default index;
  * ) => import('eslint').Linter.Config)}
  */
 export const jsdoc = function (cfg) {
-  /* eslint-enable jsdoc/valid-types -- Bug */
   /** @type {import('eslint').Linter.Config} */
   let outputConfig = {
     plugins: {

package/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,
@@ -694,7 +706,6 @@ index.configs['flat/recommended-mixed'] = [
 
 export default index;
 
-/* eslint-disable jsdoc/valid-types -- Bug */
 /**
  * @type {((
  *   cfg?: import('eslint').Linter.Config & {
@@ -732,7 +743,6 @@ export default index;
  * ) => import('eslint').Linter.Config)}
  */
 export const jsdoc = function (cfg) {
-  /* eslint-enable jsdoc/valid-types -- Bug */
   /** @type {import('eslint').Linter.Config} */
   let outputConfig = {
     plugins: {

package/src/iterateJsdoc.js

@@ -436,6 +436,14 @@ import esquery from 'esquery';
  *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
  */
 
+/**
+ * @callback getInlineTags
+ * @returns {(import('comment-parser').Spec|
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
+ *     line?: number | undefined; column?: number | undefined;
+ *   })[]}
+ */
+
 /**
  * @callback GetTagsByType
  * @param {import('comment-parser').Spec[]} tags
@@ -533,6 +541,7 @@ import esquery from 'esquery';
  *   getPresentTags: GetPresentTags,
  *   filterTags: FilterTags,
  *   filterAllTags: FilterAllTags,
+ *   getInlineTags: getInlineTags,
  *   getTagsByType: GetTagsByType,
  *   hasOptionTag: HasOptionTag,
  *   getClassNode: GetClassNode,
@@ -1641,6 +1650,10 @@ const getUtils = (
     });
   };
 
+  utils.getInlineTags = () => {
+    return jsdocUtils.getInlineTags(jsdoc);
+  };
+
   /** @type {GetTagsByType} */
   utils.getTagsByType = (tags) => {
     return jsdocUtils.getTagsByType(context, mode, tags);

package/src/jsdocUtils.js

@@ -836,14 +836,15 @@ const forEachPreferredTag = (
 };
 
 /**
- * Get all tags, inline tags and inline tags in tags
+ * Get all inline tags and inline tags in tags
  * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @returns {(import('comment-parser').Spec|
- *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
+ *     line?: number | undefined; column?: number | undefined;
+ *   })[]}
  */
-const getAllTags = (jsdoc) => {
+const getInlineTags = (jsdoc) => {
   return [
-    ...jsdoc.tags,
     ...jsdoc.inlineTags.map((inlineTag) => {
       // Tags don't have source or line numbers, so add before returning
       let line = -1;
@@ -863,18 +864,6 @@ const getAllTags = (jsdoc) => {
       return inlineTag;
     }),
     ...jsdoc.tags.flatMap((tag) => {
-      let tagBegins = -1;
-      for (const {
-        tokens: {
-          tag: tg,
-        },
-      } of jsdoc.source) {
-        tagBegins++;
-        if (tg) {
-          break;
-        }
-      }
-
       for (const inlineTag of tag.inlineTags) {
         /** @type {import('./iterateJsdoc.js').Integer} */
         let line = 0;
@@ -890,7 +879,7 @@ const getAllTags = (jsdoc) => {
           }
         }
 
-        inlineTag.line = tagBegins + line - 1;
+        inlineTag.line = line;
       }
 
       return (
@@ -906,6 +895,21 @@ const getAllTags = (jsdoc) => {
   ];
 };
 
+/**
+ * Get all tags, inline tags and inline tags in tags
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+ * @returns {(import('comment-parser').Spec|
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
+ *     line?: number | undefined; column?: number | undefined;
+ *   })[]}
+ */
+const getAllTags = (jsdoc) => {
+  return [
+    ...jsdoc.tags,
+    ...getInlineTags(jsdoc),
+  ];
+};
+
 /**
  * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @param {string[]} targetTagNames
@@ -1853,6 +1857,7 @@ export {
   getContextObject,
   getFunctionParameterNames,
   getIndent,
+  getInlineTags,
   getJsdocTagsDeep,
   getPreferredTagName,
   getPreferredTagNameSimple,

package/src/rules/checkTagNames.js

@@ -75,11 +75,15 @@ export default iterateJsdoc(({
      * @type {{
      *   definedTags: string[],
      *   enableFixer: boolean,
+     *   inlineTags: string[],
      *   jsxTags: boolean,
      *   typed: boolean
      }} */ {
       definedTags = [],
       enableFixer = true,
+      inlineTags = [
+        'link', 'linkcode', 'linkplain', 'tutorial',
+      ],
       jsxTags,
       typed,
     } = context.options[0] || {};
@@ -278,6 +282,12 @@ export default iterateJsdoc(({
       report(`Invalid JSDoc tag name "${tagName}".`, null, jsdocTag);
     }
   }
+
+  for (const inlineTag of utils.getInlineTags()) {
+    if (!inlineTags.includes(inlineTag.tag)) {
+      report(`Invalid JSDoc inline tag name "${inlineTag.tag}"`, null, inlineTag);
+    }
+  }
 }, {
   iterateAllJsdocs: true,
   meta: {
@@ -308,6 +318,15 @@ The format is as follows:
             description: 'Set to `false` to disable auto-removal of types that are redundant with the [`typed` option](#typed).',
             type: 'boolean',
           },
+          inlineTags: {
+            description: `List of tags to allow inline.
+
+Defaults to array of \`'link', 'linkcode', 'linkplain', 'tutorial'\``,
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
           jsxTags: {
             description: `If this is set to \`true\`, all of the following tags used to control JSX output are allowed:
 

package/src/rules/noUndefinedTypes.js

@@ -139,7 +139,13 @@ export default iterateJsdoc(({
       return doc.tags.filter(({
         tag,
       }) => {
-        return utils.isNamepathDefiningTag(tag);
+        return utils.isNamepathDefiningTag(tag) && ![
+          'arg',
+          'argument',
+          'param',
+          'prop',
+          'property',
+        ].includes(tag);
       });
     });
 

package/src/rules/requireParam.js

@@ -175,7 +175,10 @@ export default iterateJsdoc(({
    *   newAdd?: boolean
    * })[]} jsdocTags
    * @param {import('../iterateJsdoc.js').Integer} indexAtFunctionParams
-   * @returns {import('../iterateJsdoc.js').Integer}
+   * @returns {{
+   *   foundIndex: import('../iterateJsdoc.js').Integer,
+   *   tagLineCount: import('../iterateJsdoc.js').Integer,
+   * }}
    */
   const findExpectedIndex = (jsdocTags, indexAtFunctionParams) => {
     const remainingRoots = functionParameterNames.slice(indexAtFunctionParams || 0);
@@ -225,7 +228,10 @@ export default iterateJsdoc(({
       }
     }
 
-    return tagLineCount;
+    return {
+      foundIndex,
+      tagLineCount,
+    };
   };
 
   let [
@@ -486,8 +492,22 @@ export default iterateJsdoc(({
     if (remove) {
       createTokens(functionParameterIdx, offset + functionParameterIdx, 1);
     } else {
-      const expectedIdx = findExpectedIndex(jsdoc.tags, functionParameterIdx);
-      createTokens(expectedIdx, offset + expectedIdx, 0);
+      const {
+        foundIndex,
+        tagLineCount: expectedIdx,
+      } =
+        findExpectedIndex(jsdoc.tags, functionParameterIdx);
+
+      const firstParamLine = jsdoc.source.findIndex(({
+        tokens,
+      }) => {
+        return tokens.tag === `@${preferredTagName}`;
+      });
+      const baseOffset = foundIndex > -1 || firstParamLine === -1 ?
+        offset :
+        firstParamLine;
+
+      createTokens(expectedIdx, baseOffset + expectedIdx, 0);
     }
   };
 

package/src/rules.d.ts

@@ -261,6 +261,12 @@ export interface Rules {
            * Set to `false` to disable auto-removal of types that are redundant with the [`typed` option](#typed).
            */
           enableFixer?: boolean;
+          /**
+           * List of tags to allow inline.
+           *
+           * Defaults to array of `'link', 'linkcode', 'linkplain', 'tutorial'`
+           */
+          inlineTags?: string[];
           /**
            * If this is set to `true`, all of the following tags used to control JSX output are allowed:
            *
@@ -2444,6 +2450,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": 
     | []