eslint-plugin-jsdoc 44.2.2 → 44.2.4

package/dist/jsdocUtils.js

@@ -10,24 +10,90 @@ var _getDefaultTagStructureForMode = _interopRequireDefault(require("./getDefaul
 var _tagNames = require("./tagNames");
 var _hasReturnValue = require("./utils/hasReturnValue");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-/* eslint-disable jsdoc/no-undefined-types */
-
 /**
- * @typedef {"jsdoc"|"typescript"|"closure"} ParserMode
+ * @typedef {number} Integer
+ */
+/**
+ * @typedef {import('./utils/hasReturnValue.js').ESTreeOrTypeScriptNode} ESTreeOrTypeScriptNode
  */
 
+/**
+ * @typedef {"jsdoc"|"typescript"|"closure"|"permissive"} ParserMode
+ */
+/**
+ * @type {import('./getDefaultTagStructureForMode.js').TagStructure}
+ */
 let tagStructure;
+
+/**
+ * @param {ParserMode} mode
+ * @returns {void}
+ */
 const setTagStructure = mode => {
   tagStructure = (0, _getDefaultTagStructureForMode.default)(mode);
 };
 
-// Given a nested array of property names, reduce them to a single array,
-// appending the name of the root element along the way if present.
+/**
+ * @typedef {{
+ *   hasPropertyRest: boolean,
+ *   hasRestElement: boolean,
+ *   names: string[],
+ *   rests: boolean[],
+ * }} FlattendRootInfo
+ */
+
+/**
+ * @typedef {undefined|string|{
+ *   isRestProperty: boolean|undefined,
+ *   name: string,
+ *   restElement: true
+ * }|[undefined|string, FlattendRootInfo & {
+ *   annotationParamName?: string
+ * }|{
+ *   name: Integer,
+ *   restElement: boolean
+ * }[]]} ParamNameInfo
+ */
+
+/**
+ * @typedef {undefined|string|{
+ *   isRestProperty: boolean,
+ *   restElement: boolean,
+ *   name: string
+ * }|[string, {
+ *   hasPropertyRest: boolean,
+ *   hasRestElement: boolean,
+ *   names: string[],
+ *   rests: boolean[],
+ * }]|[string, string[]]} ParamInfo
+ */
+
+/**
+ * Given a nested array of property names, reduce them to a single array,
+ *   appending the name of the root element along the way if present.
+ *
+ * @callback FlattenRoots
+ * @param {ParamInfo[]} params
+ * @param {string} [root]
+ * @returns {FlattendRootInfo}
+ */
+
+/** @type {FlattenRoots} */
 const flattenRoots = (params, root = '') => {
   let hasRestElement = false;
   let hasPropertyRest = false;
+
+  /**
+   * @type {boolean[]}
+   */
   const rests = [];
-  const names = params.reduce((acc, cur) => {
+  const names = params.reduce(
+  /**
+   * @param {string[]} acc
+   * @param {ParamInfo} cur
+   * @returns {string[]}
+   */
+  (acc, cur) => {
     if (Array.isArray(cur)) {
       let nms;
       if (Array.isArray(cur[1])) {
@@ -78,46 +144,68 @@ const flattenRoots = (params, root = '') => {
 };
 
 /**
- * @param {object} propSignature
- * @returns {undefined|Array|string}
+ * @param {import('@typescript-eslint/types').TSESTree.TSIndexSignature|
+ *  import('@typescript-eslint/types').TSESTree.TSConstructSignatureDeclaration|
+ *  import('@typescript-eslint/types').TSESTree.TSCallSignatureDeclaration|
+ *  import('@typescript-eslint/types').TSESTree.TSPropertySignature} propSignature
+ * @returns {undefined|string|[string, string[]]}
  */
 const getPropertiesFromPropertySignature = propSignature => {
   if (propSignature.type === 'TSIndexSignature' || propSignature.type === 'TSConstructSignatureDeclaration' || propSignature.type === 'TSCallSignatureDeclaration') {
     return undefined;
   }
   if (propSignature.typeAnnotation && propSignature.typeAnnotation.typeAnnotation.type === 'TSTypeLiteral') {
-    return [propSignature.key.name, propSignature.typeAnnotation.typeAnnotation.members.map(member => {
-      return getPropertiesFromPropertySignature(member);
+    return [/** @type {import('@typescript-eslint/types').TSESTree.Identifier} */propSignature.key.name, propSignature.typeAnnotation.typeAnnotation.members.map(member => {
+      return (/** @type {string} */
+        getPropertiesFromPropertySignature( /** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */
+        member)
+      );
     })];
   }
-  return propSignature.key.name;
+  return (/** @type {import('@typescript-eslint/types').TSESTree.Identifier} */propSignature.key.name
+  );
 };
 
 /**
- * @param {object} functionNode
- * @param {boolean} checkDefaultObjects
- * @returns {Array}
+ * @param {ESTreeOrTypeScriptNode|null} functionNode
+ * @param {boolean} [checkDefaultObjects]
+ * @throws {Error}
+ * @returns {ParamNameInfo[]}
  */
 const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
   var _functionNode$value;
-  // eslint-disable-next-line complexity
+  /* eslint-disable complexity -- Temporary */
+  /**
+   * @param {import('estree').Identifier|import('estree').AssignmentPattern|
+   *   import('estree').ObjectPattern|import('estree').Property|
+   *   import('estree').RestElement|import('estree').ArrayPattern|
+   *   import('@typescript-eslint/types').TSESTree.TSParameterProperty|
+   *   import('@typescript-eslint/types').TSESTree.Property|
+   *   import('@typescript-eslint/types').TSESTree.RestElement
+   * } param
+   * @param {boolean} [isProperty]
+   * @returns {ParamNameInfo}
+   */
   const getParamName = (param, isProperty) => {
-    var _param$left, _param$left3;
+    var _param$left2;
+    /* eslint-enable complexity -- Temporary */
     const hasLeftTypeAnnotation = 'left' in param && 'typeAnnotation' in param.left;
     if ('typeAnnotation' in param || hasLeftTypeAnnotation) {
       var _typeAnnotation$typeA;
-      const typeAnnotation = hasLeftTypeAnnotation ? param.left.typeAnnotation : param.typeAnnotation;
+      const typeAnnotation = hasLeftTypeAnnotation ? /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */param.left.typeAnnotation : /** @type {import('@typescript-eslint/types').TSESTree.Identifier|import('@typescript-eslint/types').TSESTree.ObjectPattern} */
+      param.typeAnnotation;
       if ((typeAnnotation === null || typeAnnotation === void 0 ? void 0 : (_typeAnnotation$typeA = typeAnnotation.typeAnnotation) === null || _typeAnnotation$typeA === void 0 ? void 0 : _typeAnnotation$typeA.type) === 'TSTypeLiteral') {
         const propertyNames = typeAnnotation.typeAnnotation.members.map(member => {
-          return getPropertiesFromPropertySignature(member);
+          return getPropertiesFromPropertySignature( /** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */
+          member);
         });
         const flattened = {
           ...flattenRoots(propertyNames),
-          annotationParamName: param.name
+          annotationParamName: 'name' in param ? param.name : undefined
         };
         const hasLeftName = 'left' in param && 'name' in param.left;
         if ('name' in param || hasLeftName) {
-          return [hasLeftName ? param.left.name : param.name, flattened];
+          return [hasLeftName ? /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */param.left.name : /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */param.name, flattened];
         }
         return [undefined, flattened];
       }
@@ -128,9 +216,9 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
     if ('left' in param && 'name' in param.left) {
       return param.left.name;
     }
-    if (param.type === 'ObjectPattern' || ((_param$left = param.left) === null || _param$left === void 0 ? void 0 : _param$left.type) === 'ObjectPattern') {
-      var _param$left2;
-      const properties = param.properties || ((_param$left2 = param.left) === null || _param$left2 === void 0 ? void 0 : _param$left2.properties);
+    if (param.type === 'ObjectPattern' || 'left' in param && param.left.type === 'ObjectPattern') {
+      var _param$left;
+      const properties = /** @type {import('@typescript-eslint/types').TSESTree.ObjectPattern} */param.properties || ( /** @type {import('estree').ObjectPattern} */(_param$left = /** @type {import('@typescript-eslint/types').TSESTree.AssignmentPattern} */param.left) === null || _param$left === void 0 ? void 0 : _param$left.properties);
       const roots = properties.map(prop => {
         return getParamName(prop, true);
       });
@@ -140,14 +228,14 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
       // eslint-disable-next-line default-case
       switch (param.value.type) {
         case 'ArrayPattern':
-          return [param.key.name, param.value.elements.map((prop, idx) => {
+          return [param.key.name, /** @type {import('estree').ArrayPattern} */param.value.elements.map((prop, idx) => {
             return {
               name: idx,
-              restElement: prop.type === 'RestElement'
+              restElement: (prop === null || prop === void 0 ? void 0 : prop.type) === 'RestElement'
             };
           })];
         case 'ObjectPattern':
-          return [param.key.name, param.value.properties.map(prop => {
+          return [param.key.name, /** @type {import('estree').ObjectPattern} */param.value.properties.map(prop => {
             return getParamName(prop, isProperty);
           })];
         case 'AssignmentPattern':
@@ -157,20 +245,20 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
               case 'Identifier':
                 // Default parameter
                 if (checkDefaultObjects && param.value.right.type === 'ObjectExpression') {
-                  return [param.key.name, param.value.right.properties.map(prop => {
+                  return [param.key.name, /** @type {import('estree').AssignmentPattern} */param.value.right.properties.map(prop => {
                     return getParamName(prop, isProperty);
                   })];
                 }
                 break;
               case 'ObjectPattern':
-                return [param.key.name, param.value.left.properties.map(prop => {
+                return [param.key.name, /** @type {import('estree').ObjectPattern} */param.value.left.properties.map(prop => {
                   return getParamName(prop, isProperty);
                 })];
               case 'ArrayPattern':
-                return [param.key.name, param.value.left.elements.map((prop, idx) => {
+                return [param.key.name, /** @type {import('estree').ArrayPattern} */param.value.left.elements.map((prop, idx) => {
                   return {
                     name: idx,
-                    restElement: prop.type === 'RestElement'
+                    restElement: (prop === null || prop === void 0 ? void 0 : prop.type) === 'RestElement'
                   };
                 })];
             }
@@ -195,9 +283,9 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
           return undefined;
       }
     }
-    if (param.type === 'ArrayPattern' || ((_param$left3 = param.left) === null || _param$left3 === void 0 ? void 0 : _param$left3.type) === 'ArrayPattern') {
-      var _param$left4;
-      const elements = param.elements || ((_param$left4 = param.left) === null || _param$left4 === void 0 ? void 0 : _param$left4.elements);
+    if (param.type === 'ArrayPattern' || ((_param$left2 = param.left) === null || _param$left2 === void 0 ? void 0 : _param$left2.type) === 'ArrayPattern') {
+      var _param$left3;
+      const elements = /** @type {import('estree').ArrayPattern} */param.elements || ( /** @type {import('estree').ArrayPattern} */(_param$left3 = param.left) === null || _param$left3 === void 0 ? void 0 : _param$left3.elements);
       const roots = elements.map((prop, idx) => {
         return {
           name: `"${idx}"`,
@@ -227,7 +315,7 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
 };
 
 /**
- * @param {Node} functionNode
+ * @param {ESTreeOrTypeScriptNode} functionNode
  * @returns {Integer}
  */
 const hasParams = functionNode => {
@@ -239,9 +327,13 @@ const hasParams = functionNode => {
  * Gets all names of the target type, including those that refer to a path, e.g.
  * "@param foo; @param foo.bar".
  *
- * @param {object} jsdoc
+ * @param {import('comment-parser').Block} jsdoc
  * @param {string} targetTagName
- * @returns {Array<object>}
+ * @returns {{
+ *   idx: Integer,
+ *   name: string,
+ *   type: string
+ * }[]}
  */
 const getJsdocTagsDeep = (jsdoc, targetTagName) => {
   const ret = [];
@@ -264,8 +356,9 @@ const getJsdocTagsDeep = (jsdoc, targetTagName) => {
 const modeWarnSettings = (0, _WarnSettings.default)();
 
 /**
- * @param {string} mode
- * @param context
+ * @param {ParserMode|undefined} mode
+ * @param {import('eslint').Rule.RuleContext} context
+ * @returns {import('./tagNames.js').AliasedTags}
  */
 const getTagNamesForMode = (mode, context) => {
   switch (mode) {
@@ -296,11 +389,14 @@ const getTagNamesForMode = (mode, context) => {
 };
 
 /**
- * @param context
- * @param {ParserMode} mode
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {ParserMode|undefined} mode
  * @param {string} name
- * @param {object} tagPreference
- * @returns {string|object}
+ * @param {TagNamePreference} tagPreference
+ * @returns {string|false|{
+ *   message: string;
+ *   replacement?: string|undefined;
+ * }}
  */
 const getPreferredTagName = (context, mode, name, tagPreference = {}) => {
   var _Object$entries$find;
@@ -319,7 +415,7 @@ const getPreferredTagName = (context, mode, name, tagPreference = {}) => {
   const tagPreferenceFixed = Object.fromEntries(Object.entries(tagPreference).map(([key, value]) => {
     return [key.replace(/^tag /u, ''), value];
   }));
-  if (Object.prototype.hasOwnProperty.call(tagPreferenceFixed, name)) {
+  if (Object.hasOwn(tagPreferenceFixed, name)) {
     return tagPreferenceFixed[name];
   }
   const tagNames = getTagNamesForMode(mode, context);
@@ -333,10 +429,10 @@ const getPreferredTagName = (context, mode, name, tagPreference = {}) => {
 };
 
 /**
- * @param context
- * @param {ParserMode} mode
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {ParserMode|undefined} mode
  * @param {string} name
- * @param {Array} definedTags
+ * @param {string[]} definedTags
  * @returns {boolean}
  */
 const isValidTag = (context, mode, name, definedTags) => {
@@ -348,7 +444,9 @@ const isValidTag = (context, mode, name, definedTags) => {
 };
 
 /**
- * @param {object} jsdoc
+ * @param {import('comment-parser').Block & {
+ *   inlineTags: import('@es-joy/jsdoccomment').InlineTag[]
+ * }} jsdoc
  * @param {string} targetTagName
  * @returns {boolean}
  */
@@ -362,18 +460,69 @@ const hasTag = (jsdoc, targetTagName) => {
 /**
  * Get all tags, inline tags and inline tags in tags
  *
- * @param {object} jsdoc
- * @returns {Array}
+ * @param {import('comment-parser').Block & {
+ *   inlineTags: import('@es-joy/jsdoccomment').JsdocInlineTagNoType[]
+ * }} jsdoc
+ * @returns {(import('comment-parser').Spec|
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
  */
-const getAllTags = (jsdoc, includeInlineTags) => {
-  return includeInlineTags ? [...jsdoc.tags, ...jsdoc.inlineTags, ...jsdoc.tags.flatMap(tag => {
-    return tag.inlineTags;
-  })] : jsdoc.tags;
+const getAllTags = jsdoc => {
+  return [...jsdoc.tags, ...jsdoc.inlineTags.map(inlineTag => {
+    // Tags don't have source or line numbers, so add before returning
+    let line = -1;
+    for (const {
+      tokens: {
+        description
+      }
+    } of jsdoc.source) {
+      line++;
+      if (description && description.includes(`{@${inlineTag.tag}`)) {
+        break;
+      }
+    }
+    inlineTag.line = line;
+    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) {
+      let line;
+      for (const {
+        number,
+        tokens: {
+          description
+        }
+      } of tag.source) {
+        if (description && description.includes(`{@${inlineTag.tag}`)) {
+          line = number;
+          break;
+        }
+      }
+      inlineTag.line = tagBegins + line - 1;
+    }
+    return (
+      /**
+       * @type {import('comment-parser').Spec & {
+       *   inlineTags: import('@es-joy/jsdoccomment').JsdocInlineTagNoType[]
+       * }}
+       */
+      tag.inlineTags
+    );
+  })];
 };
 
 /**
- * @param {object} jsdoc
- * @param {Array} targetTagNames
+ * @param {import('comment-parser').Block} jsdoc
+ * @param {string[]} targetTagNames
  * @returns {boolean}
  */
 const hasATag = (jsdoc, targetTagNames) => {
@@ -385,9 +534,9 @@ const hasATag = (jsdoc, targetTagNames) => {
 /**
  * Checks if the JSDoc comment has an undefined type.
  *
- * @param {JsDocTag} tag
+ * @param {import('comment-parser').Spec|null|undefined} tag
  *   the tag which should be checked.
- * @param {"jsdoc"|"closure"|"typescript"} mode
+ * @param {ParserMode} mode
  * @returns {boolean}
  *   true in case a defined type is undeclared; otherwise false.
  */
@@ -423,20 +572,22 @@ const mayBeUndefinedTypeTag = (tag, mode) => {
 };
 
 /**
- * @param map
- * @param tag
- * @returns {Map}
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} map
+ * @param {string} tag
+ * @returns {Map<string, string|string[]|boolean|undefined>}
  */
 const ensureMap = (map, tag) => {
   if (!map.has(tag)) {
     map.set(tag, new Map());
   }
-  return map.get(tag);
+  return (/** @type {Map<string, string | boolean>} */map.get(tag)
+  );
 };
 
 /**
- * @param structuredTags
- * @param tagMap
+ * @param {import('./iterateJsdoc.js').StructuredTags} structuredTags
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+ * @returns {void}
  */
 const overrideTagStructure = (structuredTags, tagMap = tagStructure) => {
   for (const [tag, {
@@ -469,9 +620,9 @@ const overrideTagStructure = (structuredTags, tagMap = tagStructure) => {
 };
 
 /**
- * @param mode
- * @param structuredTags
- * @returns {Map}
+ * @param {ParserMode} mode
+ * @param {import('./iterateJsdoc.js').StructuredTags} structuredTags
+ * @returns {import('./getDefaultTagStructureForMode.js').TagStructure}
  */
 const getTagStructureForMode = (mode, structuredTags) => {
   const tagStruct = (0, _getDefaultTagStructureForMode.default)(mode);
@@ -484,8 +635,8 @@ const getTagStructureForMode = (mode, structuredTags) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const isNamepathDefiningTag = (tag, tagMap = tagStructure) => {
@@ -494,8 +645,8 @@ const isNamepathDefiningTag = (tag, tagMap = tagStructure) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const isNamepathReferencingTag = (tag, tagMap = tagStructure) => {
@@ -504,8 +655,8 @@ const isNamepathReferencingTag = (tag, tagMap = tagStructure) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const isNamepathOrUrlReferencingTag = (tag, tagMap = tagStructure) => {
@@ -514,19 +665,20 @@ const isNamepathOrUrlReferencingTag = (tag, tagMap = tagStructure) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
- * @returns {boolean}
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+ * @returns {boolean|undefined}
  */
 const tagMustHaveTypePosition = (tag, tagMap = tagStructure) => {
   const tagStruct = ensureMap(tagMap, tag);
-  return tagStruct.get('typeRequired');
+  return (/** @type {boolean|undefined} */tagStruct.get('typeRequired')
+  );
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
- * @returns {boolean}
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+ * @returns {boolean|string}
  */
 const tagMightHaveTypePosition = (tag, tagMap = tagStructure) => {
   if (tagMustHaveTypePosition(tag, tagMap)) {
@@ -539,8 +691,8 @@ const tagMightHaveTypePosition = (tag, tagMap = tagStructure) => {
 const namepathTypes = new Set(['namepath-defining', 'namepath-referencing']);
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const tagMightHaveNamePosition = (tag, tagMap = tagStructure) => {
@@ -550,8 +702,8 @@ const tagMightHaveNamePosition = (tag, tagMap = tagStructure) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const tagMightHaveNamepath = (tag, tagMap = tagStructure) => {
@@ -560,38 +712,40 @@ const tagMightHaveNamepath = (tag, tagMap = tagStructure) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
- * @returns {boolean}
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+ * @returns {boolean|undefined}
  */
 const tagMustHaveNamePosition = (tag, tagMap = tagStructure) => {
   const tagStruct = ensureMap(tagMap, tag);
-  return tagStruct.get('nameRequired');
+  return (/** @type {boolean|undefined} */tagStruct.get('nameRequired')
+  );
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const tagMightHaveEitherTypeOrNamePosition = (tag, tagMap) => {
-  return tagMightHaveTypePosition(tag, tagMap) || tagMightHaveNamepath(tag, tagMap);
+  return Boolean(tagMightHaveTypePosition(tag, tagMap)) || tagMightHaveNamepath(tag, tagMap);
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
- * @returns {boolean}
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+ * @returns {boolean|undefined}
  */
 const tagMustHaveEitherTypeOrNamePosition = (tag, tagMap) => {
   const tagStruct = ensureMap(tagMap, tag);
-  return tagStruct.get('typeOrNameRequired');
+  return (/** @type {boolean} */tagStruct.get('typeOrNameRequired')
+  );
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
- * @returns {boolean}
+ * @param {import('comment-parser').Spec} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+ * @returns {boolean|undefined}
  */
 const tagMissingRequiredTypeOrNamepath = (tag, tagMap = tagStructure) => {
   const mustHaveTypePosition = tagMustHaveTypePosition(tag.tag, tagMap);
@@ -603,8 +757,14 @@ const tagMissingRequiredTypeOrNamepath = (tag, tagMap = tagStructure) => {
   return mustHaveEither && !hasEither && !mustHaveTypePosition;
 };
 
-// eslint-disable-next-line complexity
+/* eslint-disable complexity -- Temporary */
+/**
+ * @param {ESTreeOrTypeScriptNode} node
+ * @param {boolean} [checkYieldReturnValue]
+ * @returns {boolean}
+ */
 const hasNonFunctionYield = (node, checkYieldReturnValue) => {
+  /* eslint-enable complexity -- Temporary */
   if (!node) {
     return false;
   }
@@ -616,6 +776,7 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
         });
       }
 
+    // @ts-expect-error In Babel?
     // istanbul ignore next -- In Babel?
     case 'OptionalCallExpression':
     case 'CallExpression':
@@ -693,13 +854,16 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
     // istanbul ignore next -- In Babel?
     case 'PropertyDefinition':
     /* eslint-disable no-fallthrough */
+    // @ts-expect-error In Babel?
     // istanbul ignore next -- In Babel?
     case 'ObjectProperty':
+    // @ts-expect-error In Babel?
     // istanbul ignore next -- In Babel?
     case 'ClassProperty':
     case 'Property':
       /* eslint-enable no-fallthrough */
       return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) || hasNonFunctionYield(node.value, checkYieldReturnValue);
+    // @ts-expect-error In Babel?
     // istanbul ignore next -- In Babel?
     case 'ObjectMethod':
       // istanbul ignore next -- In Babel?
@@ -712,12 +876,14 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
     case 'TaggedTemplateExpression':
       return hasNonFunctionYield(node.quasi, checkYieldReturnValue);
 
+    // @ts-expect-error In Babel?
     // ?.
     // istanbul ignore next -- In Babel?
     case 'OptionalMemberExpression':
     case 'MemberExpression':
       return hasNonFunctionYield(node.object, checkYieldReturnValue) || hasNonFunctionYield(node.property, checkYieldReturnValue);
 
+    // @ts-expect-error In Babel?
     // istanbul ignore next -- In Babel?
     case 'Import':
     case 'ImportExpression':
@@ -754,7 +920,8 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
 /**
  * Checks if a node has a return statement. Void return does not count.
  *
- * @param {object} node
+ * @param {ESTreeOrTypeScriptNode} node
+ * @param {boolean} [checkYieldReturnValue]
  * @returns {boolean}
  */
 const hasYieldValue = (node, checkYieldReturnValue) => {
@@ -764,8 +931,8 @@ const hasYieldValue = (node, checkYieldReturnValue) => {
 /**
  * Checks if a node has a throws statement.
  *
- * @param {object} node
- * @param {boolean} innerFunction
+ * @param {ESTreeOrTypeScriptNode|null|undefined} node
+ * @param {boolean} [innerFunction]
  * @returns {boolean}
  */
 // eslint-disable-next-line complexity
@@ -843,8 +1010,8 @@ const isInlineTag = (tag) => {
  *
  * @see {https://github.com/google/closure-compiler/wiki/Generic-Types}
  * @see {https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template}
- * @param {JsDocTag} tag
- * @returns {Array<string>}
+ * @param {import('comment-parser').Spec} tag
+ * @returns {string[]}
  */
 const parseClosureTemplateTag = tag => {
   return tag.name.split(',').map(type => {
@@ -861,9 +1028,11 @@ const parseClosureTemplateTag = tag => {
  *   contexts designated by the rule. Returns an array of
  *   ESTree AST types, indicating allowable contexts.
  *
- * @param {*} context
- * @param {DefaultContexts} defaultContexts
- * @param settings
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {DefaultContexts|undefined} defaultContexts
+ * @param {{
+ *   contexts?: import('./iterateJsdoc.js').Context[]
+ * }} settings
  * @returns {string[]}
  */
 const enforcedContexts = (context, defaultContexts, settings) => {
@@ -873,11 +1042,13 @@ const enforcedContexts = (context, defaultContexts, settings) => {
 };
 
 /**
- * @param {string[]} contexts
- * @param {Function} checkJsdoc
- * @param {Function} handler
+ * @param {import('./iterateJsdoc.js').Context[]} contexts
+ * @param {import('./iterateJsdoc.js').CheckJsdoc} checkJsdoc
+ * @param {Function} [handler]
+ * @returns {import('eslint').Rule.RuleListener}
  */
 const getContextObject = (contexts, checkJsdoc, handler) => {
+  /** @type {import('eslint').Rule.RuleListener} */
   const properties = {};
   for (const [idx, prop] of contexts.entries()) {
     let property;
@@ -913,18 +1084,36 @@ const getContextObject = (contexts, checkJsdoc, handler) => {
   }
   return properties;
 };
-const filterTags = (tags, filter) => {
-  return tags.filter(tag => {
-    return filter(tag);
-  });
-};
 const tagsWithNamesAndDescriptions = new Set(['param', 'arg', 'argument', 'property', 'prop', 'template',
 // These two are parsed by our custom parser as though having a `name`
 'returns', 'return']);
+
+/* eslint-disable jsdoc/valid-types -- Old version */
+/**
+ * @typedef {{
+ *   [key: string]: false|
+ *     {message: string, replacement?: string}
+ * }} TagNamePreference
+ */
+/* eslint-enable jsdoc/valid-types -- Old version */
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {ParserMode|undefined} mode
+ * @param {import('comment-parser').Spec[]} tags
+ * @param {TagNamePreference} tagPreference
+ * @returns {{
+ *   tagsWithNames: import('comment-parser').Spec[],
+ *   tagsWithoutNames: import('comment-parser').Spec[]
+ * }}
+ */
 const getTagsByType = (context, mode, tags, tagPreference) => {
   const descName = getPreferredTagName(context, mode, 'description', tagPreference);
+  /**
+   * @type {import('comment-parser').Spec[]}
+   */
   const tagsWithoutNames = [];
-  const tagsWithNames = filterTags(tags, tag => {
+  const tagsWithNames = tags.filter(tag => {
     const {
       tag: tagName
     } = tag;
@@ -939,42 +1128,100 @@ const getTagsByType = (context, mode, tags, tagPreference) => {
     tagsWithoutNames
   };
 };
+
+/**
+ * @param {import('eslint').SourceCode|{
+ *   text: string
+ * }} sourceCode
+ * @returns {string}
+ */
 const getIndent = sourceCode => {
   var _sourceCode$text$matc;
   return (((_sourceCode$text$matc = sourceCode.text.match(/^\n*([ \t]+)/u)) === null || _sourceCode$text$matc === void 0 ? void 0 : _sourceCode$text$matc[1]) ?? '') + ' ';
 };
+
+/**
+ * @param {import('eslint').Rule.Node|null} node
+ * @returns {boolean}
+ */
 const isConstructor = node => {
   var _node$parent;
-  return (node === null || node === void 0 ? void 0 : node.type) === 'MethodDefinition' && node.kind === 'constructor' || (node === null || node === void 0 ? void 0 : (_node$parent = node.parent) === null || _node$parent === void 0 ? void 0 : _node$parent.kind) === 'constructor';
+  return (node === null || node === void 0 ? void 0 : node.type) === 'MethodDefinition' && node.kind === 'constructor' || /** @type {import('@typescript-eslint/types').TSESTree.MethodDefinition} */(node === null || node === void 0 ? void 0 : (_node$parent = node.parent) === null || _node$parent === void 0 ? void 0 : _node$parent.kind) === 'constructor';
 };
+
+/**
+ * @param {import('eslint').Rule.Node|null} node
+ * @returns {boolean}
+ */
 const isGetter = node => {
   var _node$parent2;
-  return node && ((_node$parent2 = node.parent) === null || _node$parent2 === void 0 ? void 0 : _node$parent2.kind) === 'get';
+  return node !== null &&
+  /**
+   * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
+   *   import('@typescript-eslint/types').TSESTree.Property}
+   */
+  ((_node$parent2 = node.parent) === null || _node$parent2 === void 0 ? void 0 : _node$parent2.kind) === 'get';
 };
+
+/**
+ * @param {import('eslint').Rule.Node|null} node
+ * @returns {boolean}
+ */
 const isSetter = node => {
   var _node$parent3;
-  return node && ((_node$parent3 = node.parent) === null || _node$parent3 === void 0 ? void 0 : _node$parent3.kind) === 'set';
+  return node !== null &&
+  /**
+   * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
+   *   import('@typescript-eslint/types').TSESTree.Property}
+   */
+  ((_node$parent3 = node.parent) === null || _node$parent3 === void 0 ? void 0 : _node$parent3.kind) === 'set';
 };
+
+/**
+ * @param {import('eslint').Rule.Node} node
+ * @returns {boolean}
+ */
 const hasAccessorPair = node => {
   const {
     type,
     kind: sourceKind,
-    key: {
-      name: sourceName
-    }
-  } = node;
+    key
+  } =
+  /**
+   * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
+   *   import('@typescript-eslint/types').TSESTree.Property}
+   */
+  node;
+  const sourceName = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */key.name;
   const oppositeKind = sourceKind === 'get' ? 'set' : 'get';
-  const children = type === 'MethodDefinition' ? 'body' : 'properties';
-  return node.parent[children].some(({
-    kind,
-    key: {
-      name
-    }
-  }) => {
+  const sibling = type === 'MethodDefinition' ? /** @type {import('@typescript-eslint/types').TSESTree.ClassBody} */node.parent.body : /** @type {import('@typescript-eslint/types').TSESTree.ObjectExpression} */node.parent.properties;
+  return sibling.some(child => {
+    const {
+      kind,
+      key: ky
+    } =
+    /**
+     * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
+     *   import('@typescript-eslint/types').TSESTree.Property}
+     */
+    child;
+    const name = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ky.name;
     return kind === oppositeKind && name === sourceName;
   });
 };
+
+/**
+ * @param {import('comment-parser').Block} jsdoc
+ * @param {import('eslint').Rule.Node|null} node
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {import('json-schema').JSONSchema4} schema
+ * @returns {boolean}
+ */
 const exemptSpeciaMethods = (jsdoc, node, context, schema) => {
+  /**
+   * @param {"checkGetters"|"checkSetters"|"checkConstructors"} prop
+   * @returns {boolean|"no-setter"|"no-getter"}
+   */
   const hasSchemaOption = prop => {
     var _context$options$2;
     const schemaProperties = schema[0].properties;
@@ -982,7 +1229,7 @@ const exemptSpeciaMethods = (jsdoc, node, context, schema) => {
   };
   const checkGetters = hasSchemaOption('checkGetters');
   const checkSetters = hasSchemaOption('checkSetters');
-  return !hasSchemaOption('checkConstructors') && (isConstructor(node) || hasATag(jsdoc, ['class', 'constructor'])) || isGetter(node) && (!checkGetters || checkGetters === 'no-setter' && hasAccessorPair(node.parent)) || isSetter(node) && (!checkSetters || checkSetters === 'no-getter' && hasAccessorPair(node.parent));
+  return !hasSchemaOption('checkConstructors') && (isConstructor(node) || hasATag(jsdoc, ['class', 'constructor'])) || isGetter(node) && (!checkGetters || checkGetters === 'no-setter' && hasAccessorPair( /** @type {import('./iterateJsdoc.js').Node} */node.parent)) || isSetter(node) && (!checkSetters || checkSetters === 'no-getter' && hasAccessorPair( /** @type {import('./iterateJsdoc.js').Node} */node.parent));
 };
 
 /**
@@ -1009,17 +1256,20 @@ const comparePaths = name => {
 };
 
 /**
+ * @callback PathDoesNotBeginWith
  * @param {string} name
  * @param {string} otherPathName
  * @returns {boolean}
  */
+
+/** @type {PathDoesNotBeginWith} */
 const pathDoesNotBeginWith = (name, otherPathName) => {
   return !name.startsWith(otherPathName) && !dropPathSegmentQuotes(name).startsWith(dropPathSegmentQuotes(otherPathName));
 };
 
 /**
  * @param {string} regexString
- * @param {string} requiredFlags
+ * @param {string} [requiredFlags]
  * @returns {RegExp}
  */
 const getRegexFromString = (regexString, requiredFlags) => {
@@ -1041,7 +1291,6 @@ var _default = {
   dropPathSegmentQuotes,
   enforcedContexts,
   exemptSpeciaMethods,
-  filterTags,
   flattenRoots,
   getAllTags,
   getContextObject,