eslint-plugin-jsdoc 60.5.0 → 60.7.0

package/src/rules/checkTypes.js

@@ -1,21 +1,9 @@
 import {
   buildRejectOrPreferRuleDefinition,
 } from '../buildRejectOrPreferRuleDefinition.js';
-
-const strictNativeTypes = [
-  'undefined',
-  'null',
-  'boolean',
-  'number',
-  'bigint',
-  'string',
-  'symbol',
-  'object',
-  'Array',
-  'Function',
-  'Date',
-  'RegExp',
-];
+import {
+  strictNativeTypes,
+} from '../jsdocUtils.js';
 
 /**
  * @callback CheckNativeTypes

package/src/rules/convertToJsdocComments.js

@@ -319,8 +319,7 @@ Supplying your own value overrides the defaults.`,
 Can either be strings or an object with a \`context\` string and an optional, default \`false\` \`inlineCommentBlock\` boolean.
 
 Defaults to \`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
-\`FunctionExpression\`, \`TSDeclareFunction\`.
-`,
+\`FunctionExpression\`, \`TSDeclareFunction\`.`,
             items: {
               anyOf: [
                 {
@@ -417,8 +416,7 @@ be converted to \`multi\` style JSDoc comments.)
 /** Some text */
 \`\`\`
 
-Defaults to \`multi\`.
-`,
+Defaults to \`multi\`.`,
             enum: [
               'multi', 'single',
             ],

package/src/rules/emptyTags.js

@@ -91,8 +91,7 @@ add them within this option.
 {
   'jsdoc/empty-tags': ['error', {tags: ['event']}]
 }
-\`\`\`
-`,
+\`\`\``,
             items: {
               type: 'string',
             },

package/src/rules/escapeInlineTags.js

