eslint-plugin-jsdoc 50.6.16 → 50.7.0

package/src/jsdocUtils.js

@@ -4,10 +4,6 @@ import {
   jsdocTags,
   typeScriptTags,
 } from './tagNames.js';
-import {
-  hasReturnValue,
-  hasValueOrExecutorHasNonEmptyResolveValue,
-} from './utils/hasReturnValue.js';
 import WarnSettings from './WarnSettings.js';
 import {
   tryParse,
@@ -308,70 +304,12 @@ const getFunctionParameterNames = (
 
     if (param.type === 'Property') {
       switch (param.value.type) {
-      case 'ArrayPattern': {
-        return [
-          /** @type {import('estree').Identifier} */
-          (param.key).name,
-          /** @type {import('estree').ArrayPattern} */ (
-            param.value
-          ).elements.map((prop, idx) => {
-            return {
-              name: idx,
-              restElement: prop?.type === 'RestElement',
-            };
-          }),
-        ];
-      }
-
-      case 'ObjectPattern': {
-        return [
-          /** @type {import('estree').Identifier} */ (param.key).name,
-          /** @type {import('estree').ObjectPattern} */ (
-            param.value
-          ).properties.map((prop) => {
-            return /** @type {string|[string, string[]]} */ (getParamName(prop, isProperty));
-          }),
-        ];
-      }
-
-      case 'AssignmentPattern': {
-        switch (param.value.left.type) {
-        case 'Identifier':
-          // Default parameter
-          if (checkDefaultObjects && param.value.right.type === 'ObjectExpression') {
-            return [
-              /** @type {import('estree').Identifier} */ (
-                param.key
-              ).name,
-              /** @type {import('estree').AssignmentPattern} */ (
-                param.value
-              ).right.properties.map((prop) => {
-                return /** @type {string} */ (getParamName(
-                  /** @type {import('estree').Property} */
-                  (prop),
-                  isProperty,
-                ));
-              }),
-            ];
-          }
-
-          break;
-        case 'ObjectPattern':
+        case 'ArrayPattern': {
           return [
-            /** @type {import('estree').Identifier} */
-            (param.key).name,
-            /** @type {import('estree').ObjectPattern} */ (
-              param.value.left
-            ).properties.map((prop) => {
-              return getParamName(prop, isProperty);
-            }),
-          ];
-        case 'ArrayPattern':
-          return [
-            /** @type {import('estree').Identifier} */
+          /** @type {import('estree').Identifier} */
             (param.key).name,
             /** @type {import('estree').ArrayPattern} */ (
-              param.value.left
+              param.value
             ).elements.map((prop, idx) => {
               return {
                 name: idx,
@@ -380,26 +318,84 @@ const getFunctionParameterNames = (
             }),
           ];
         }
-      }
+
+        case 'ObjectPattern': {
+          return [
+          /** @type {import('estree').Identifier} */ (param.key).name,
+            /** @type {import('estree').ObjectPattern} */ (
+              param.value
+            ).properties.map((prop) => {
+              return /** @type {string|[string, string[]]} */ (getParamName(prop, isProperty));
+            }),
+          ];
+        }
+
+        case 'AssignmentPattern': {
+          switch (param.value.left.type) {
+            case 'ArrayPattern':
+              return [
+                /** @type {import('estree').Identifier} */
+                (param.key).name,
+                /** @type {import('estree').ArrayPattern} */ (
+                  param.value.left
+                ).elements.map((prop, idx) => {
+                  return {
+                    name: idx,
+                    restElement: prop?.type === 'RestElement',
+                  };
+                }),
+              ];
+            case 'Identifier':
+              // Default parameter
+              if (checkDefaultObjects && param.value.right.type === 'ObjectExpression') {
+                return [
+                  /** @type {import('estree').Identifier} */ (
+                    param.key
+                  ).name,
+                  /** @type {import('estree').AssignmentPattern} */ (
+                    param.value
+                  ).right.properties.map((prop) => {
+                    return /** @type {string} */ (getParamName(
+                      /** @type {import('estree').Property} */
+                      (prop),
+                      isProperty,
+                    ));
+                  }),
+                ];
+              }
+
+              break;
+            case 'ObjectPattern':
+              return [
+                /** @type {import('estree').Identifier} */
+                (param.key).name,
+                /** @type {import('estree').ObjectPattern} */ (
+                  param.value.left
+                ).properties.map((prop) => {
+                  return getParamName(prop, isProperty);
+                }),
+              ];
+          }
+        }
       }
 
       switch (param.key.type) {
-      case 'Identifier':
-        return param.key.name;
+        case 'Identifier':
+          return param.key.name;
 
-      // The key of an object could also be a string or number
-      case 'Literal':
+          // The key of an object could also be a string or number
+        case 'Literal':
         /* c8 ignore next 2 -- `raw` may not be present in all parsers */
-        return /** @type {string} */ (param.key.raw ||
+          return /** @type {string} */ (param.key.raw ||
           param.key.value);
 
-      // case 'MemberExpression':
-      default:
+          // case 'MemberExpression':
+        default:
         // Todo: We should really create a structure (and a corresponding
         //   option analogous to `checkRestProperty`) which allows for
         //   (and optionally requires) dynamic properties to have a single
         //   line of documentation
-        return undefined;
+          return undefined;
       }
     }
 
@@ -429,7 +425,7 @@ const getFunctionParameterNames = (
     }
 
     if ([
-      'RestElement', 'ExperimentalRestProperty',
+      'ExperimentalRestProperty', 'RestElement',
     ].includes(param.type)) {
       return {
         isRestProperty: isProperty,
@@ -437,9 +433,12 @@ const getFunctionParameterNames = (
           /** @type {import('@typescript-eslint/types').TSESTree.RestElement} */ (
             param
           // @ts-expect-error Ok
-          ).argument).name ?? param?.argument?.elements?.map(({name}) => {
-            return name;
-          }),
+          ).argument).name ?? param?.argument?.elements?.map(({
+          // @ts-expect-error Ok
+          name,
+        }) => {
+          return name;
+        }),
         restElement: true,
       };
     }
@@ -526,32 +525,32 @@ const modeWarnSettings = WarnSettings();
  */
 const getTagNamesForMode = (mode, context) => {
   switch (mode) {
-  case 'jsdoc':
-    return jsdocTags;
-  case 'typescript':
-    return typeScriptTags;
-  case 'closure': case 'permissive':
-    return closureTags;
-  default:
-    if (!modeWarnSettings.hasBeenWarned(context, 'mode')) {
-      context.report({
-        loc: {
-          end: {
-            column: 1,
-            line: 1,
+    case 'closure':
+    case 'permissive':
+      return closureTags;
+    case 'jsdoc':
+      return jsdocTags; case 'typescript':
+      return typeScriptTags;
+    default:
+      if (!modeWarnSettings.hasBeenWarned(context, 'mode')) {
+        context.report({
+          loc: {
+            end: {
+              column: 1,
+              line: 1,
+            },
+            start: {
+              column: 1,
+              line: 1,
+            },
           },
-          start: {
-            column: 1,
-            line: 1,
-          },
-        },
-        message: `Unrecognized value \`${mode}\` for \`settings.jsdoc.mode\`.`,
-      });
-      modeWarnSettings.markSettingAsWarned(context, 'mode');
-    }
+          message: `Unrecognized value \`${mode}\` for \`settings.jsdoc.mode\`.`,
+        });
+        modeWarnSettings.markSettingAsWarned(context, 'mode');
+      }
 
-    // We'll avoid breaking too many other rules
-    return jsdocTags;
+      // We'll avoid breaking too many other rules
+      return jsdocTags;
   }
 };
 
@@ -561,44 +560,44 @@ const getTagNamesForMode = (mode, context) => {
  * @returns {string[]|string}
  */
 const getTagDescription = (tg, returnArray) => {
-    /**
-     * @type {string[]}
-     */
-    const descriptions = [];
-    tg.source.some(({
-      tokens: {
-        end,
-        lineEnd,
-        postDelimiter,
-        tag,
-        postTag,
-        name,
-        type,
-        description,
-      },
-    }) => {
-      const desc = (
-        tag && postTag ||
+  /**
+   * @type {string[]}
+   */
+  const descriptions = [];
+  tg.source.some(({
+    tokens: {
+      description,
+      end,
+      lineEnd,
+      name,
+      postDelimiter,
+      postTag,
+      tag,
+      type,
+    },
+  }) => {
+    const desc = (
+      tag && postTag ||
         !tag && !name && !type && postDelimiter || ''
 
-      // Remove space
-      ).slice(1) +
+    // Remove space
+    ).slice(1) +
         (description || '') + (lineEnd || '');
 
-      if (end) {
-        if (desc) {
-          descriptions.push(desc);
-        }
-
-        return true;
+    if (end) {
+      if (desc) {
+        descriptions.push(desc);
       }
 
-      descriptions.push(desc);
+      return true;
+    }
 
-      return false;
-    });
+    descriptions.push(desc);
 
-    return returnArray ? descriptions : descriptions.join('\n');
+    return false;
+  });
+
+  return returnArray ? descriptions : descriptions.join('\n');
 };
 
 /**
@@ -621,10 +620,11 @@ const getPreferredTagNameSimple = (
   name,
   mode,
   tagPreference = {},
+  // eslint-disable-next-line unicorn/no-object-as-default-parameter -- Ok
   context = {
     report () {
       // No-op
-    }
+    },
   },
 ) => {
   const prefValues = Object.values(tagPreference);
@@ -748,13 +748,14 @@ const getTags = (jsdoc, tagName) => {
  * }}
  */
 const getPreferredTagName = (jsdoc, {
+  allowObjectReturn = false,
+  context,
   tagName,
-  context, mode,
-  tagNamePreference,
+  defaultMessage = `Unexpected tag \`@${tagName}\``,
+  mode,
   report = () => {},
   skipReportingBlockedTag = false,
-  allowObjectReturn = false,
-  defaultMessage = `Unexpected tag \`@${tagName}\``,
+  tagNamePreference,
 }) => {
   const ret = getPreferredTagNameSimple(tagName, mode, tagNamePreference, context);
   const isObject = ret && typeof ret === 'object';
@@ -793,16 +794,21 @@ const getPreferredTagName = (jsdoc, {
 const forEachPreferredTag = (
   jsdoc, tagName, arrayHandler,
   {
-    context, mode, report,
-    tagNamePreference,
+    context,
+    mode,
+    report,
     skipReportingBlockedTag = false,
-  } = {}
+    tagNamePreference,
+  } = {},
 ) => {
   const targetTagName = /** @type {string|false} */ (
     getPreferredTagName(jsdoc, {
+      context,
+      mode,
+      report,
       skipReportingBlockedTag,
       tagName,
-      context, mode, report, tagNamePreference
+      tagNamePreference,
     })
   );
   if (!targetTagName ||
@@ -985,8 +991,8 @@ const overrideTagStructure = (structuredTags, tagMap = tagStructure) => {
     tag,
     {
       name,
-      type,
       required = [],
+      type,
     },
   ] of Object.entries(structuredTags)) {
     const tagStruct = ensureMap(tagMap, tag);
@@ -1193,185 +1199,191 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
   }
 
   switch (node.type) {
-  case 'BlockStatement': {
-    return node.body.some((bodyNode) => {
-      return ![
-        'ArrowFunctionExpression',
-        'FunctionDeclaration',
-        'FunctionExpression',
-      ].includes(bodyNode.type) && hasNonFunctionYield(
-        bodyNode, checkYieldReturnValue,
-      );
-    });
-  }
+    case 'ArrayExpression':
 
-  /* c8 ignore next 2 -- In Babel? */
-  // @ts-expect-error In Babel?
-  case 'OptionalCallExpression':
-  case 'CallExpression':
-    return node.arguments.some((element) => {
-      return hasNonFunctionYield(element, checkYieldReturnValue);
-    });
-  case 'ChainExpression':
-  case 'ExpressionStatement': {
-    return hasNonFunctionYield(node.expression, checkYieldReturnValue);
-  }
+    case 'ArrayPattern':
+      return node.elements.some((element) => {
+        return hasNonFunctionYield(element, checkYieldReturnValue);
+      });
+    case 'AssignmentExpression':
+    case 'BinaryExpression':
+    case 'LogicalExpression': {
+      return hasNonFunctionYield(node.left, checkYieldReturnValue) ||
+      hasNonFunctionYield(node.right, checkYieldReturnValue);
+    }
 
-  case 'LabeledStatement':
-  case 'WhileStatement':
-  case 'DoWhileStatement':
-  case 'ForStatement':
-  case 'ForInStatement':
-  case 'ForOfStatement':
-  case 'WithStatement': {
-    return hasNonFunctionYield(node.body, checkYieldReturnValue);
-  }
+    case 'AssignmentPattern':
+      return hasNonFunctionYield(node.right, checkYieldReturnValue);
+    case 'BlockStatement': {
+      return node.body.some((bodyNode) => {
+        return ![
+          'ArrowFunctionExpression',
+          'FunctionDeclaration',
+          'FunctionExpression',
+        ].includes(bodyNode.type) && hasNonFunctionYield(
+          bodyNode, checkYieldReturnValue,
+        );
+      });
+    }
 
-  case 'ConditionalExpression':
-  case 'IfStatement': {
-    return hasNonFunctionYield(node.test, checkYieldReturnValue) ||
-      hasNonFunctionYield(node.consequent, checkYieldReturnValue) ||
-      hasNonFunctionYield(node.alternate, checkYieldReturnValue);
-  }
+    /* c8 ignore next 2 -- In Babel? */
+    case 'CallExpression':
+    // @ts-expect-error In Babel?
+    case 'OptionalCallExpression':
+      return node.arguments.some((element) => {
+        return hasNonFunctionYield(element, checkYieldReturnValue);
+      });
+    case 'ChainExpression':
+    case 'ExpressionStatement': {
+      return hasNonFunctionYield(node.expression, checkYieldReturnValue);
+    }
 
-  case 'TryStatement': {
-    return hasNonFunctionYield(node.block, checkYieldReturnValue) ||
-      hasNonFunctionYield(
-        node.handler && node.handler.body, checkYieldReturnValue,
-      ) ||
-      hasNonFunctionYield(
-        /** @type {import('@typescript-eslint/types').TSESTree.BlockStatement} */
-        (node.finalizer),
-        checkYieldReturnValue,
-      );
-  }
+    /* c8 ignore next 2 -- In Babel? */
+    // @ts-expect-error In Babel?
+    case 'ClassProperty':
 
-  case 'SwitchStatement': {
-    return node.cases.some(
-      (someCase) => {
-        return someCase.consequent.some((nde) => {
-          return hasNonFunctionYield(nde, checkYieldReturnValue);
-        });
-      },
-    );
-  }
+    /* c8 ignore next 2 -- In Babel? */
+      // @ts-expect-error In Babel?
+    case 'ObjectProperty':
+    /* c8 ignore next 2 -- In Babel? */
+    case 'Property':
 
-  case 'ArrayPattern':
-  case 'ArrayExpression':
-    return node.elements.some((element) => {
-      return hasNonFunctionYield(element, checkYieldReturnValue);
-    });
-  case 'AssignmentPattern':
-    return hasNonFunctionYield(node.right, checkYieldReturnValue);
+    case 'PropertyDefinition':
+      return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) ||
+      hasNonFunctionYield(node.value, checkYieldReturnValue);
 
-  case 'VariableDeclaration': {
-    return node.declarations.some((nde) => {
-      return hasNonFunctionYield(nde, checkYieldReturnValue);
-    });
-  }
+    case 'ConditionalExpression':
 
-  case 'VariableDeclarator': {
-    return hasNonFunctionYield(node.id, checkYieldReturnValue) ||
-      hasNonFunctionYield(node.init, checkYieldReturnValue);
-  }
+    case 'IfStatement': {
+      return hasNonFunctionYield(node.test, checkYieldReturnValue) ||
+      hasNonFunctionYield(node.consequent, checkYieldReturnValue) ||
+      hasNonFunctionYield(node.alternate, checkYieldReturnValue);
+    }
 
-  case 'AssignmentExpression':
-  case 'BinaryExpression':
-  case 'LogicalExpression': {
-    return hasNonFunctionYield(node.left, checkYieldReturnValue) ||
-      hasNonFunctionYield(node.right, checkYieldReturnValue);
-  }
+    case 'DoWhileStatement':
+    case 'ForInStatement':
 
-  // Comma
-  case 'SequenceExpression':
-  case 'TemplateLiteral':
-    return node.expressions.some((subExpression) => {
-      return hasNonFunctionYield(subExpression, checkYieldReturnValue);
-    });
+    case 'ForOfStatement':
 
-  case 'ObjectPattern':
-  case 'ObjectExpression':
-    return node.properties.some((property) => {
-      return hasNonFunctionYield(property, checkYieldReturnValue);
-    });
+    case 'ForStatement':
 
-  /* c8 ignore next -- In Babel? */
-  case 'PropertyDefinition':
-  /* eslint-disable no-fallthrough */
-  /* c8 ignore next 2 -- In Babel? */
-  // @ts-expect-error In Babel?
-  case 'ObjectProperty':
-  /* c8 ignore next 2 -- In Babel? */
-  // @ts-expect-error In Babel?
-  case 'ClassProperty':
-  case 'Property':
-  /* eslint-enable no-fallthrough */
-    return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) ||
-      hasNonFunctionYield(node.value, checkYieldReturnValue);
-  /* c8 ignore next 2 -- In Babel? */
-  // @ts-expect-error In Babel?
-  case 'ObjectMethod':
+    case 'LabeledStatement':
+    case 'WhileStatement':
+    case 'WithStatement': {
+      return hasNonFunctionYield(node.body, checkYieldReturnValue);
+    }
+
+    /* c8 ignore next 2 -- In Babel? */
+    // @ts-expect-error In Babel?
+    case 'Import':
+    case 'ImportExpression':
+      return hasNonFunctionYield(node.source, checkYieldReturnValue);
+
+    // ?.
+      /* c8 ignore next 2 -- In Babel? */
+    case 'MemberExpression':
+    // @ts-expect-error In Babel?
+    case 'OptionalMemberExpression':
+      return hasNonFunctionYield(node.object, checkYieldReturnValue) ||
+      hasNonFunctionYield(node.property, checkYieldReturnValue);
+
+    case 'ObjectExpression':
+    /* eslint-disable no-fallthrough */
+    case 'ObjectPattern':
+      /* eslint-enable no-fallthrough */
+      return node.properties.some((property) => {
+        return hasNonFunctionYield(property, checkYieldReturnValue);
+      });
+      /* c8 ignore next 2 -- In Babel? */
+      // @ts-expect-error In Babel?
+    case 'ObjectMethod':
     /* c8 ignore next 6 -- In Babel? */
     // @ts-expect-error In Babel?
-    return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) ||
+      return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) ||
       // @ts-expect-error In Babel?
       node.arguments.some((nde) => {
         return hasNonFunctionYield(nde, checkYieldReturnValue);
       });
+    case 'ReturnStatement': {
+      if (node.argument === null) {
+        return false;
+      }
 
-  case 'SpreadElement':
-  case 'UnaryExpression':
-    return hasNonFunctionYield(node.argument, checkYieldReturnValue);
+      return hasNonFunctionYield(node.argument, checkYieldReturnValue);
+    }
 
-  case 'TaggedTemplateExpression':
-    return hasNonFunctionYield(node.quasi, checkYieldReturnValue);
+    // Comma
+    case 'SequenceExpression':
 
-  // ?.
-  /* c8 ignore next 2 -- In Babel? */
-  // @ts-expect-error In Babel?
-  case 'OptionalMemberExpression':
-  case 'MemberExpression':
-    return hasNonFunctionYield(node.object, checkYieldReturnValue) ||
-      hasNonFunctionYield(node.property, checkYieldReturnValue);
+    case 'TemplateLiteral':
+      return node.expressions.some((subExpression) => {
+        return hasNonFunctionYield(subExpression, checkYieldReturnValue);
+      });
+    case 'SpreadElement':
 
-  /* c8 ignore next 2 -- In Babel? */
-  // @ts-expect-error In Babel?
-  case 'Import':
-  case 'ImportExpression':
-    return hasNonFunctionYield(node.source, checkYieldReturnValue);
+    case 'UnaryExpression':
+      return hasNonFunctionYield(node.argument, checkYieldReturnValue);
 
-  case 'ReturnStatement': {
-    if (node.argument === null) {
-      return false;
+    case 'SwitchStatement': {
+      return node.cases.some(
+        (someCase) => {
+          return someCase.consequent.some((nde) => {
+            return hasNonFunctionYield(nde, checkYieldReturnValue);
+          });
+        },
+      );
     }
 
-    return hasNonFunctionYield(node.argument, checkYieldReturnValue);
-  }
+    case 'TaggedTemplateExpression':
+      return hasNonFunctionYield(node.quasi, checkYieldReturnValue);
+
+    case 'TryStatement': {
+      return hasNonFunctionYield(node.block, checkYieldReturnValue) ||
+      hasNonFunctionYield(
+        node.handler && node.handler.body, checkYieldReturnValue,
+      ) ||
+      hasNonFunctionYield(
+        /** @type {import('@typescript-eslint/types').TSESTree.BlockStatement} */
+        (node.finalizer),
+        checkYieldReturnValue,
+      );
+    }
+
+    case 'VariableDeclaration': {
+      return node.declarations.some((nde) => {
+        return hasNonFunctionYield(nde, checkYieldReturnValue);
+      });
+    }
+
+    case 'VariableDeclarator': {
+      return hasNonFunctionYield(node.id, checkYieldReturnValue) ||
+      hasNonFunctionYield(node.init, checkYieldReturnValue);
+    }
 
-  case 'YieldExpression': {
-    if (checkYieldReturnValue) {
-      if (
+    case 'YieldExpression': {
+      if (checkYieldReturnValue) {
+        if (
         /** @type {import('eslint').Rule.Node} */ (
-          node
-        ).parent.type === 'VariableDeclarator'
-      ) {
-        return true;
+            node
+          ).parent.type === 'VariableDeclarator'
+        ) {
+          return true;
+        }
+
+        return false;
       }
 
-      return false;
+      // void return does not count.
+      if (node.argument === null) {
+        return false;
+      }
+
+      return true;
     }
 
-    // void return does not count.
-    if (node.argument === null) {
+    default: {
       return false;
     }
-
-    return true;
-  }
-
-  default: {
-    return false;
-  }
   }
 };
 
@@ -1411,55 +1423,55 @@ const hasThrowValue = (node, innerFunction) => {
   //   throws, but we're treating functions atomically rather than trying to
   //   follow them
   switch (node.type) {
-  case 'FunctionExpression':
-  case 'FunctionDeclaration':
-  case 'ArrowFunctionExpression': {
-    return !innerFunction && !node.async && hasThrowValue(node.body, true);
-  }
+    case 'ArrowFunctionExpression':
+    case 'FunctionDeclaration':
+    case 'FunctionExpression': {
+      return !innerFunction && !node.async && hasThrowValue(node.body, true);
+    }
 
-  case 'BlockStatement': {
-    return node.body.some((bodyNode) => {
-      return bodyNode.type !== 'FunctionDeclaration' && hasThrowValue(bodyNode);
-    });
-  }
+    case 'BlockStatement': {
+      return node.body.some((bodyNode) => {
+        return bodyNode.type !== 'FunctionDeclaration' && hasThrowValue(bodyNode);
+      });
+    }
 
-  case 'LabeledStatement':
-  case 'WhileStatement':
-  case 'DoWhileStatement':
-  case 'ForStatement':
-  case 'ForInStatement':
-  case 'ForOfStatement':
-  case 'WithStatement': {
-    return hasThrowValue(node.body);
-  }
+    case 'DoWhileStatement':
+    case 'ForInStatement':
+    case 'ForOfStatement':
+    case 'ForStatement':
+    case 'LabeledStatement':
+    case 'WhileStatement':
+    case 'WithStatement': {
+      return hasThrowValue(node.body);
+    }
 
-  case 'IfStatement': {
-    return hasThrowValue(node.consequent) || hasThrowValue(node.alternate);
-  }
+    case 'IfStatement': {
+      return hasThrowValue(node.consequent) || hasThrowValue(node.alternate);
+    }
 
-  // We only consider it to throw an error if the catch or finally blocks throw an error.
-  case 'TryStatement': {
-    return hasThrowValue(node.handler && node.handler.body) ||
-        hasThrowValue(node.finalizer);
-  }
+    case 'SwitchStatement': {
+      return node.cases.some(
+        (someCase) => {
+          return someCase.consequent.some((nde) => {
+            return hasThrowValue(nde);
+          });
+        },
+      );
+    }
 
-  case 'SwitchStatement': {
-    return node.cases.some(
-      (someCase) => {
-        return someCase.consequent.some((nde) => {
-          return hasThrowValue(nde);
-        });
-      },
-    );
-  }
+    case 'ThrowStatement': {
+      return true;
+    }
 
-  case 'ThrowStatement': {
-    return true;
-  }
+    // We only consider it to throw an error if the catch or finally blocks throw an error.
+    case 'TryStatement': {
+      return hasThrowValue(node.handler && node.handler.body) ||
+        hasThrowValue(node.finalizer);
+    }
 
-  default: {
-    return false;
-  }
+    default: {
+      return false;
+    }
   }
 };
 
@@ -1584,11 +1596,11 @@ const getContextObject = (contexts, checkJsdoc, handler) => {
 };
 
 const tagsWithNamesAndDescriptions = new Set([
-  'param', 'arg', 'argument', 'property', 'prop',
-  'template',
+  'arg', 'argument', 'param', 'prop', 'property',
+  'return',
 
   // These two are parsed by our custom parser as though having a `name`
-  'returns', 'return',
+  'returns', 'template',
 ]);
 
 /**
@@ -1685,9 +1697,9 @@ const isSetter = (node) => {
  */
 const hasAccessorPair = (node) => {
   const {
-    type,
-    kind: sourceKind,
     key,
+    kind: sourceKind,
+    type,
   } =
     /**
      * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
@@ -1712,8 +1724,8 @@ const hasAccessorPair = (node) => {
   return (
     sibling.some((child) => {
       const {
-        kind,
         key: ky,
+        kind,
       } = /**
            * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
            *   import('@typescript-eslint/types').TSESTree.Property}
@@ -1853,10 +1865,10 @@ export {
   getTagStructureForMode,
   hasATag,
   hasParams,
-  hasReturnValue,
+
   hasTag,
   hasThrowValue,
-  hasValueOrExecutorHasNonEmptyResolveValue,
+
   hasYieldValue,
   isConstructor,
   isGetter,
@@ -1878,3 +1890,7 @@ export {
   tagMustHaveNamePosition,
   tagMustHaveTypePosition,
 };
+export {
+  hasReturnValue,
+  hasValueOrExecutorHasNonEmptyResolveValue,
+} from './utils/hasReturnValue.js';