eslint-plugin-jsdoc 60.4.1 → 60.6.0

package/dist/rules.d.ts

@@ -82,7 +82,6 @@ export interface Rules {
           /**
            * An object with any of the following spacing keys set to an integer.
            * If a spacing is not defined, it defaults to one.
-           *
            */
           customSpacings?: {
             /**
@@ -261,6 +260,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:
            *
@@ -431,7 +436,6 @@ export interface Rules {
            *
            * Defaults to `ArrowFunctionExpression`, `FunctionDeclaration`,
            * `FunctionExpression`, `TSDeclareFunction`.
-           *
            */
           contexts?: (
             | string
@@ -490,7 +494,6 @@ export interface Rules {
            * ```
            *
            * Defaults to `multi`.
-           *
            */
           enforceJsdocLineStyle?: "multi" | "single";
           /**
@@ -520,12 +523,36 @@ export interface Rules {
            *   'jsdoc/empty-tags': ['error', {tags: ['event']}]
            * }
            * ```
-           *
            */
           tags?: string[];
         }
       ];
 
+  /** Reports use of JSDoc tags in non-tag positions (in the default "typescript" mode). */
+  "jsdoc/escape-inline-tags": 
+    | []
+    | [
+        {
+          /**
+           * A listing of tags you wish to allow unescaped. Defaults to an empty array.
+           */
+          allowedInlineTags?: string[];
+          /**
+           * Whether to enable the fixer. Defaults to `false`.
+           */
+          enableFixer?: boolean;
+          /**
+           * How to escape the inline tag.
+           *
+           * May be "backticks" to enclose tags in backticks (treating as code segments), or
+           * "backslash" to escape tags with a backslash, i.e., `\@`
+           *
+           * Defaults to "backslash".
+           */
+          fixType?: "backticks" | "backslash";
+        }
+      ];
+
   /** Prohibits use of `@implements` on non-constructor functions (to enforce the tag only being used on classes/constructors). */
   "jsdoc/implements-on-classes": 
     | []
@@ -582,7 +609,6 @@ export interface Rules {
            *   "a": ["an", "our"]
            * }
            * ```
-           *
            */
           aliases?: {
             /**
@@ -604,7 +630,6 @@ export interface Rules {
            * ```
            *
            * No tags are excluded by default.
-           *
            */
           excludedTags?: string[];
           /**
@@ -622,7 +647,6 @@ export interface Rules {
            * ```json
            * ["a", "an", "i", "in", "of", "s", "the"]
            * ```
-           *
            */
           uselessWords?: string[];
         }
@@ -636,26 +660,22 @@ export interface Rules {
           /**
            * Whether to additionally check the start of blocks, such as classes or functions.
            * Defaults to `false`.
-           *
            */
           checkBlockStarts?: boolean;
           /**
            * An array of tags whose presence in the JSDoc block will prevent the
            * application of the rule. Defaults to `['type']` (i.e., if `@type` is present,
            * lines before the block will not be added).
-           *
            */
           excludedTags?: string[];
           /**
            * This option excludes cases where the JSDoc block occurs on the same line as a
            * preceding code or comment. Defaults to `true`.
-           *
            */
           ignoreSameLine?: boolean;
           /**
            * This option excludes cases where the JSDoc block is only one line long.
            * Defaults to `true`.
-           *
            */
           ignoreSingleLines?: boolean;
           /**
@@ -683,7 +703,6 @@ export interface Rules {
            *
            * See the ["AST and Selectors"](../#advanced-ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
-           *
            */
           contexts?: (
             | string
@@ -765,7 +784,6 @@ export interface Rules {
            *
            * This can be overridden per tag or for the main block description by setting
            * `message` within `tags` or `mainDescription`, respectively.
-           *
            */
           message?: string;
           /**
@@ -863,7 +881,6 @@ export interface Rules {
            * tag of the desired tag and/or name and no `disallowName` (or `allowName`) is
            * supplied. In such a case, only one error will be reported, but no fixer will
            * be applied, however.
-           *
            */
           match: {
             /**
@@ -952,7 +969,6 @@ export interface Rules {
            * lines.
            *
            * Defaults to `['*']`.
-           *
            */
           multilineTags?: "*" | string[];
           /**
@@ -977,7 +993,6 @@ export interface Rules {
            * are whitelisted in `singleLineTags`.
            *
            * Defaults to `false`.
-           *
            */
           noSingleLineBlocks?: boolean;
           /**
@@ -998,7 +1013,6 @@ export interface Rules {
            * descriptions.
            *
            * Defaults to `null`.
-           *
            */
           requireSingleLineUnderCount?: number;
           /**
@@ -1025,7 +1039,6 @@ export interface Rules {
            *
            * Defaults to `['ts-check', 'ts-expect-error', 'ts-ignore', 'ts-nocheck']`
            * (some directives [used by TypeScript](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#ts-check)).
-           *
            */
           ignore?: string[];
           /**
@@ -1233,7 +1246,6 @@ export interface Rules {
            *
            * See the ["AST and Selectors"](../#advanced-ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
-           *
            */
           contexts?: (
             | string
@@ -1326,7 +1338,6 @@ export interface Rules {
            *   }]
            * }
            * ```
-           *
            */
           tags?: {
             /**
@@ -1446,7 +1457,6 @@ export interface Rules {
            * its "description" (e.g., for `@returns {someType} some description`, the
            * description is `some description` while for `@some-tag xyz`, the description
            * is `xyz`).
-           *
            */
           tags?: string[];
         }
@@ -1577,8 +1587,6 @@ export interface Rules {
            * in this configuration object regardless of whether you have configured
            * `fileoverview` instead of `file` on `tagNamePreference` (i.e., `fileoverview`
            * will be checked, but you must use `file` on the configuration object).
-           *
-           *
            */
           tags?: {
             /**
@@ -1609,7 +1617,6 @@ export interface Rules {
            *   `'*': 'always'` to apply hyphen checking to any tag (besides the preferred
            *   `@param` tag which follows the main string option setting and besides any
            *   other `tags` entries).
-           *
            */
           tags?:
             | {
@@ -1640,7 +1647,6 @@ export interface Rules {
            * getters should be checked but only when there is no setter. This may be useful
            * if one only wishes documentation on one of the two accessors. Defaults to
            * `false`.
-           *
            */
           checkGetters?: boolean | "no-setter";
           /**
@@ -1695,7 +1701,6 @@ export interface Rules {
            * function/method names are sufficient for themselves as documentation).
            *
            * Defaults to `false`.
-           *
            */
           exemptEmptyFunctions?: boolean;
           /**
@@ -1728,7 +1733,6 @@ export interface Rules {
            * - `esm` - ESM exports are checked for JSDoc comments (Defaults to `true`)
            * - `cjs` - CommonJS exports are checked for JSDoc comments  (Defaults to `true`)
            * - `window` - Window global exports are checked for JSDoc comments
-           *
            */
           publicOnly?:
             | boolean
@@ -1795,13 +1799,11 @@ export interface Rules {
           /**
            * Numeric to indicate the number at which to begin auto-incrementing roots.
            * Defaults to `0`.
-           *
            */
           autoIncrementBase?: number;
           /**
            * A value indicating whether `constructor`s should be checked. Defaults to
            * `true`.
-           *
            */
           checkConstructors?: boolean;
           /**
@@ -1818,7 +1820,6 @@ export interface Rules {
            * implied to be `false` (i.e., the inside of the roots will not be checked
            * either, e.g., it will also not complain if `a` or `b` do not have their own
            * documentation). Defaults to `true`.
-           *
            */
           checkDestructuredRoots?: boolean;
           /**
@@ -1876,7 +1877,6 @@ export interface Rules {
            * function quux ({num, ...extra}) {
            * }
            * ```
-           *
            */
           checkRestProperty?: boolean;
           /**
@@ -1930,7 +1930,6 @@ export interface Rules {
            *
            * See the ["AST and Selectors"](../#advanced-ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
-           *
            */
           contexts?: (
             | string
@@ -1977,7 +1976,6 @@ export interface Rules {
            * type to use.
            *
            * Defaults to `true`.
-           *
            */
           enableRestElementFixer?: boolean;
           /**
@@ -2128,7 +2126,6 @@ export interface Rules {
            *
            * See the ["AST and Selectors"](../#advanced-ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
-           *
            */
           contexts?: (
             | string
@@ -2281,7 +2278,6 @@ export interface Rules {
            * - `esm` - ESM exports are checked for `@returns` JSDoc comments (Defaults to `true`)
            * - `cjs` - CommonJS exports are checked for `@returns` JSDoc comments  (Defaults to `true`)
            * - `window` - Window global exports are checked for `@returns` JSDoc comments
-           *
            */
           publicOnly?:
             | boolean
@@ -2438,12 +2434,14 @@ export interface Rules {
            * ```
            *
            * Defaults to `false`.
-           *
            */
           requireSeparateTemplates?: boolean;
         }
       ];
 
+  /** Requires a description for `@template` tags */
+  "jsdoc/require-template-description": [];
+
   /** Requires that throw statements are documented with `@throws` tags. */
   "jsdoc/require-throws": 
     | []
@@ -2839,7 +2837,6 @@ export interface Rules {
            *   'todo',
            * ]}];
            * ```
-           *
            */
           tagSequence?: {
             /**

package/package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.62.0",
+    "@es-joy/jsdoccomment": "~0.64.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",
@@ -41,16 +41,16 @@
     "@types/estree": "^1.0.8",
     "@types/json-schema": "^7.0.15",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^24.5.2",
+    "@types/node": "^24.6.0",
     "@types/semver": "^7.7.1",
     "@types/spdx-expression-parse": "^3.0.5",
-    "@typescript-eslint/types": "^8.44.1",
+    "@typescript-eslint/types": "^8.45.0",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-istanbul": "^7.0.1",
     "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,17 +58,17 @@
     "glob": "^11.0.3",
     "globals": "^16.4.0",
     "husky": "^9.1.7",
-    "jsdoc-type-pratt-parser": "^5.9.0",
+    "jsdoc-type-pratt-parser": "^6.0.1",
     "json-schema": "^0.4.0",
     "json-schema-to-typescript": "^15.0.4",
-    "lint-staged": "^16.2.1",
-    "mocha": "^11.7.2",
+    "lint-staged": "^16.2.3",
+    "mocha": "^11.7.3",
     "open-editor": "^5.1.0",
     "replace": "^1.2.2",
     "rimraf": "^6.0.1",
     "semantic-release": "^24.2.9",
     "typescript": "5.9.2",
-    "typescript-eslint": "^8.44.1"
+    "typescript-eslint": "^8.45.0"
   },
   "engines": {
     "node": ">=20.11.0"
@@ -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.1"
+  "version": "60.6.0"
 }

package/src/index-cjs.js

@@ -21,6 +21,7 @@ import checkTypes from './rules/checkTypes.js';
 import checkValues from './rules/checkValues.js';
 import convertToJsdocComments from './rules/convertToJsdocComments.js';
 import emptyTags from './rules/emptyTags.js';
+import escapeInlineTags from './rules/escapeInlineTags.js';
 import implementsOnClasses from './rules/implementsOnClasses.js';
 import importsAsDependencies from './rules/importsAsDependencies.js';
 import informativeDocs from './rules/informativeDocs.js';
@@ -101,6 +102,7 @@ index.rules = {
   'check-values': checkValues,
   'convert-to-jsdoc-comments': convertToJsdocComments,
   'empty-tags': emptyTags,
+  'escape-inline-tags': escapeInlineTags,
   'implements-on-classes': implementsOnClasses,
   'imports-as-dependencies': importsAsDependencies,
   'informative-docs': informativeDocs,
@@ -188,6 +190,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: [
@@ -274,6 +287,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/check-values': warnOrError,
       'jsdoc/convert-to-jsdoc-comments': 'off',
       'jsdoc/empty-tags': warnOrError,
+      'jsdoc/escape-inline-tags': warnOrError,
       'jsdoc/implements-on-classes': warnOrError,
       'jsdoc/imports-as-dependencies': 'off',
       'jsdoc/informative-docs': 'off',
@@ -316,6 +330,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,
@@ -439,6 +454,7 @@ const logicalRules = [
   'jsdoc/check-types',
   'jsdoc/check-values',
   'jsdoc/empty-tags',
+  'jsdoc/escape-inline-tags',
   'jsdoc/implements-on-classes',
   'jsdoc/require-returns-check',
   'jsdoc/require-yields-check',

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

@@ -27,6 +27,7 @@ import checkTypes from './rules/checkTypes.js';
 import checkValues from './rules/checkValues.js';
 import convertToJsdocComments from './rules/convertToJsdocComments.js';
 import emptyTags from './rules/emptyTags.js';
+import escapeInlineTags from './rules/escapeInlineTags.js';
 import implementsOnClasses from './rules/implementsOnClasses.js';
 import importsAsDependencies from './rules/importsAsDependencies.js';
 import informativeDocs from './rules/informativeDocs.js';
@@ -107,6 +108,7 @@ index.rules = {
   'check-values': checkValues,
   'convert-to-jsdoc-comments': convertToJsdocComments,
   'empty-tags': emptyTags,
+  'escape-inline-tags': escapeInlineTags,
   'implements-on-classes': implementsOnClasses,
   'imports-as-dependencies': importsAsDependencies,
   'informative-docs': informativeDocs,
@@ -194,6 +196,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: [
@@ -280,6 +293,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/check-values': warnOrError,
       'jsdoc/convert-to-jsdoc-comments': 'off',
       'jsdoc/empty-tags': warnOrError,
+      'jsdoc/escape-inline-tags': warnOrError,
       'jsdoc/implements-on-classes': warnOrError,
       'jsdoc/imports-as-dependencies': 'off',
       'jsdoc/informative-docs': 'off',
@@ -322,6 +336,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,
@@ -445,6 +460,7 @@ const logicalRules = [
   'jsdoc/check-types',
   'jsdoc/check-values',
   'jsdoc/empty-tags',
+  'jsdoc/escape-inline-tags',
   'jsdoc/implements-on-classes',
   'jsdoc/require-returns-check',
   'jsdoc/require-yields-check',
@@ -694,7 +710,6 @@ index.configs['flat/recommended-mixed'] = [
 
 export default index;
 
-/* eslint-disable jsdoc/valid-types -- Bug */
 /**
  * @type {((
  *   cfg?: import('eslint').Linter.Config & {
@@ -732,7 +747,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/checkLineAlignment.js

@@ -338,8 +338,7 @@ ensure that at least one space is present after the asterisk delimiter.`,
           customSpacings: {
             additionalProperties: false,
             description: `An object with any of the following spacing keys set to an integer.
-If a spacing is not defined, it defaults to one.
-`,
+If a spacing is not defined, it defaults to one.`,
             properties: {
               postDelimiter: {
                 description: 'Affects spacing after the asterisk (e.g., `*   @param`)',