@@ -0,0 +1,189 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  settings,
+  utils,
+}) => {
+  const {
+    mode,
+  } = settings;
+
+  if (mode !== 'typescript') {
+    return;
+  }
+
+  const {
+    allowedInlineTags = [],
+    enableFixer = false,
+    fixType = 'backslash',
+  } = context.options[0] || {};
+
+  const {
+    description,
+  } = utils.getDescription();
+
+  /** @type {string[]} */
+  const tagNames = [];
+
+  /** @type {number[]} */
+  const indexes = [];
+
+  const unescapedInlineTagRegex = /(?:^|\s)@(\w+)/gv;
+  for (const [
+    idx,
+    descLine,
+  ] of (
+      description.startsWith('\n') ? description.slice(1) : description
+    ).split('\n').entries()
+  ) {
+    descLine.replaceAll(unescapedInlineTagRegex, (_, tagName) => {
+      if (allowedInlineTags.includes(tagName)) {
+        return _;
+      }
+
+      tagNames.push(tagName);
+      indexes.push(idx);
+
+      return _;
+    });
+  }
+
+  for (const [
+    idx,
+    tagName,
+  ] of tagNames.entries()) {
+    utils.reportJSDoc(
+      `Unexpected inline JSDoc tag. Did you mean to use {@${tagName}}, \\@${tagName}, or \`@${tagName}\`?`,
+      {
+        line: indexes[idx] + 1,
+      },
+      enableFixer ?
+        () => {
+          utils.setBlockDescription((info, seedTokens, descLines) => {
+            return descLines.map((desc) => {
+              const newDesc = desc.replaceAll(
+                new RegExp(`(^|\\s)@${
+                  // No need to escape, as contains only safe characters
+                  tagName
+                }`, 'gv'),
+                fixType === 'backticks' ? '$1`@' + tagName + '`' : '$1\\@' + tagName,
+              );
+
+              return {
+                number: 0,
+                source: '',
+                tokens: seedTokens({
+                  ...info,
+                  description: newDesc,
+                  postDelimiter: newDesc.trim() ? ' ' : '',
+                }),
+              };
+            });
+          });
+        } :
+        null,
+    );
+  }
+
+  /**
+   * @param {string} tagName
+   * @returns {[
+   *   RegExp,
+   *   (description: string) => string
+   * ]}
+   */
+  const escapeInlineTags = (tagName) => {
+    const regex = new RegExp(`(^|\\s)@${
+      // No need to escape, as contains only safe characters
+      tagName
+    }`, 'gv');
+
+    return [
+      regex,
+      /**
+       * @param {string} desc
+       */
+      (desc) => {
+        return desc.replaceAll(
+          regex,
+          fixType === 'backticks' ? '$1`@' + tagName + '`' : '$1\\@' + tagName,
+        );
+      },
+    ];
+  };
+
+  for (const tag of jsdoc.tags) {
+    if (tag.tag === 'example') {
+      continue;
+    }
+
+    /** @type {string} */
+    let tagName = '';
+    while (/** @type {string[]} */ (
+      utils.getTagDescription(tag, true)
+    // eslint-disable-next-line no-loop-func -- Safe
+    ).some((desc) => {
+      tagName = unescapedInlineTagRegex.exec(desc)?.[1] ?? '';
+      if (allowedInlineTags.includes(tagName)) {
+        return false;
+      }
+
+      return tagName;
+    })) {
+      const line = utils.setTagDescription(tag, ...escapeInlineTags(tagName)) +
+          tag.source[0].number;
+      utils.reportJSDoc(
+        `Unexpected inline JSDoc tag. Did you mean to use {@${tagName}}, \\@${tagName}, or \`@${tagName}\`?`,
+        {
+          line,
+        },
+        enableFixer ? () => {} : null,
+        true,
+      );
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Reports use of JSDoc tags in non-tag positions (in the default "typescript" mode).',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/escape-inline-tags.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          allowedInlineTags: {
+            description: 'A listing of tags you wish to allow unescaped. Defaults to an empty array.',
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+          enableFixer: {
+            description: 'Whether to enable the fixer. Defaults to `false`.',
+            type: 'boolean',
+          },
+          fixType: {
+            description: `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".`,
+            enum: [
+              'backticks',
+              'backslash',
+            ],
+            type: 'string',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/informativeDocs.js

@@ -171,8 +171,7 @@ The default \`aliases\` option is:
 {
   "a": ["an", "our"]
 }
-\`\`\`
-`,
+\`\`\``,
             patternProperties: {
               '.*': {
                 items: {
@@ -194,8 +193,7 @@ function computeTypes(node) {
 }
 \`\`\`
 
-No tags are excluded by default.
-`,
+No tags are excluded by default.`,
             items: {
               type: 'string',
             },
@@ -215,8 +213,7 @@ The default \`uselessWords\` option is:
 
 \`\`\`json
 ["a", "an", "i", "in", "of", "s", "the"]
-\`\`\`
-`,
+\`\`\``,
             items: {
               type: 'string',
             },

package/src/rules/linesBeforeBlock.js

@@ -109,15 +109,13 @@ export default iterateJsdoc(({
         properties: {
           checkBlockStarts: {
             description: `Whether to additionally check the start of blocks, such as classes or functions.
-Defaults to \`false\`.
-`,
+Defaults to \`false\`.`,
             type: 'boolean',
           },
           excludedTags: {
             description: `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).
-`,
+lines before the block will not be added).`,
             items: {
               type: 'string',
             },
@@ -125,14 +123,12 @@ lines before the block will not be added).
           },
           ignoreSameLine: {
             description: `This option excludes cases where the JSDoc block occurs on the same line as a
-preceding code or comment. Defaults to \`true\`.
-`,
+preceding code or comment. Defaults to \`true\`.`,
             type: 'boolean',
           },
           ignoreSingleLines: {
             description: `This option excludes cases where the JSDoc block is only one line long.
-Defaults to \`true\`.
-`,
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           lines: {

package/src/rules/matchDescription.js

@@ -184,8 +184,7 @@ Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclarati
 JSDoc block throughout your files.
 
 See the ["AST and Selectors"](../#advanced-ast-and-selectors)
-section of our Advanced docs for more on the expected format.
-`,
+section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [
                 {
@@ -302,8 +301,7 @@ literal, e.g., \`/[A-Z].*\\./vi\`.
 \`\`\`
 
 This can be overridden per tag or for the main block description by setting
-\`message\` within \`tags\` or \`mainDescription\`, respectively.
-`,
+\`message\` within \`tags\` or \`mainDescription\`, respectively.`,
             type: 'string',
           },
           nonemptyTags: {

package/src/rules/matchName.js

@@ -118,8 +118,7 @@ fixes found by the likes of \`disallowName\` even when a different tag has the
 disallowed name. An alternative is to ensure that \`comment\` finds the specific
 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.
-`,
+be applied, however.`,
             items: {
               additionalProperties: false,
               properties: {

package/src/rules/multilineBlocks.js

@@ -494,8 +494,7 @@ such a tag will cause multiline blocks to be allowed.
 You may set this to an empty array to prevent any tag from permitting multiple
 lines.
 
-Defaults to \`['*']\`.
-`,
+Defaults to \`['*']\`.`,
           },
           noFinalLineText: {
             description: `For multiline blocks, any non-whitespace text preceding the \`*/\` on the final
@@ -518,8 +517,7 @@ Defaults to \`false\`.`,
             description: `If this is \`true\`, any single line blocks will be reported, except those which
 are whitelisted in \`singleLineTags\`.
 
-Defaults to \`false\`.
-`,
+Defaults to \`false\`.`,
             type: 'boolean',
           },
           noZeroLineText: {
@@ -539,8 +537,7 @@ for such cases. Blocks are not reported which have multi-line descriptions,
 multiple tags, a block description and tag, or tags with multi-line types or
 descriptions.
 
-Defaults to \`null\`.
-`,
+Defaults to \`null\`.`,
             type: 'number',
           },
           singleLineTags: {

package/src/rules/noBadBlocks.js

@@ -106,8 +106,7 @@ export default iterateJsdoc(({
 a multi-comment block and at-sign \`/* @\`.
 
 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)).
-`,
+(some directives [used by TypeScript](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#ts-check)).`,
             items: {
               type: 'string',
             },

package/src/rules/noTypes.js

@@ -77,8 +77,7 @@ expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
 \`@method\`) (including those associated with an \`@interface\`).
 
 See the ["AST and Selectors"](../#advanced-ast-and-selectors)
-section of our Advanced docs for more on the expected format.
-`,
+section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [
                 {

package/src/rules/preferImportTag.js

@@ -16,6 +16,7 @@ import {
 
 export default iterateJsdoc(({
   context,
+  indent,
   jsdoc,
   settings,
   sourceCode,
@@ -363,10 +364,14 @@ export default iterateJsdoc(({
           enableFixer ? (fixer) => {
             getFixer(element.value, [])();
 
-            const programNode = sourceCode.getNodeByRangeIndex(0);
+            const programNode = sourceCode.ast;
+            const commentNodes = sourceCode.getCommentsBefore(programNode);
             return fixer.insertTextBefore(
-              /** @type {import('estree').Program} */ (programNode),
-              `/** @import * as ${element.value} from '${element.value}'; */`,
+              // @ts-expect-error Ok
+              commentNodes[0] ?? programNode,
+              `/** @import * as ${element.value} from '${element.value}'; */${
+                commentNodes[0] ? '\n' + indent : ''
+              }`,
             );
           } : null,
         );

package/src/rules/requireAsteriskPrefix.js

@@ -180,8 +180,7 @@ which applies to the main JSDoc block description.
     }
   }]
 }
-\`\`\`
-`,
+\`\`\``,
             properties: {
               always: {
                 description: `If it is \`"always"\` then a problem is raised when there is no asterisk

package/src/rules/requireDescriptionCompleteSentence.js

@@ -346,8 +346,7 @@ All other tags will treat the text following the tag name, a space, and
 an optional curly-bracketed type expression (and another space) as part of
 its "description" (e.g., for \`@returns {someType} some description\`, the
 description is \`some description\` while for \`@some-tag xyz\`, the description
-is \`xyz\`).
-`,
+is \`xyz\`).`,
             items: {
               type: 'string',
             },

package/src/rules/requireFileOverview.js

@@ -176,9 +176,7 @@ have a way to allow multiple licenses for the whole page by using the SPDX
 Note that the tag names are the main JSDoc tag name, so you should use \`file\`
 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).
-
-`,
+will be checked, but you must use \`file\` on the configuration object).`,
             patternProperties: {
               '.*': {
                 additionalProperties: false,

package/src/rules/requireHyphenBeforeParamDescription.js

@@ -199,8 +199,7 @@ other tags besides the \`@param\` tag (or the \`@arg\` tag if so set).`,
   to ensure \`@property\` never uses hyphens. A key can also be set as \`*\`, e.g.,
   \`'*': '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).
-`,
+  other \`tags\` entries).`,
           },
         },
         type: 'object',

package/src/rules/requireJsdoc.js

@@ -60,8 +60,7 @@ no parameters or return values are found.`,
 boolean, this option can be set to the string \`"no-setter"\` to indicate that
 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\`.
-`,
+\`false\`.`,
     },
     checkSetters: {
       anyOf: [
@@ -143,8 +142,7 @@ Defaults to \`true\`.`,
 functions/methods with no parameters or return values (intended where
 function/method names are sufficient for themselves as documentation).
 
-Defaults to \`false\`.
-`,
+Defaults to \`false\`.`,
       type: 'boolean',
     },
     exemptOverloadedImplementations: {
@@ -178,8 +176,7 @@ otherwise noted):
 - \`ancestorsOnly\` - Optimization to only check node ancestors to check if node is exported
 - \`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
-`,
+- \`window\` - Window global exports are checked for JSDoc comments`,
       oneOf: [
         {
           default: false,

package/src/rules/requireParam.js

@@ -548,15 +548,13 @@ export default iterateJsdoc(({
           autoIncrementBase: {
             default: 0,
             description: `Numeric to indicate the number at which to begin auto-incrementing roots.
-Defaults to \`0\`.
-`,
+Defaults to \`0\`.`,
             type: 'integer',
           },
           checkConstructors: {
             default: true,
             description: `A value indicating whether \`constructor\`s should be checked. Defaults to
-\`true\`.
-`,
+\`true\`.`,
             type: 'boolean',
           },
           checkDestructured: {
@@ -574,8 +572,7 @@ the \`{a, b}\` object parameter).
 If \`checkDestructuredRoots\` is \`false\`, \`checkDestructured\` will also be
 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\`.
-`,
+documentation). Defaults to \`true\`.`,
             type: 'boolean',
           },
           checkGetters: {
@@ -634,8 +631,7 @@ Nor will this:
  */
 function quux ({num, ...extra}) {
 }
-\`\`\`
-`,
+\`\`\``,
             type: 'boolean',
           },
           checkSetters: {
@@ -689,8 +685,7 @@ Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclarati
 which are checked.
 
 See the ["AST and Selectors"](../#advanced-ast-and-selectors)
-section of our Advanced docs for more on the expected format.
-`,
+section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [
                 {
@@ -749,8 +744,7 @@ function baar ([a, ...extra]) {
 Note that the type \`any\` is included since we don't know of any specific
 type to use.
 
-Defaults to \`true\`.
-`,
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           enableRootFixer: {

package/src/rules/requireParamName.js

@@ -38,8 +38,7 @@ expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
 \`@method\`) (including those associated with an \`@interface\`).
 
 See the ["AST and Selectors"](../#advanced-ast-and-selectors)
-section of our Advanced docs for more on the expected format.
-`,
+section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [
                 {

package/src/rules/requireReturns.js

@@ -254,8 +254,7 @@ otherwise noted):
 - \`ancestorsOnly\` - Optimization to only check node ancestors to check if node is exported
 - \`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
-`,
+- \`window\` - Window global exports are checked for \`@returns\` JSDoc comments`,
             oneOf: [
               {
                 default: false,

package/src/rules/requireReturnsCheck.js

@@ -1,4 +1,7 @@
 import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  strictNativeTypes,
+} from '../jsdocUtils.js';
 
 /**
  * @param {import('../iterateJsdoc.js').Utils} utils
@@ -43,6 +46,7 @@ export default iterateJsdoc(({
   const {
     exemptAsync = true,
     exemptGenerators = settings.mode === 'typescript',
+    noNativeTypes = true,
     reportMissingReturnForUndefinedTypes = false,
   } = context.options[0] || {};
 
@@ -50,7 +54,8 @@ export default iterateJsdoc(({
     return;
   }
 
-  if (exemptAsync && utils.isAsync()) {
+  const isAsync = utils.isAsync();
+  if (exemptAsync && isAsync) {
     return;
   }
 
@@ -92,6 +97,11 @@ export default iterateJsdoc(({
     return;
   }
 
+  if (noNativeTypes && isAsync && strictNativeTypes.includes(type)) {
+    report('Function is async or otherwise returns a Promise but the return type is a native type.');
+    return;
+  }
+
   // In case a return value is declared in JSDoc, we also expect one in the code.
   if (
     !returnNever &&
@@ -147,6 +157,11 @@ one might be more likely to take advantage of \`@yields\`). Set it to \`false\`
 if you wish for a missing \`return\` to be flagged regardless.`,
             type: 'boolean',
           },
+          noNativeTypes: {
+            description: `Whether to check that async functions do not
+indicate they return non-native types. Defaults to \`true\`.`,
+            type: 'boolean',
+          },
           reportMissingReturnForUndefinedTypes: {
             default: false,
             description: `If \`true\` and no return or

package/src/rules/requireTemplate.js

@@ -214,8 +214,7 @@ templates of this format:
  */
 \`\`\`
 
-Defaults to \`false\`.
-`,
+Defaults to \`false\`.`,
             type: 'boolean',
           },
         },

package/src/rules/sortTags.js

@@ -729,8 +729,7 @@ a fixed order that doesn't change into the future, supply your own
   'deprecated',
   'todo',
 ]}];
-\`\`\`
-`,
+\`\`\``,
             items: {
               additionalProperties: false,
               properties: {