eslint-plugin-jsdoc 63.0.0 → 63.0.2

package/dist/rules.d.ts

@@ -575,7 +575,7 @@ export interface Rules {
            * 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)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -705,7 +705,7 @@ export interface Rules {
            * `FunctionExpression`). Set to `"any"` if you want the rule to apply to any
            * JSDoc block throughout your files.
            *
-           * See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -900,7 +900,7 @@ export interface Rules {
             /**
              * AST to confine the allowing or disallowing to JSDoc blocks
              * associated with a particular context. See the
-             * ["AST and Selectors"](../#advanced-ast-and-selectors)
+             * ["AST and Selectors"](../advanced.md#ast-and-selectors)
              * section of our Advanced docs for more on the expected format.
              */
             context?: string;
@@ -1087,7 +1087,7 @@ export interface Rules {
            * 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)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -1133,7 +1133,7 @@ export interface Rules {
            * function declaration or 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)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -1215,7 +1215,7 @@ export interface Rules {
            * function declaration or 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)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts: (
@@ -1248,7 +1248,7 @@ export interface Rules {
            * 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)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -1396,7 +1396,7 @@ export interface Rules {
            * 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)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -1495,7 +1495,7 @@ export interface Rules {
            * `FunctionExpression`). Set to `"any"` if you want the rule to apply to any
            * JSDoc block throughout your files.
            *
-           * See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -1681,7 +1681,7 @@ export interface Rules {
            * Note that you may need to disable `require` items (e.g., `MethodDefinition`)
            * if you are specifying a more precise form in `contexts` (e.g., `MethodDefinition:not([accessibility="private"] > FunctionExpression`).
            *
-           * See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -1938,7 +1938,7 @@ export interface Rules {
            * `TSMethodSignature` in TypeScript or restricting the contexts
            * which are checked.
            *
-           * See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -2090,7 +2090,7 @@ export interface Rules {
            * 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)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -2134,7 +2134,7 @@ export interface Rules {
            * 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)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -2165,7 +2165,7 @@ export interface Rules {
            * 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)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -2394,7 +2394,7 @@ export interface Rules {
            * 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)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (
@@ -2425,7 +2425,7 @@ export interface Rules {
            * 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)
+           * See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
            * section of our Advanced docs for more on the expected format.
            */
           contexts?: (

package/package.json

@@ -5,24 +5,24 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.86.0",
+    "@es-joy/jsdoccomment": "~0.87.0",
     "@es-joy/resolve.exports": "1.2.0",
     "are-docs-informative": "^0.0.2",
-    "comment-parser": "1.4.6",
+    "comment-parser": "1.4.7",
     "debug": "^4.4.3",
     "escape-string-regexp": "^4.0.0",
     "espree": "^11.2.0",
     "esquery": "^1.7.0",
     "html-entities": "^2.6.0",
-    "object-deep-merge": "^2.0.0",
+    "object-deep-merge": "^2.0.1",
     "parse-imports-exports": "^0.2.4",
-    "semver": "^7.8.0",
+    "semver": "^7.8.2",
     "spdx-expression-parse": "^4.0.0",
     "to-valid-identifier": "^1.0.0"
   },
   "description": "JSDoc linting rules for ESLint.",
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.2",
+    "@arethetypeswrong/cli": "^0.18.3",
     "@babel/cli": "8.0.0-rc.5",
     "@babel/core": "8.0.0-rc.5",
     "@babel/eslint-parser": "8.0.0-rc.5",
@@ -42,10 +42,10 @@
     "@types/estree": "^1.0.9",
     "@types/json-schema": "^7.0.15",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^25.9.0",
+    "@types/node": "^25.9.2",
     "@types/semver": "^7.7.1",
     "@types/spdx-expression-parse": "^4.0.0",
-    "@typescript-eslint/types": "8.59.4",
+    "@typescript-eslint/types": "8.60.1",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-istanbul": "^8.0.0",
     "babel-plugin-transform-import-meta": "^2.3.3",
@@ -53,7 +53,7 @@
     "camelcase": "^9.0.0",
     "chai": "^6.2.2",
     "decamelize": "^6.0.1",
-    "eslint": "10.4.0",
+    "eslint": "10.4.1",
     "eslint-config-canonical": "^47.4.2",
     "gitdown": "^4.1.1",
     "glob": "^13.0.6",
@@ -62,18 +62,18 @@
     "jsdoc-type-pratt-parser": "^7.2.0",
     "json-schema": "^0.4.0",
     "json-schema-to-typescript": "^15.0.4",
-    "lint-staged": "^17.0.5",
-    "mocha": "^11.7.5",
+    "lint-staged": "^17.0.7",
+    "mocha": "^11.7.6",
     "open-editor": "^6.0.0",
     "playwright": "^1.60.0",
     "replace": "^1.2.2",
     "rimraf": "^6.1.3",
-    "rollup": "^4.60.4",
+    "rollup": "^4.61.1",
     "semantic-release": "^25.0.3",
     "sinon": "^22.0.0",
     "ts-api-utils": "^2.5.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.59.4"
+    "typescript-eslint": "8.60.1"
   },
   "engines": {
     "node": "^22.13.0 || >=24"
@@ -179,5 +179,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": "63.0.0"
+  "version": "63.0.2"
 }

package/src/jsdocUtils.js

@@ -6,6 +6,7 @@ import {
 } from './tagNames.js';
 import WarnSettings from './WarnSettings.js';
 import {
+  parseComment,
   stringify,
   tryParse,
 } from '@es-joy/jsdoccomment';
@@ -1084,6 +1085,41 @@ const isNameOrNamepathDefiningTag = (tag, tagMap = tagStructure) => {
     tagStruct.get('namepathRole')));
 };
 
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @returns {import('@es-joy/jsdoccomment').JsdocBlockWithInline[]}
+ */
+const getJSDocCommentBlocks = (sourceCode) => {
+  return sourceCode.getAllComments()
+    .filter((comment) => {
+      return (/^\*(?!\*)/v).test(comment.value);
+    })
+    .map((commentNode) => {
+      return parseComment(commentNode, '');
+    });
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @returns {import('comment-parser').Spec[]}
+ */
+const getDocumentNamepathDefiningTags = (sourceCode) => {
+  return getJSDocCommentBlocks(sourceCode)
+    .flatMap((doc) => {
+      return doc.tags.filter(({
+        tag,
+      }) => {
+        return isNameOrNamepathDefiningTag(tag) && ![
+          'arg',
+          'argument',
+          'param',
+          'prop',
+          'property',
+        ].includes(tag);
+      });
+    });
+};
+
 /**
  * @param {string} tag
  * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
@@ -2110,9 +2146,11 @@ export {
   forEachPreferredTag,
   getAllTags,
   getContextObject,
+  getDocumentNamepathDefiningTags,
   getFunctionParameterNames,
   getIndent,
   getInlineTags,
+  getJSDocCommentBlocks,
   getJsdocTagsDeep,
   getPreferredTagName,
   getPreferredTagNameSimple,

package/src/rules/emptyTags.js

@@ -55,6 +55,14 @@ export default iterateJsdoc(({
       // Allow for JSDoc-block final asterisks
       key !== emptyTags.length - 1 || !(/^\s*\*+$/v).test(content)
     )) {
+      const {
+        tokens: {
+          delimiter,
+          end,
+          postName,
+          start,
+        },
+      } = tag.source[0];
       const fix = () => {
         // By time of call in fixer, `tag` will have `line` added
         utils.setTag(
@@ -63,6 +71,12 @@ export default iterateJsdoc(({
            *   line: import('../iterateJsdoc.js').Integer
            * }}
            */ (tag),
+          {
+            delimiter,
+            end,
+            postName: end ? postName : '',
+            start,
+          },
         );
       };
 

package/src/rules/implementsOnClasses.js

@@ -46,7 +46,7 @@ for finding function blocks not attached to a function declaration or
 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)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [

package/src/rules/matchDescription.js

@@ -183,7 +183,7 @@ Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclarati
 \`FunctionExpression\`). Set to \`"any"\` if you want the rule to apply to any
 JSDoc block throughout your files.
 
-See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [

package/src/rules/matchName.js

@@ -135,7 +135,7 @@ Accepts a string regular expression (optionally wrapped between two
                 context: {
                   description: `AST to confine the allowing or disallowing to JSDoc blocks
 associated with a particular context. See the
-["AST and Selectors"](../#advanced-ast-and-selectors)
+["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
                   type: 'string',
                 },

package/src/rules/noDefaults.js

@@ -64,7 +64,7 @@ for finding function blocks not attached to a function declaration or
 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)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [

package/src/rules/noMissingSyntax.js

@@ -177,7 +177,7 @@ your files (as is necessary for finding function blocks not attached to a
 function declaration or 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)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [

package/src/rules/noRestrictedSyntax.js

@@ -35,7 +35,7 @@ your files (as is necessary for finding function blocks not attached to a
 function declaration or 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)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
           items: {
             anyOf: [

package/src/rules/noTypes.js

@@ -76,7 +76,7 @@ for finding function blocks not attached to a function declaration or
 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)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [

package/src/rules/noUndefinedTypes.js

@@ -1,6 +1,10 @@
 import iterateJsdoc, {
   parseComment,
 } from '../iterateJsdoc.js';
+import {
+  getDocumentNamepathDefiningTags,
+  getJSDocCommentBlocks,
+} from '../jsdocUtils.js';
 import {
   getJSDocComment,
   parse as parseType,
@@ -123,13 +127,7 @@ export default iterateJsdoc(({
   }
 
   const allComments = sourceCode.getAllComments();
-  const comments = allComments
-    .filter((comment) => {
-      return (/^\*(?!\*)/v).test(comment.value);
-    })
-    .map((commentNode) => {
-      return parseComment(commentNode, '');
-    });
+  const comments = getJSDocCommentBlocks(sourceCode);
 
   const globals = allComments
     .filter((comment) => {
@@ -138,20 +136,7 @@ export default iterateJsdoc(({
       return commentNode.value.replace(/^\s*globals/v, '').trim().split(/,\s*/v);
     }).concat(Object.keys(context.languageOptions.globals ?? []));
 
-  const typedefs = comments
-    .flatMap((doc) => {
-      return doc.tags.filter(({
-        tag,
-      }) => {
-        return utils.isNameOrNamepathDefiningTag(tag) && ![
-          'arg',
-          'argument',
-          'param',
-          'prop',
-          'property',
-        ].includes(tag);
-      });
-    });
+  const typedefs = getDocumentNamepathDefiningTags(sourceCode);
 
   const typedefDeclarations = typedefs
     .map((tag) => {

package/src/rules/requireDescription.js

@@ -138,7 +138,7 @@ for finding function blocks not attached to a function declaration or
 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)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [

package/src/rules/requireExample.js

@@ -88,7 +88,7 @@ Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclarati
 \`FunctionExpression\`). Set to \`"any"\` if you want the rule to apply to any
 JSDoc block throughout your files.
 
-See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [

package/src/rules/requireJsdoc.js

@@ -102,7 +102,7 @@ for it to require documentation.
 Note that you may need to disable \`require\` items (e.g., \`MethodDefinition\`)
 if you are specifying a more precise form in \`contexts\` (e.g., \`MethodDefinition:not([accessibility="private"] > FunctionExpression\`).
 
-See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
       items: {
         anyOf: [

package/src/rules/requireParam.js

@@ -684,7 +684,7 @@ Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclarati
 \`TSMethodSignature\` in TypeScript or restricting the contexts
 which are checked.
 
-See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [

package/src/rules/requireParamDescription.js

@@ -65,7 +65,7 @@ for finding function blocks not attached to a function declaration or
 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)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [

package/src/rules/requireParamName.js

@@ -37,7 +37,7 @@ for finding function blocks not attached to a function declaration or
 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)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [

package/src/rules/requireParamType.js

@@ -65,7 +65,7 @@ for finding function blocks not attached to a function declaration or
 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)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [

package/src/rules/requireReturnsCheck.js

@@ -1,7 +1,27 @@
 import iterateJsdoc from '../iterateJsdoc.js';
 import {
+  getDocumentNamepathDefiningTags,
   strictNativeTypes,
 } from '../jsdocUtils.js';
+import {
+  traverse,
+  tryParse as tryParseType,
+} from '@es-joy/jsdoccomment';
+
+/**
+ * @type {Partial<Record<import('../jsdocUtils.js').ParserMode, import('jsdoc-type-pratt-parser').ParseMode[]>>}
+ */
+const parseTypeModes = {
+  closure: [
+    'closure',
+  ],
+  jsdoc: [
+    'jsdoc',
+  ],
+  typescript: [
+    'typescript',
+  ],
+};
 
 /**
  * @param {import('../iterateJsdoc.js').Utils} utils
@@ -36,11 +56,35 @@ const canSkip = (utils, settings) => {
     settings.mode === 'closure' && utils.classHasTag('record');
 };
 
+/**
+ * @param {import('jsdoc-type-pratt-parser').RootResult} parsedType
+ * @returns {import('jsdoc-type-pratt-parser').RootResult}
+ */
+const getReturnTypeLevelNode = (parsedType) => {
+  return parsedType.type === 'JsdocTypeParenthesis' ?
+    parsedType.element :
+    parsedType;
+};
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {import('../jsdocUtils.js').ParserMode} mode
+ * @returns {import('../jsdocUtils.js').ParserMode}
+ */
+const getParseMode = (context, mode) => {
+  const {
+    jsdoc,
+  } = /** @type {{jsdoc?: {mode?: import('../jsdocUtils.js').ParserMode}}} */ (context.settings);
+
+  return jsdoc?.mode ?? mode;
+};
+
 export default iterateJsdoc(({
   context,
   node,
   report,
   settings,
+  sourceCode,
   utils,
 }) => {
   const {
@@ -49,6 +93,10 @@ export default iterateJsdoc(({
     noNativeTypes = true,
     reportMissingReturnForUndefinedTypes = false,
   } = context.options[0] || {};
+  const {
+    mode,
+  } = settings;
+  const parseMode = getParseMode(context, mode);
 
   if (canSkip(utils, settings)) {
     return;
@@ -90,6 +138,67 @@ export default iterateJsdoc(({
   }
 
   const returnNever = type === 'never';
+  const typedefs = getDocumentNamepathDefiningTags(sourceCode);
+
+  /**
+   * @param {import('comment-parser').Spec} returnTag
+   * @returns {boolean}
+   */
+  const mayReturnUndefined = (returnTag) => {
+    if (utils.mayBeUndefinedTypeTag(returnTag)) {
+      return true;
+    }
+
+    const returnType = returnTag.type.trim();
+    let parsedType;
+    try {
+      parsedType = tryParseType(returnType, parseTypeModes[parseMode]);
+    } catch {
+      return false;
+    }
+
+    const returnTypeLevelNode = getReturnTypeLevelNode(parsedType);
+    let returnIsUndefined = false;
+    traverse(returnTypeLevelNode, (nde, parentNode) => {
+      const isReturnLevelNode = !parentNode ||
+        returnTypeLevelNode.type === 'JsdocTypeUnion' && parentNode === returnTypeLevelNode;
+      if (!isReturnLevelNode) {
+        return;
+      }
+
+      const {
+        type: nodeType,
+      } = /** @type {import('jsdoc-type-pratt-parser').RootResult} */ (nde);
+
+      if (nodeType === 'JsdocTypeUndefined') {
+        returnIsUndefined = true;
+        return;
+      }
+
+      if (nodeType !== 'JsdocTypeName') {
+        return;
+      }
+
+      const {
+        value,
+      } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);
+
+      if (value === 'void') {
+        returnIsUndefined = true;
+        return;
+      }
+
+      const referencedTypedef = typedefs.find((typedefTag) => {
+        return typedefTag.name === value;
+      });
+
+      if (referencedTypedef && utils.mayBeUndefinedTypeTag(referencedTypedef)) {
+        returnIsUndefined = true;
+      }
+    });
+
+    return returnIsUndefined;
+  };
 
   if (returnNever && utils.hasValueOrExecutorHasNonEmptyResolveValue(false)) {
     report(`JSDoc @${tagName} declaration set with "never" but return expression is present in function.`);
@@ -107,7 +216,7 @@ export default iterateJsdoc(({
     !returnNever &&
     (
       reportMissingReturnForUndefinedTypes ||
-      !utils.mayBeUndefinedTypeTag(tag)
+      !mayReturnUndefined(tag)
     ) &&
     (tag.type === '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(
       exemptAsync,

package/src/rules/requireReturnsDescription.js

@@ -41,7 +41,7 @@ for finding function blocks not attached to a function declaration or
 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)
+See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
 section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [