eslint-plugin-jsdoc 44.2.2 → 44.2.4

package/dist/iterateJsdoc.js

@@ -15,6 +15,531 @@ var _jsdoccomment = require("@es-joy/jsdoccomment");
 var _commentParser = require("comment-parser");
 var _jsdocUtils = _interopRequireDefault(require("./jsdocUtils"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+/**
+ * @typedef {number} Integer
+ */
+
+/**
+ * @typedef {{
+ *   disallowName?: string,
+ *   allowName?: string,
+ *   context?: string,
+ *   comment?: string,
+ *   tags?: string[],
+ *   replacement?: string,
+ *   minimum?: Integer,
+ *   message?: string
+ * }} ContextObject
+ */
+/**
+ * @typedef {string|ContextObject} Context
+ */
+
+/**
+ * @callback CheckJsdoc
+ * @param {{
+ *   lastIndex?: Integer,
+ *   isFunctionContext?: boolean,
+ *   selector?: string
+ * }} info
+ * @param {null|((jsdoc: import('comment-parser').Block) => boolean|undefined)} handler
+ * @param {import('eslint').Rule.Node} node
+ * @returns {void}
+ */
+
+/**
+ * @callback ForEachPreferredTag
+ * @param {string} tagName
+ * @param {(
+ *   matchingJsdocTag: import('comment-parser').Spec & {
+ *     line: Integer
+ *   },
+ *   targetTagName: string
+ * ) => void} arrayHandler
+ * @param {boolean} [skipReportingBlockedTag]
+ * @returns {void}
+ */
+
+/**
+ * @callback ReportSettings
+ * @param {string} message
+ * @returns {void}
+ */
+
+/**
+ * @callback ParseClosureTemplateTag
+ * @param {import('comment-parser').Spec} tag
+ * @returns {string[]}
+ */
+
+/**
+ * @callback GetPreferredTagNameObject
+ * @param {{
+ *   tagName: string
+ * }} cfg
+ * @returns {string|false|{
+ *   message: string;
+ *   replacement?: string|undefined
+ * }|{
+ *   blocked: true,
+ *   tagName: string
+ * }}
+ */
+
+/**
+ * @typedef {{
+ *   forEachPreferredTag: ForEachPreferredTag,
+ *   reportSettings: ReportSettings,
+ *   parseClosureTemplateTag: ParseClosureTemplateTag,
+ *   getPreferredTagNameObject: GetPreferredTagNameObject,
+ *   pathDoesNotBeginWith: import('./jsdocUtils.js').PathDoesNotBeginWith
+ * }} BasicUtils
+ */
+
+/**
+ * @callback IsIteratingFunction
+ * @returns {boolean}
+ */
+
+/**
+ * @callback IsVirtualFunction
+ * @returns {boolean}
+ */
+
+/**
+ * @callback Stringify
+ * @param {import('comment-parser').Block} tagBlock
+ * @param {boolean} [specRewire]
+ * @returns {string}
+ */
+
+/* eslint-disable jsdoc/valid-types -- Old version */
+/**
+ * @callback ReportJSDoc
+ * @param {string} msg
+ * @param {null|import('comment-parser').Spec|{line: Integer, column?: Integer}} [tag]
+ * @param {(() => void)|null} [handler]
+ * @param {boolean} [specRewire]
+ * @param {undefined|{
+ *   [key: string]: string
+ * }} [data]
+ */
+/* eslint-enable jsdoc/valid-types -- Old version */
+
+/**
+ * @callback GetRegexFromString
+ * @param {string} str
+ * @param {string} [requiredFlags]
+ * @returns {RegExp}
+ */
+
+/**
+ * @callback GetTagDescription
+ * @param {import('comment-parser').Spec} tg
+ * @param {boolean} [returnArray]
+ * @returns {string[]|string}
+ */
+
+/**
+ * @callback SetTagDescription
+ * @param {import('comment-parser').Spec} tg
+ * @param {RegExp} matcher
+ * @param {(description: string) => string} setter
+ * @returns {Integer}
+ */
+
+/**
+ * @callback GetDescription
+ * @returns {{
+ *   description: string,
+ *   descriptions: string[],
+ *   lastDescriptionLine: Integer
+ * }}
+ */
+
+/* eslint-disable jsdoc/no-undefined-types -- Bug */
+/**
+ * @callback SetBlockDescription
+ * @param {(
+ *   info: {
+ *     delimiter: string,
+ *     postDelimiter: string,
+ *     start: string
+ *   },
+ *   seedTokens: (
+ *     tokens?: Partial<import('comment-parser').Tokens>
+ *   ) => import('comment-parser').Tokens,
+ *   descLines: string[]
+ * ) => import('comment-parser').Line[]} setter
+ * @returns {void}
+ */
+/* eslint-enable jsdoc/no-undefined-types -- Bug */
+
+/**
+ * @callback SetDescriptionLines
+ * @param {RegExp} matcher
+ * @param {(description: string) => string} setter
+ * @returns {Integer}
+ */
+
+/* eslint-disable jsdoc/no-undefined-types -- TS */
+/**
+ * @callback ChangeTag
+ * @param {import('comment-parser').Spec} tag
+ * @param {...Partial<import('comment-parser').Tokens>} tokens
+ * @returns {void}
+ */
+/* eslint-enable jsdoc/no-undefined-types -- TS */
+
+/* eslint-disable jsdoc/no-undefined-types -- TS */
+/**
+ * @callback SetTag
+ * @param {import('comment-parser').Spec & {
+ *   line: Integer
+ * }} tag
+ * @param {Partial<import('comment-parser').Tokens>} [tokens]
+ * @returns {void}
+ */
+/* eslint-enable jsdoc/no-undefined-types -- TS */
+
+/**
+ * @callback RemoveTag
+ * @param {Integer} tagIndex
+ * @param {{
+ *   removeEmptyBlock?: boolean,
+ *   tagSourceOffset?: Integer
+ * }} [cfg]
+ * @returns {void}
+ */
+
+/**
+ * @callback AddTag
+ * @param {string} targetTagName
+ * @param {Integer} [number]
+ * @param {import('comment-parser').Tokens|{}} [tokens]
+ * @returns {void}
+ */
+
+/**
+ * @callback GetFirstLine
+ * @returns {Integer|undefined}
+ */
+
+/* eslint-disable jsdoc/no-undefined-types -- TS */
+/**
+ * @typedef {(
+ *   tokens?: Partial<import('comment-parser').Tokens> | undefined
+ * ) => import('comment-parser').Tokens} SeedTokens
+ */
+/* eslint-enable jsdoc/no-undefined-types -- TS */
+
+/**
+ * Sets tokens to empty string.
+ *
+ * @callback EmptyTokens
+ * @param {import('comment-parser').Tokens} tokens
+ * @returns {void}
+ */
+
+/* eslint-disable jsdoc/no-undefined-types -- TS */
+/**
+ * @callback AddLine
+ * @param {Integer} sourceIndex
+ * @param {Partial<import('comment-parser').Tokens>} tokens
+ * @returns {void}
+ */
+/* eslint-enable jsdoc/no-undefined-types -- TS */
+
+/**
+ * @callback AddLines
+ * @param {Integer} tagIndex
+ * @param {Integer} tagSourceOffset
+ * @param {Integer} numLines
+ * @returns {void}
+ */
+
+/**
+ * @callback MakeMultiline
+ * @returns {void}
+ */
+
+/**
+ * @callback GetFunctionParameterNames
+ * @param {boolean} [useDefaultObjectProperties]
+ * @returns {import('./jsdocUtils.js').ParamNameInfo[]}
+ */
+
+/**
+ * @callback HasParams
+ * @returns {Integer}
+ */
+
+/**
+ * @callback IsGenerator
+ * @returns {boolean}
+ */
+
+/**
+ * @callback IsConstructor
+ * @returns {boolean}
+ */
+
+/**
+ * @callback GetJsdocTagsDeep
+ * @param {string} tagName
+ * @returns {false|{
+ *   idx: Integer,
+ *   name: string,
+ *   type: string
+ * }[]}
+ */
+
+/**
+ * @callback GetPreferredTagName
+ * @param {{
+ *   tagName: string,
+ *   skipReportingBlockedTag?: boolean,
+ *   allowObjectReturn?: boolean,
+ *   defaultMessage?: string
+ * }} cfg
+ * @returns {string|undefined|false|{
+ *   message: string;
+ *   replacement?: string|undefined;
+ * }|{
+ *   blocked: true,
+ *   tagName: string
+ * }}
+ */
+
+/**
+ * @callback IsValidTag
+ * @param {string} name
+ * @param {string[]} definedTags
+ * @returns {boolean}
+ */
+
+/**
+ * @callback HasATag
+ * @param {string[]} names
+ * @returns {boolean}
+ */
+
+/**
+ * @callback HasTag
+ * @param {string} name
+ * @returns {boolean}
+ */
+
+/**
+ * @callback ComparePaths
+ * @param {string} name
+ * @returns {(otherPathName: string) => void}
+ */
+
+/**
+ * @callback DropPathSegmentQuotes
+ * @param {string} name
+ * @returns {string}
+ */
+
+/**
+ * @callback AvoidDocs
+ * @returns {boolean}
+ */
+
+/**
+ * @callback TagMightHaveNamePositionTypePosition
+ * @param {string} tagName
+ * @param {import('./getDefaultTagStructureForMode.js').
+ *   TagStructure[]} [otherModeMaps]
+ * @returns {boolean|{otherMode: true}}
+ */
+
+/**
+ * @callback TagMustHave
+ * @param {string} tagName
+ * @param {import('./getDefaultTagStructureForMode.js').
+ *   TagStructure[]} otherModeMaps
+ * @returns {boolean|{
+ *   otherMode: false
+ * }}
+ */
+
+/**
+ * @callback TagMissingRequiredTypeOrNamepath
+ * @param {import('comment-parser').Spec} tag
+ * @param {import('./getDefaultTagStructureForMode.js').
+ *   TagStructure[]} otherModeMaps
+ * @returns {boolean|{
+ *   otherMode: false
+ * }}
+ */
+
+/**
+ * @callback IsNamepathX
+ * @param {string} tagName
+ * @returns {boolean}
+ */
+
+/**
+ * @callback GetTagStructureForMode
+ * @param {import('./jsdocUtils.js').ParserMode} mde
+ * @returns {import('./getDefaultTagStructureForMode.js').TagStructure}
+ */
+
+/**
+ * @callback MayBeUndefinedTypeTag
+ * @param {import('comment-parser').Spec} tag
+ * @returns {boolean}
+ */
+
+/**
+ * @callback HasValueOrExecutorHasNonEmptyResolveValue
+ * @param {boolean} anyPromiseAsReturn
+ * @param {boolean} [allBranches]
+ * @returns {boolean}
+ */
+
+/**
+ * @callback HasYieldValue
+ * @returns {boolean}
+ */
+
+/**
+ * @callback HasYieldReturnValue
+ * @returns {boolean}
+ */
+
+/**
+ * @callback HasThrowValue
+ * @returns {boolean}
+ */
+
+/**
+ * @callback IsAsync
+ * @returns {boolean|undefined}
+ */
+
+/**
+ * @callback GetTags
+ * @param {string} tagName
+ * @returns {import('comment-parser').Spec[]}
+ */
+
+/**
+ * @callback GetPresentTags
+ * @param {string[]} tagList
+ * @returns {import('comment-parser').Spec[]}
+ */
+
+/**
+ * @callback FilterTags
+ * @param {(tag: import('comment-parser').Spec) => boolean} filter
+ * @returns {import('comment-parser').Spec[]}
+ */
+
+/**
+ * @callback FilterAllTags
+ * @param {(tag: (import('comment-parser').Spec|
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)) => boolean} filter
+ * @returns {(import('comment-parser').Spec|
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
+ */
+
+/**
+ * @callback GetTagsByType
+ * @param {import('comment-parser').Spec[]} tags
+ * @returns {{
+ *   tagsWithNames: import('comment-parser').Spec[],
+ *   tagsWithoutNames: import('comment-parser').Spec[]
+ * }}
+ */
+
+/**
+ * @callback HasOptionTag
+ * @param {string} tagName
+ * @returns {boolean}
+ */
+
+/**
+ * @callback GetClassNode
+ * @returns {Node|null}
+ */
+
+/**
+ * @callback GetClassJsdoc
+ * @returns {null|import('comment-parser').Block & {
+ *   inlineTags: import('@es-joy/jsdoccomment').InlineTag[]
+ * }}
+ */
+
+/**
+ * @callback ClassHasTag
+ * @param {string} tagName
+ * @returns {boolean}
+ */
+/**
+ * @typedef {BasicUtils & {
+ *   isIteratingFunction: IsIteratingFunction,
+ *   isVirtualFunction: IsVirtualFunction,
+ *   stringify: Stringify,
+ *   reportJSDoc: ReportJSDoc,
+ *   getRegexFromString: GetRegexFromString,
+ *   getTagDescription: GetTagDescription,
+ *   setTagDescription: SetTagDescription,
+ *   getDescription: GetDescription,
+ *   setBlockDescription: SetBlockDescription,
+ *   setDescriptionLines: SetDescriptionLines,
+ *   changeTag: ChangeTag,
+ *   setTag: SetTag,
+ *   removeTag: RemoveTag,
+ *   addTag: AddTag,
+ *   getFirstLine: GetFirstLine,
+ *   seedTokens: SeedTokens,
+ *   emptyTokens: EmptyTokens,
+ *   addLine: AddLine,
+ *   addLines: AddLines,
+ *   makeMultiline: MakeMultiline,
+ *   flattenRoots: import('./jsdocUtils.js').FlattenRoots,
+ *   getFunctionParameterNames: GetFunctionParameterNames,
+ *   hasParams: HasParams,
+ *   isGenerator: IsGenerator,
+ *   isConstructor: IsConstructor,
+ *   getJsdocTagsDeep: GetJsdocTagsDeep,
+ *   getPreferredTagName: GetPreferredTagName,
+ *   isValidTag: IsValidTag,
+ *   hasATag: HasATag,
+ *   hasTag: HasTag,
+ *   comparePaths: ComparePaths,
+ *   dropPathSegmentQuotes: DropPathSegmentQuotes,
+ *   avoidDocs: AvoidDocs,
+ *   tagMightHaveNamePosition: TagMightHaveNamePositionTypePosition,
+ *   tagMightHaveTypePosition: TagMightHaveNamePositionTypePosition,
+ *   tagMustHaveNamePosition: TagMustHave,
+ *   tagMustHaveTypePosition: TagMustHave,
+ *   tagMissingRequiredTypeOrNamepath: TagMissingRequiredTypeOrNamepath,
+ *   isNamepathDefiningTag: IsNamepathX,
+ *   isNamepathReferencingTag: IsNamepathX,
+ *   isNamepathOrUrlReferencingTag: IsNamepathX,
+ *   tagMightHaveNamepath: IsNamepathX,
+ *   getTagStructureForMode: GetTagStructureForMode,
+ *   mayBeUndefinedTypeTag: MayBeUndefinedTypeTag,
+ *   hasValueOrExecutorHasNonEmptyResolveValue: HasValueOrExecutorHasNonEmptyResolveValue,
+ *   hasYieldValue: HasYieldValue,
+ *   hasYieldReturnValue: HasYieldReturnValue,
+ *   hasThrowValue: HasThrowValue,
+ *   isAsync: IsAsync,
+ *   getTags: GetTags,
+ *   getPresentTags: GetPresentTags,
+ *   filterTags: FilterTags,
+ *   filterAllTags: FilterAllTags,
+ *   getTagsByType: GetTagsByType,
+ *   hasOptionTag: HasOptionTag,
+ *   getClassNode: GetClassNode,
+ *   getClassJsdoc: GetClassJsdoc,
+ *   classHasTag: ClassHasTag
+ * }} Utils
+ */
 const {
   rewireSpecs,
   seedTokens
@@ -25,19 +550,38 @@ const {
 /**
  * Should use ESLint rule's typing.
  *
- * @typedef {any} EslintRuleMeta
+ * @typedef {import('eslint').Rule.RuleMetaData} EslintRuleMeta
  */
 
+/* eslint-disable jsdoc/valid-types -- Old version */
 /**
  * A plain object for tracking state as needed by rules across iterations.
  *
- * @typedef {any} StateObject
+ * @typedef {{
+ *   globalTags: {},
+ *   hasDuplicates: {
+ *     [key: string]: boolean
+ *   },
+ *   selectorMap: {
+ *     [selector: string]: {
+ *       [comment: string]: Integer
+ *     }
+ *   },
+ *   hasTag: {
+ *     [key: string]: boolean
+ *   },
+ *   hasNonComment: number,
+ *   hasNonCommentBeforeTag: {
+ *     [key: string]: boolean|number
+ *   }
+ * }} StateObject
  */
+/* eslint-enable jsdoc/valid-types -- Old version */
 
 /**
  * The Node AST as supplied by the parser.
  *
- * @typedef {any} Node
+ * @typedef {import('eslint').Rule.Node} Node
  */
 
 /*
@@ -49,14 +593,29 @@ const {
 */
 
 const globalState = new Map();
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {{
+ *   tagNamePreference?: import('./jsdocUtils.js').TagNamePreference,
+ *   mode?: import('./jsdocUtils.js').ParserMode
+ * }} cfg
+ * @returns {BasicUtils}
+ */
 const getBasicUtils = (context, {
   tagNamePreference,
   mode
 }) => {
+  /** @type {BasicUtils} */
   const utils = {};
+
+  /** @type {ReportSettings} */
   utils.reportSettings = message => {
     context.report({
       loc: {
+        end: {
+          column: 1,
+          line: 1
+        },
         start: {
           column: 1,
           line: 1
@@ -65,14 +624,18 @@ const getBasicUtils = (context, {
       message
     });
   };
+
+  /** @type {ParseClosureTemplateTag} */
   utils.parseClosureTemplateTag = tag => {
     return _jsdocUtils.default.parseClosureTemplateTag(tag);
   };
   utils.pathDoesNotBeginWith = _jsdocUtils.default.pathDoesNotBeginWith;
+
+  /** @type {GetPreferredTagNameObject} */
   utils.getPreferredTagNameObject = ({
     tagName
   }) => {
-    const ret = _jsdocUtils.default.getPreferredTagName(context, mode, tagName, tagNamePreference);
+    const ret = _jsdocUtils.default.getPreferredTagName(context, /** @type {import('./jsdocUtils.js').ParserMode} */mode, tagName, tagNamePreference);
     const isObject = ret && typeof ret === 'object';
     if (ret === false || isObject && !ret.replacement) {
       return {
@@ -84,10 +647,41 @@ const getBasicUtils = (context, {
   };
   return utils;
 };
+
+/* eslint-disable jsdoc/valid-types -- Old version of pratt */
+/**
+ * @callback Report
+ * @param {string} message
+ * @param {import('eslint').Rule.ReportFixer|null} [fix]
+ * @param {null|
+ *   {line?: Integer, column?: Integer}|
+ *   import('comment-parser').Spec & {line?: Integer}
+ * } [jsdocLoc]
+ * @param {undefined|{
+ *   [key: string]: string
+ * }} [data]
+ * @returns {void}
+ */
+/* eslint-enable jsdoc/valid-types -- Old version of pratt */
+
+/**
+ * @param {Node|null} node
+ * @param {import('comment-parser').Block & {
+ *   inlineTags: import('@es-joy/jsdoccomment').InlineTag[]
+ * }} jsdoc
+ * @param {import('eslint').AST.Token} jsdocNode
+ * @param {Settings} settings
+ * @param {Report} report
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {boolean|undefined} iteratingAll
+ * @param {RuleConfig} ruleConfig
+ * @param {string} indent
+ * @returns {Utils}
+ */
 const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAll, ruleConfig, indent) => {
-  const ancestors = context.getAncestors();
+  const ancestors = /** @type {import('eslint').Rule.Node[]} */context.getAncestors();
   const sourceCode = context.getSourceCode();
-  const utils = getBasicUtils(context, settings);
+  const utils = /** @type {Utils} */getBasicUtils(context, settings);
   const {
     tagNamePreference,
     overrideReplacesDocs,
@@ -98,21 +692,30 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     minLines,
     mode
   } = settings;
+
+  /** @type {IsIteratingFunction} */
   utils.isIteratingFunction = () => {
-    return !iteratingAll || ['MethodDefinition', 'ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression'].includes(node && node.type);
+    return !iteratingAll || ['MethodDefinition', 'ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression'].includes(String(node && node.type));
   };
+
+  /** @type {IsVirtualFunction} */
   utils.isVirtualFunction = () => {
-    return iteratingAll && utils.hasATag(['callback', 'function', 'func', 'method']);
+    return Boolean(iteratingAll) && utils.hasATag(['callback', 'function', 'func', 'method']);
   };
+
+  /** @type {Stringify} */
   utils.stringify = (tagBlock, specRewire) => {
     let block;
     if (specRewire) {
       block = rewireSpecs(tagBlock);
     }
-    return (0, _commentParser.stringify)(specRewire ? block : tagBlock);
+    return (0, _commentParser.stringify)( /** @type {import('comment-parser').Block} */
+    specRewire ? block : tagBlock);
   };
+
+  /** @type {ReportJSDoc} */
   utils.reportJSDoc = (msg, tag, handler, specRewire, data) => {
-    report(msg, handler ? fixer => {
+    report(msg, handler ? /** @type {import('eslint').Rule.ReportFixer} */fixer => {
       handler();
       const replacement = utils.stringify(jsdoc, specRewire);
       if (!replacement) {
@@ -126,10 +729,17 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
       return fixer.replaceText(jsdocNode, replacement);
     } : null, tag, data);
   };
+
+  /** @type {GetRegexFromString} */
   utils.getRegexFromString = (str, requiredFlags) => {
     return _jsdocUtils.default.getRegexFromString(str, requiredFlags);
   };
+
+  /** @type {GetTagDescription} */
   utils.getTagDescription = (tg, returnArray) => {
+    /**
+     * @type {string[]}
+     */
     const descriptions = [];
     tg.source.some(({
       tokens: {
@@ -158,6 +768,8 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     });
     return returnArray ? descriptions : descriptions.join('\n');
   };
+
+  /** @type {SetTagDescription} */
   utils.setTagDescription = (tg, matcher, setter) => {
     let finalIdx = 0;
     tg.source.some(({
@@ -174,7 +786,10 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     });
     return finalIdx;
   };
+
+  /** @type {GetDescription} */
   utils.getDescription = () => {
+    /** @type {string[]} */
     const descriptions = [];
     let lastDescriptionLine = 0;
     let tagsBegun = false;
@@ -206,10 +821,27 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
       lastDescriptionLine
     };
   };
+
+  /** @type {SetBlockDescription} */
   utils.setBlockDescription = setter => {
+    /** @type {string[]} */
     const descLines = [];
+    /**
+     * @type {undefined|Integer}
+     */
     let startIdx;
+    /**
+     * @type {undefined|Integer}
+     */
     let endIdx;
+
+    /**
+     * @type {undefined|{
+     *   delimiter: string,
+     *   postDelimiter: string,
+     *   start: string
+     * }}
+     */
     let info;
     jsdoc.source.some(({
       tokens: {
@@ -242,9 +874,19 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
 
     /* istanbul ignore else -- Won't be called if missing */
     if (descLines.length) {
-      jsdoc.source.splice(startIdx, endIdx - startIdx, ...setter(info, seedTokens, descLines));
+      jsdoc.source.splice( /** @type {Integer} */startIdx, /** @type {Integer} */endIdx - /** @type {Integer} */startIdx, ...setter(
+      /**
+       * @type {{
+       *   delimiter: string,
+       *   postDelimiter: string,
+       *   start: string
+       * }}
+       */
+      info, seedTokens, descLines));
     }
   };
+
+  /** @type {SetDescriptionLines} */
   utils.setDescriptionLines = (matcher, setter) => {
     let finalIdx = 0;
     jsdoc.source.some(({
@@ -267,6 +909,8 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     });
     return finalIdx;
   };
+
+  /** @type {ChangeTag} */
   utils.changeTag = (tag, ...tokens) => {
     for (const [idx, src] of tag.source.entries()) {
       src.tokens = {
@@ -275,10 +919,13 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
       };
     }
   };
+
+  /** @type {SetTag} */
   utils.setTag = (tag, tokens) => {
     tag.source = [{
-      // Or tag.source[0].number?
       number: tag.line,
+      // Or tag.source[0].number?
+      source: '',
       tokens: seedTokens({
         delimiter: '*',
         postDelimiter: ' ',
@@ -288,6 +935,8 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
       })
     }];
   };
+
+  /** @type {RemoveTag} */
   utils.removeTag = (tagIndex, {
     removeEmptyBlock = false,
     tagSourceOffset = 0
@@ -295,6 +944,7 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     const {
       source: tagSource
     } = jsdoc.tags[tagIndex];
+    /** @type {Integer|undefined} */
     let lastIndex;
     const firstNumber = jsdoc.source[0].number;
     tagSource.some(({
@@ -332,7 +982,12 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
             tokens
           } = jsdoc.source[spliceIdx];
           for (const item of ['postDelimiter', 'tag', 'postTag', 'type', 'postType', 'name', 'postName', 'description']) {
-            tokens[item] = '';
+            tokens[
+            /**
+             * @type {"postDelimiter"|"tag"|"type"|"postType"|
+             *   "postTag"|"name"|"postName"|"description"}
+             */
+            item] = '';
           }
         } else {
           jsdoc.source.splice(spliceIdx, spliceCount - tagSourceOffset + (spliceIdx ? 0 : jsdoc.source.length));
@@ -346,14 +1001,16 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
       return false;
     });
     for (const [idx, src] of jsdoc.source.slice(lastIndex).entries()) {
-      src.number = firstNumber + lastIndex + idx;
+      src.number = firstNumber + /** @type {Integer} */lastIndex + idx;
     }
 
-    // Todo: Once rewiring of tags may be fixed in comment-parser to reflect missing tags,
-    //         this step should be added here (so that, e.g., if accessing `jsdoc.tags`,
-    //         such as to add a new tag, the correct information will be available)
+    // Todo: Once rewiring of tags may be fixed in comment-parser to reflect
+    //         missing tags, this step should be added here (so that, e.g.,
+    //         if accessing `jsdoc.tags`, such as to add a new tag, the
+    //         correct information will be available)
   };
 
+  /** @type {AddTag} */
   utils.addTag = (targetTagName, number = ((() => {
     var _jsdoc$tags, _jsdoc$tags$source$;
     return (_jsdoc$tags = jsdoc.tags[jsdoc.tags.length - 1]) === null || _jsdoc$tags === void 0 ? void 0 : (_jsdoc$tags$source$ = _jsdoc$tags.source[0]) === null || _jsdoc$tags$source$ === void 0 ? void 0 : _jsdoc$tags$source$.number;
@@ -379,6 +1036,8 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
       src.number++;
     }
   };
+
+  /** @type {GetFirstLine} */
   utils.getFirstLine = () => {
     let firstLine;
     for (const {
@@ -394,12 +1053,23 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     }
     return firstLine;
   };
+
+  /** @type {SeedTokens} */
   utils.seedTokens = seedTokens;
+
+  /** @type {EmptyTokens} */
   utils.emptyTokens = tokens => {
     for (const prop of ['start', 'postDelimiter', 'tag', 'type', 'postType', 'postTag', 'name', 'postName', 'description', 'end', 'lineEnd']) {
-      tokens[prop] = '';
+      tokens[
+      /**
+       * @type {"start"|"postDelimiter"|"tag"|"type"|"postType"|
+       *   "postTag"|"name"|"postName"|"description"|"end"|"lineEnd"}
+       */
+      prop] = '';
     }
   };
+
+  /** @type {AddLine} */
   utils.addLine = (sourceIndex, tokens) => {
     var _jsdoc$source;
     const number = (((_jsdoc$source = jsdoc.source[sourceIndex - 1]) === null || _jsdoc$source === void 0 ? void 0 : _jsdoc$source.number) || 0) + 1;
@@ -415,10 +1085,12 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     // rewireSource(jsdoc);
   };
 
+  /** @type {AddLines} */
   utils.addLines = (tagIndex, tagSourceOffset, numLines) => {
     const {
       source: tagSource
     } = jsdoc.tags[tagIndex];
+    /** @type {Integer|undefined} */
     let lastIndex;
     const firstNumber = jsdoc.source[0].number;
     tagSource.some(({
@@ -461,9 +1133,11 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
       return false;
     });
     for (const [idx, src] of jsdoc.source.slice(lastIndex).entries()) {
-      src.number = firstNumber + lastIndex + idx;
+      src.number = firstNumber + /** @type {Integer} */lastIndex + idx;
     }
   };
+
+  /** @type {MakeMultiline} */
   utils.makeMultiline = () => {
     const {
       source: [{
@@ -517,23 +1191,45 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
       start: indent + ' '
     });
   };
-  utils.flattenRoots = params => {
-    return _jsdocUtils.default.flattenRoots(params);
-  };
+
+  /**
+   * @type {import('./jsdocUtils.js').FlattenRoots}
+   */
+  utils.flattenRoots = _jsdocUtils.default.flattenRoots;
+
+  /** @type {GetFunctionParameterNames} */
   utils.getFunctionParameterNames = useDefaultObjectProperties => {
     return _jsdocUtils.default.getFunctionParameterNames(node, useDefaultObjectProperties);
   };
+
+  /** @type {HasParams} */
   utils.hasParams = () => {
-    return _jsdocUtils.default.hasParams(node);
+    return _jsdocUtils.default.hasParams( /** @type {Node} */node);
   };
+
+  /** @type {IsGenerator} */
   utils.isGenerator = () => {
-    return node && (node.generator || node.type === 'MethodDefinition' && node.value.generator || ['ExportNamedDeclaration', 'ExportDefaultDeclaration'].includes(node.type) && node.declaration.generator);
+    return node !== null && Boolean(
+    /**
+     * @type {import('estree').FunctionDeclaration|
+     *   import('estree').FunctionExpression}
+     */
+    node.generator || node.type === 'MethodDefinition' && node.value.generator || ['ExportNamedDeclaration', 'ExportDefaultDeclaration'].includes(node.type) && /** @type {import('estree').FunctionDeclaration} */
+    /**
+     * @type {import('estree').ExportNamedDeclaration|
+     *   import('estree').ExportDefaultDeclaration}
+     */
+    node.declaration.generator);
   };
+
+  /** @type {IsConstructor} */
   utils.isConstructor = () => {
-    return _jsdocUtils.default.isConstructor(node);
+    return _jsdocUtils.default.isConstructor( /** @type {Node} */node);
   };
+
+  /** @type {GetJsdocTagsDeep} */
   utils.getJsdocTagsDeep = tagName => {
-    const name = utils.getPreferredTagName({
+    const name = /** @type {string|false} */utils.getPreferredTagName({
       tagName
     });
     if (!name) {
@@ -541,6 +1237,8 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     }
     return _jsdocUtils.default.getJsdocTagsDeep(jsdoc, name);
   };
+
+  /** @type {GetPreferredTagName} */
   utils.getPreferredTagName = ({
     tagName,
     skipReportingBlockedTag = false,
@@ -562,27 +1260,40 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     }
     return isObject && !allowObjectReturn ? ret.replacement : ret;
   };
+
+  /** @type {IsValidTag} */
   utils.isValidTag = (name, definedTags) => {
     return _jsdocUtils.default.isValidTag(context, mode, name, definedTags);
   };
+
+  /** @type {HasATag} */
   utils.hasATag = names => {
     return _jsdocUtils.default.hasATag(jsdoc, names);
   };
+
+  /** @type {HasTag} */
   utils.hasTag = name => {
     return _jsdocUtils.default.hasTag(jsdoc, name);
   };
+
+  /** @type {ComparePaths} */
   utils.comparePaths = name => {
     return _jsdocUtils.default.comparePaths(name);
   };
+
+  /** @type {DropPathSegmentQuotes} */
   utils.dropPathSegmentQuotes = name => {
     return _jsdocUtils.default.dropPathSegmentQuotes(name);
   };
+
+  /** @type {AvoidDocs} */
   utils.avoidDocs = () => {
     var _context$options$;
     if (ignoreReplacesDocs !== false && (utils.hasTag('ignore') || utils.classHasTag('ignore')) || overrideReplacesDocs !== false && (utils.hasTag('override') || utils.classHasTag('override')) || implementsReplacesDocs !== false && (utils.hasTag('implements') || utils.classHasTag('implements')) || augmentsExtendsReplacesDocs && (utils.hasATag(['augments', 'extends']) || utils.classHasTag('augments') || utils.classHasTag('extends'))) {
       return true;
     }
-    if (_jsdocUtils.default.exemptSpeciaMethods(jsdoc, node, context, ruleConfig.meta.schema)) {
+    if (_jsdocUtils.default.exemptSpeciaMethods(jsdoc, node, context, /** @type {import('json-schema').JSONSchema4|import('json-schema').JSONSchema4[]} */
+    ruleConfig.meta.schema)) {
       return true;
     }
     const exemptedBy = ((_context$options$ = context.options[0]) === null || _context$options$ === void 0 ? void 0 : _context$options$.exemptedBy) ?? ['inheritDoc', ...(mode === 'closure' ? [] : ['inheritdoc'])];
@@ -592,8 +1303,11 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     return false;
   };
   for (const method of ['tagMightHaveNamePosition', 'tagMightHaveTypePosition']) {
-    utils[method] = (tagName, otherModeMaps) => {
-      const result = _jsdocUtils.default[method](tagName);
+    /** @type {TagMightHaveNamePositionTypePosition} */
+    utils[/** @type {"tagMightHaveNamePosition"|"tagMightHaveTypePosition"} */
+    method] = (tagName, otherModeMaps) => {
+      const result = _jsdocUtils.default[/** @type {"tagMightHaveNamePosition"|"tagMightHaveTypePosition"} */
+      method](tagName);
       if (result) {
         return true;
       }
@@ -601,16 +1315,34 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
         return false;
       }
       const otherResult = otherModeMaps.some(otherModeMap => {
-        return _jsdocUtils.default[method](tagName, otherModeMap);
+        return _jsdocUtils.default[/** @type {"tagMightHaveNamePosition"|"tagMightHaveTypePosition"} */
+        method](tagName, otherModeMap);
       });
       return otherResult ? {
         otherMode: true
       } : false;
     };
   }
-  for (const method of ['tagMustHaveNamePosition', 'tagMustHaveTypePosition', 'tagMissingRequiredTypeOrNamepath']) {
-    utils[method] = (tagName, otherModeMaps) => {
-      const result = _jsdocUtils.default[method](tagName);
+
+  /** @type {TagMissingRequiredTypeOrNamepath} */
+  utils.tagMissingRequiredTypeOrNamepath = (tagName, otherModeMaps) => {
+    const result = _jsdocUtils.default.tagMissingRequiredTypeOrNamepath(tagName);
+    if (!result) {
+      return false;
+    }
+    const otherResult = otherModeMaps.every(otherModeMap => {
+      return _jsdocUtils.default.tagMissingRequiredTypeOrNamepath(tagName, otherModeMap);
+    });
+    return otherResult ? true : {
+      otherMode: false
+    };
+  };
+  for (const method of ['tagMustHaveNamePosition', 'tagMustHaveTypePosition']) {
+    /** @type {TagMustHave} */
+    utils[/** @type {"tagMustHaveNamePosition"|"tagMustHaveTypePosition"} */
+    method] = (tagName, otherModeMaps) => {
+      const result = _jsdocUtils.default[/** @type {"tagMustHaveNamePosition"|"tagMustHaveTypePosition"} */
+      method](tagName);
       if (!result) {
         return false;
       }
@@ -618,7 +1350,8 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
       // if (!otherModeMaps) { return true; }
 
       const otherResult = otherModeMaps.every(otherModeMap => {
-        return _jsdocUtils.default[method](tagName, otherModeMap);
+        return _jsdocUtils.default[/** @type {"tagMustHaveNamePosition"|"tagMustHaveTypePosition"} */
+        method](tagName, otherModeMap);
       });
       return otherResult ? true : {
         otherMode: false
@@ -626,62 +1359,104 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     };
   }
   for (const method of ['isNamepathDefiningTag', 'isNamepathReferencingTag', 'isNamepathOrUrlReferencingTag', 'tagMightHaveNamepath']) {
-    utils[method] = tagName => {
-      return _jsdocUtils.default[method](tagName);
+    /** @type {IsNamepathX} */
+    utils[/** @type {"isNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNamepath"} */
+    method] = tagName => {
+      return _jsdocUtils.default[/** @type {"isNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNamepath"} */
+      method](tagName);
     };
   }
+
+  /** @type {GetTagStructureForMode} */
   utils.getTagStructureForMode = mde => {
     return _jsdocUtils.default.getTagStructureForMode(mde, settings.structuredTags);
   };
+
+  /** @type {MayBeUndefinedTypeTag} */
   utils.mayBeUndefinedTypeTag = tag => {
     return _jsdocUtils.default.mayBeUndefinedTypeTag(tag, settings.mode);
   };
+
+  /** @type {HasValueOrExecutorHasNonEmptyResolveValue} */
   utils.hasValueOrExecutorHasNonEmptyResolveValue = (anyPromiseAsReturn, allBranches) => {
-    return _jsdocUtils.default.hasValueOrExecutorHasNonEmptyResolveValue(node, anyPromiseAsReturn, allBranches);
+    return _jsdocUtils.default.hasValueOrExecutorHasNonEmptyResolveValue( /** @type {Node} */node, anyPromiseAsReturn, allBranches);
   };
+
+  /** @type {HasYieldValue} */
   utils.hasYieldValue = () => {
-    if (['ExportNamedDeclaration', 'ExportDefaultDeclaration'].includes(node.type)) {
-      return _jsdocUtils.default.hasYieldValue(node.declaration);
+    if (['ExportNamedDeclaration', 'ExportDefaultDeclaration'].includes( /** @type {Node} */node.type)) {
+      return _jsdocUtils.default.hasYieldValue( /** @type {import('estree').Declaration|import('estree').Expression} */
+      /** @type {import('estree').ExportNamedDeclaration|import('estree').ExportDefaultDeclaration} */
+      node.declaration);
     }
-    return _jsdocUtils.default.hasYieldValue(node);
+    return _jsdocUtils.default.hasYieldValue( /** @type {Node} */node);
   };
+
+  /** @type {HasYieldReturnValue} */
   utils.hasYieldReturnValue = () => {
-    return _jsdocUtils.default.hasYieldValue(node, true);
+    return _jsdocUtils.default.hasYieldValue( /** @type {Node} */node, true);
   };
+
+  /** @type {HasThrowValue} */
   utils.hasThrowValue = () => {
     return _jsdocUtils.default.hasThrowValue(node);
   };
+
+  /** @type {IsAsync} */
   utils.isAsync = () => {
-    return node.async;
+    return 'async' in /** @type {Node} */node && node.async;
   };
+
+  /** @type {GetTags} */
   utils.getTags = tagName => {
     return utils.filterTags(item => {
       return item.tag === tagName;
     });
   };
+
+  /** @type {GetPresentTags} */
   utils.getPresentTags = tagList => {
     return utils.filterTags(tag => {
       return tagList.includes(tag.tag);
     });
   };
-  utils.filterTags = (filter, includeInlineTags = false) => {
-    const tags = _jsdocUtils.default.getAllTags(jsdoc, includeInlineTags);
-    return _jsdocUtils.default.filterTags(tags, filter);
+
+  /** @type {FilterTags} */
+  utils.filterTags = filter => {
+    return jsdoc.tags.filter(tag => {
+      return filter(tag);
+    });
   };
+
+  /** @type {FilterAllTags} */
+  utils.filterAllTags = filter => {
+    const tags = _jsdocUtils.default.getAllTags(jsdoc);
+    return tags.filter(tag => {
+      return filter(tag);
+    });
+  };
+
+  /** @type {GetTagsByType} */
   utils.getTagsByType = tags => {
     return _jsdocUtils.default.getTagsByType(context, mode, tags, tagNamePreference);
   };
+
+  /** @type {HasOptionTag} */
   utils.hasOptionTag = tagName => {
     const {
       tags
     } = context.options[0] ?? {};
     return Boolean(tags && tags.includes(tagName));
   };
+
+  /** @type {GetClassNode} */
   utils.getClassNode = () => {
     return [...ancestors, node].reverse().find(parent => {
       return parent && ['ClassDeclaration', 'ClassExpression'].includes(parent.type);
-    }) || null;
+    }) ?? null;
   };
+
+  /** @type {GetClassJsdoc} */
   utils.getClassJsdoc = () => {
     const classNode = utils.getClassNode();
     if (!classNode) {
@@ -696,12 +1471,17 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
     }
     return null;
   };
+
+  /** @type {ClassHasTag} */
   utils.classHasTag = tagName => {
     const classJsdoc = utils.getClassJsdoc();
-    return Boolean(classJsdoc) && _jsdocUtils.default.hasTag(classJsdoc, tagName);
+    return classJsdoc !== null && _jsdocUtils.default.hasTag(classJsdoc, tagName);
   };
+
+  /** @type {ForEachPreferredTag} */
   utils.forEachPreferredTag = (tagName, arrayHandler, skipReportingBlockedTag = false) => {
-    const targetTagName = utils.getPreferredTagName({
+    const targetTagName = /** @type {string|false} */
+    utils.getPreferredTagName({
       skipReportingBlockedTag,
       tagName
     });
@@ -714,11 +1494,57 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
       return tag === targetTagName;
     });
     for (const matchingJsdocTag of matchingJsdocTags) {
-      arrayHandler(matchingJsdocTag, targetTagName);
+      arrayHandler(
+      /**
+       * @type {import('comment-parser').Spec & {
+       *   line: Integer
+       * }}
+       */
+      matchingJsdocTag, targetTagName);
     }
   };
   return utils;
 };
+
+/* eslint-disable jsdoc/valid-types -- Old version */
+/**
+ * @typedef {{
+ *   [key: string]: false|string|{
+ *     message: string,
+ *     replacement?: false|string
+ *     skipRootChecking?: boolean
+ *   }
+ * }} PreferredTypes
+ */
+/**
+ * @typedef {{
+ *   [key: string]: {
+ *     name?: "text"|"namepath-defining"|"namepath-referencing"|false,
+ *     type?: boolean|string[],
+ *     required?: ("name"|"type"|"typeOrNameRequired")[]
+ *   }
+ * }} StructuredTags
+ */
+/**
+ * Settings from ESLint types.
+ *
+ * @typedef {{
+ *   maxLines: Integer,
+ *   minLines: Integer,
+ *   tagNamePreference: import('./jsdocUtils.js').TagNamePreference,
+ *   mode: import('./jsdocUtils.js').ParserMode,
+ *   preferredTypes: PreferredTypes,
+ *   structuredTags: StructuredTags,
+ *   [name: string]: any,
+ *   contexts?: Context[]
+ * }} Settings
+ */
+/* eslint-enable jsdoc/valid-types -- Old version */
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ * @returns {Settings|false}
+ */
 const getSettings = context => {
   var _context$settings$jsd, _context$settings$jsd2, _context$settings$jsd3, _context$settings$jsd4, _context$settings$jsd5, _context$settings$jsd6, _context$settings$jsd7, _context$settings$jsd8, _context$settings$jsd9, _context$settings$jsd10, _context$settings$jsd11, _context$settings$jsd12, _context$settings$jsd13, _context$settings$jsd14;
   /* eslint-disable canonical/sort-keys */
@@ -755,12 +1581,16 @@ const getSettings = context => {
   } catch (error) {
     context.report({
       loc: {
+        end: {
+          column: 1,
+          line: 1
+        },
         start: {
           column: 1,
           line: 1
         }
       },
-      message: error.message
+      message: /** @type {Error} */error.message
     });
     return false;
   }
@@ -770,18 +1600,24 @@ const getSettings = context => {
 /**
  * Create the report function
  *
- * @param {object} context
- * @param {object} commentNode
+ * @callback MakeReport
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {import('estree').Node} commentNode
+ * @returns {Report}
  */
+
+/** @type {MakeReport} */
 exports.getSettings = getSettings;
 const makeReport = (context, commentNode) => {
-  const report = (message, fix = null, jsdocLoc = null, data = null) => {
+  /** @type {Report} */
+  const report = (message, fix = null, jsdocLoc = null, data = undefined) => {
+    /* eslint-enable jsdoc/valid-types -- Old version */
     let loc;
     if (jsdocLoc) {
       if (!('line' in jsdocLoc)) {
-        jsdocLoc.line = jsdocLoc.source[0].number;
+        jsdocLoc.line = /** @type {import('comment-parser').Spec & {line?: Integer}} */jsdocLoc.source[0].number;
       }
-      const lineNumber = commentNode.loc.start.line + jsdocLoc.line;
+      const lineNumber = /** @type {import('eslint').AST.SourceLocation} */commentNode.loc.start.line + /** @type {Integer} */jsdocLoc.line;
       loc = {
         end: {
           column: 0,
@@ -795,8 +1631,8 @@ const makeReport = (context, commentNode) => {
 
       // Todo: Remove ignore once `check-examples` can be restored for ESLint 8+
       // istanbul ignore if
-      if (jsdocLoc.column) {
-        const colNumber = commentNode.loc.start.column + jsdocLoc.column;
+      if ('column' in jsdocLoc && typeof jsdocLoc.column === 'number') {
+        const colNumber = /** @type {import('eslint').AST.SourceLocation} */commentNode.loc.start.column + jsdocLoc.column;
         loc.end.column = colNumber;
         loc.start.column = colNumber;
       }
@@ -812,29 +1648,89 @@ const makeReport = (context, commentNode) => {
   return report;
 };
 
-/* eslint-disable jsdoc/no-undefined-types -- canonical still using an older version where not defined */
+/* eslint-disable jsdoc/valid-types -- Old version */
 /**
- * @typedef {ReturnType<typeof getUtils>} Utils
- * @typedef {ReturnType<typeof getSettings>} Settings
  * @typedef {(
  *   arg: {
- *     context: object,
- *     sourceCode: object,
+ *     context: import('eslint').Rule.RuleContext,
+ *     sourceCode: import('eslint').SourceCode,
+ *     indent?: string,
+ *     info?: {
+ *       comment?: string|undefined,
+ *       lastIndex?: Integer|undefined
+ *     },
+ *     state?: StateObject,
+ *     globalState?: Map<string, Map<string, string>>,
+ *     jsdoc?: import('comment-parser').Block,
+ *     jsdocNode?: import('eslint').Rule.Node & {
+ *       range: [number, number]
+ *     },
+ *     node?: Node,
+ *     allComments?: import('estree').Node[]
+ *     report?: Report,
+ *     makeReport?: MakeReport,
+ *     settings: Settings,
+ *     utils: BasicUtils,
+ *   }
+ * ) => any } JsdocVisitorBasic
+ */
+/**
+ * @typedef {(
+ *   arg: {
+ *     context: import('eslint').Rule.RuleContext,
+ *     sourceCode: import('eslint').SourceCode,
  *     indent: string,
- *     jsdoc: object,
- *     jsdocNode: object,
- *     node: Node | null,
- *     report: ReturnType<typeof makeReport>,
+ *     info: {
+ *       comment?: string|undefined,
+ *       lastIndex?: Integer|undefined
+ *     },
+ *     state: StateObject,
+ *     globalState: Map<string, Map<string, string>>,
+ *     jsdoc: import('comment-parser').Block,
+ *     jsdocNode: import('eslint').Rule.Node & {
+ *       range: [number, number]
+ *     },
+ *     node: Node|null,
+ *     allComments?: import('estree').Node[]
+ *     report: Report,
+ *     makeReport?: MakeReport,
  *     settings: Settings,
  *     utils: Utils,
  *   }
  * ) => any } JsdocVisitor
  */
+/* eslint-enable jsdoc/valid-types -- Old version */
 /* eslint-enable jsdoc/no-undefined-types -- canonical still using an older version where not defined */
 
+/**
+ * @param {{
+ *   comment?: string,
+ *   lastIndex?: Integer,
+ *   selector?: string,
+ *   isFunctionContext?: boolean,
+ * }} info
+ * @param {string} indent
+ * @param {import('comment-parser').Block & {
+ *   inlineTags: import('@es-joy/jsdoccomment').InlineTag[]
+ * }} jsdoc
+ * @param {RuleConfig} ruleConfig
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {string[]} lines
+ * @param {import('@es-joy/jsdoccomment').Token} jsdocNode
+ * @param {Node|null} node
+ * @param {Settings} settings
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {JsdocVisitor} iterator
+ * @param {StateObject} state
+ * @param {boolean} [iteratingAll]
+ * @returns {void}
+ */
 const iterate = (info, indent, jsdoc, ruleConfig, context, lines, jsdocNode, node, settings, sourceCode, iterator, state, iteratingAll) => {
-  const report = makeReport(context, jsdocNode);
-  const utils = getUtils(node, jsdoc, jsdocNode, settings, report, context, iteratingAll, ruleConfig, indent);
+  const jsdocNde = /** @type {unknown} */jsdocNode;
+  const report = makeReport(context, /** @type {import('estree').Node} */
+  jsdocNde);
+  const utils = getUtils(node, jsdoc, /** @type {import('eslint').AST.Token} */
+  jsdocNode, settings, report, context, iteratingAll, ruleConfig, indent);
   if (!ruleConfig.checkInternal && settings.ignoreInternal && utils.hasTag('internal')) {
     return;
   }
@@ -854,9 +1750,13 @@ const iterate = (info, indent, jsdoc, ruleConfig, context, lines, jsdocNode, nod
     globalState,
     indent,
     info,
-    iteratingAll,
     jsdoc,
-    jsdocNode,
+    jsdocNode:
+    /**
+     * @type {import('eslint').Rule.Node & {
+     *  range: [number, number];}}
+     */
+    jsdocNde,
     node,
     report,
     settings,
@@ -865,23 +1765,28 @@ const iterate = (info, indent, jsdoc, ruleConfig, context, lines, jsdocNode, nod
     utils
   });
 };
+
+/**
+ * @param {string[]} lines
+ * @param {import('estree').Comment} jsdocNode
+ * @returns {[indent: string, jsdoc: import('comment-parser').Block & {
+ *   inlineTags: import('@es-joy/jsdoccomment').InlineTag[]
+ * }]}
+ */
 const getIndentAndJSDoc = function (lines, jsdocNode) {
-  const sourceLine = lines[jsdocNode.loc.start.line - 1];
-  const indnt = sourceLine.charAt(0).repeat(jsdocNode.loc.start.column);
+  const sourceLine = lines[/** @type {import('estree').SourceLocation} */
+  jsdocNode.loc.start.line - 1];
+  const indnt = sourceLine.charAt(0).repeat( /** @type {import('estree').SourceLocation} */
+  jsdocNode.loc.start.column);
   const jsdc = (0, _jsdoccomment.parseComment)(jsdocNode, '');
   return [indnt, jsdc];
 };
 
 /**
  *
- * @typedef {{node: Node, state: StateObject}} NonCommentArgs
- */
-
-/**
- * Our internal dynamic set of utilities.
- *
- * @todo Document
- * @typedef {any} Utils
+ * @typedef {{node: Node & {
+ *   range: [number, number]
+ * }, state: StateObject}} NonCommentArgs
  */
 
 /**
@@ -891,9 +1796,20 @@ const getIndentAndJSDoc = function (lines, jsdocNode) {
  * @property {true} [contextSelected] Whether to force a `contexts` check
  * @property {true} [iterateAllJsdocs] Whether to iterate all JSDoc blocks by default
  *   regardless of context
- * @property {(context, state: StateObject, utils: Utils) => void} [exit] Handler to be executed
- *   upon exiting iteration of program AST
- * @property {(NonCommentArgs) => void} [nonComment] Handler to be executed if rule wishes
+ * @property {true} [checkPrivate] Whether to check `@private` blocks (normally exempted)
+ * @property {true} [checkInternal] Whether to check `@internal` blocks (normally exempted)
+ * @property {true} [checkFile] Whether to iterates over all JSDoc blocks regardless of attachment
+ * @property {true} [nonGlobalSettings] Whether to avoid relying on settings for global contexts
+ * @property {true} [noTracking] Whether to disable the tracking of visited comment nodes (as
+ *   non-tracked may conduct further actions)
+ * @property {true} [matchContext] Whether the rule expects contexts to be based on a match option
+ * @property {(args: {
+ *   context: import('eslint').Rule.RuleContext,
+ *   state: StateObject,
+ *   settings: Settings,
+ *   utils: BasicUtils
+ * }) => void} [exit] Handler to be executed upon exiting iteration of program AST
+ * @property {(nca: NonCommentArgs) => void} [nonComment] Handler to be executed if rule wishes
  *   to be supplied nodes without comments
  */
 
@@ -903,30 +1819,46 @@ const getIndentAndJSDoc = function (lines, jsdocNode) {
  *
  * @param {JsdocVisitor} iterator
  * @param {RuleConfig} ruleConfig The rule's configuration
- * @param contexts The `contexts` containing relevant `comment` info.
- * @param {boolean} additiveCommentContexts If true, will have a separate
+ * @param {ContextObject[]|null} [contexts] The `contexts` containing relevant `comment` info.
+ * @param {boolean} [additiveCommentContexts] If true, will have a separate
  *   iteration for each matching comment context. Otherwise, will iterate
  *   once if there is a single matching comment context.
+ * @returns {import('eslint').Rule.RuleModule}
  */
 const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContexts) => {
   const trackedJsdocs = new Set();
+
+  /** @type {import('@es-joy/jsdoccomment').CommentHandler} */
   let handler;
+
+  /** @type {Settings|false} */
   let settings;
+
+  /**
+   * @param {import('eslint').Rule.RuleContext} context
+   * @param {Node|null} node
+   * @param {import('estree').Comment[]} jsdocNodes
+   * @param {StateObject} state
+   * @param {boolean} [lastCall]
+   * @returns {void}
+   */
   const callIterator = (context, node, jsdocNodes, state, lastCall) => {
     const sourceCode = context.getSourceCode();
     const {
       lines
     } = sourceCode;
-    const utils = getBasicUtils(context, settings);
+    const utils = getBasicUtils(context, /** @type {Settings} */settings);
     for (const jsdocNode of jsdocNodes) {
-      if (!/^\/\*\*\s/u.test(sourceCode.getText(jsdocNode))) {
+      const jsdocNde = /** @type {unknown} */jsdocNode;
+      if (!/^\/\*\*\s/u.test(sourceCode.getText( /** @type {import('estree').Node} */
+      jsdocNde))) {
         continue;
       }
       const [indent, jsdoc] = getIndentAndJSDoc(lines, jsdocNode);
       if (additiveCommentContexts) {
         for (const [idx, {
           comment
-        }] of contexts.entries()) {
+        }] of /** @type {ContextObject[]} */contexts.entries()) {
           if (comment && handler(comment, jsdoc) === false) {
             continue;
           }
@@ -934,7 +1866,9 @@ const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContext
             comment,
             lastIndex: idx,
             selector: node === null || node === void 0 ? void 0 : node.type
-          }, indent, jsdoc, ruleConfig, context, lines, jsdocNode, node, settings, sourceCode, iterator, state, true);
+          }, indent, jsdoc, ruleConfig, context, lines, jsdocNode, /** @type {Node} */
+          node, /** @type {Settings} */
+          settings, sourceCode, iterator, state, true);
         }
         continue;
       }
@@ -957,18 +1891,21 @@ const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContext
       } : {
         lastIndex,
         selector: node === null || node === void 0 ? void 0 : node.type
-      }, indent, jsdoc, ruleConfig, context, lines, jsdocNode, node, settings, sourceCode, iterator, state, true);
+      }, indent, jsdoc, ruleConfig, context, lines, jsdocNode, node, /** @type {Settings} */
+      settings, sourceCode, iterator, state, true);
     }
+    const settngs = /** @type {Settings} */settings;
     if (lastCall && ruleConfig.exit) {
       ruleConfig.exit({
         context,
-        settings,
+        settings: settngs,
         state,
         utils
       });
     }
   };
   return {
+    // @ts-expect-error ESLint accepts
     create(context) {
       const sourceCode = context.getSourceCode();
       settings = getSettings(context);
@@ -980,29 +1917,38 @@ const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContext
       }
       const state = {};
       return {
+        /**
+         * @param {import('eslint').Rule.Node & {
+         *   range: [Integer, Integer];
+         * }} node
+         * @returns {void}
+         */
         '*:not(Program)'(node) {
-          const commentNode = (0, _jsdoccomment.getJSDocComment)(sourceCode, node, settings);
+          const commentNode = (0, _jsdoccomment.getJSDocComment)(sourceCode, node, /** @type {Settings} */settings);
           if (!ruleConfig.noTracking && trackedJsdocs.has(commentNode)) {
             return;
           }
           if (!commentNode) {
             if (ruleConfig.nonComment) {
+              const ste = /** @type {StateObject} */state;
               ruleConfig.nonComment({
                 node,
-                state
+                state: ste
               });
             }
             return;
           }
           trackedJsdocs.add(commentNode);
-          callIterator(context, node, [commentNode], state);
+          callIterator(context, node, [/** @type {import('estree').Comment} */
+          commentNode], /** @type {StateObject} */state);
         },
         'Program:exit'() {
           const allComments = sourceCode.getAllComments();
           const untrackedJSdoc = allComments.filter(node => {
             return !trackedJsdocs.has(node);
           });
-          callIterator(context, null, untrackedJSdoc, state, true);
+          callIterator(context, null, untrackedJSdoc, /** @type {StateObject} */
+          state, true);
         }
       };
     },
@@ -1014,8 +1960,9 @@ const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContext
  * Create an eslint rule that iterates over all JSDocs, regardless of whether
  * they are attached to a function-like node.
  *
- * @param {JsdocVisitor} iterator
+ * @param {JsdocVisitorBasic} iterator
  * @param {RuleConfig} ruleConfig
+ * @returns {import('eslint').Rule.RuleModule}
  */
 const checkFile = (iterator, ruleConfig) => {
   return {
@@ -1027,15 +1974,11 @@ const checkFile = (iterator, ruleConfig) => {
       }
       return {
         'Program:exit'() {
-          const allComments = sourceCode.getAllComments();
-          const {
-            lines
-          } = sourceCode;
+          const allComms = /** @type {unknown} */sourceCode.getAllComments();
           const utils = getBasicUtils(context, settings);
           iterator({
-            allComments,
+            allComments: /** @type {import('estree').Node[]} */allComms,
             context,
-            lines,
             makeReport,
             settings,
             sourceCode,
@@ -1050,6 +1993,7 @@ const checkFile = (iterator, ruleConfig) => {
 /**
  * @param {JsdocVisitor} iterator
  * @param {RuleConfig} ruleConfig
+ * @returns {import('eslint').Rule.RuleModule}
  */
 function iterateJsdoc(iterator, ruleConfig) {
   var _ruleConfig$meta;
@@ -1061,27 +2005,34 @@ function iterateJsdoc(iterator, ruleConfig) {
     throw new TypeError('The iterator argument must be a function.');
   }
   if (ruleConfig.checkFile) {
-    return checkFile(iterator, ruleConfig);
+    return checkFile( /** @type {JsdocVisitorBasic} */iterator, ruleConfig);
   }
   if (ruleConfig.iterateAllJsdocs) {
     return iterateAllJsdocs(iterator, ruleConfig);
   }
+
+  /** @type {import('eslint').Rule.RuleModule} */
   return {
     /**
      * The entrypoint for the JSDoc rule.
      *
-     * @param {*} context
+     * @param {import('eslint').Rule.RuleContext} context
      *   a reference to the context which hold all important information
      *   like settings and the sourcecode to check.
-     * @returns {object}
-     *   a list with parser callback function.
+     * @returns {import('eslint').Rule.RuleListener}
+     *   a listener with parser callback function.
      */
     create(context) {
       const settings = getSettings(context);
       if (!settings) {
         return {};
       }
+
+      /**
+       * @type {Context[]|undefined}
+       */
       let contexts;
+      /* eslint-enable jsdoc/valid-types -- Old version */
       if (ruleConfig.contextDefaults || ruleConfig.contextSelected || ruleConfig.matchContext) {
         var _context$options$2, _contexts, _contexts2;
         contexts = ruleConfig.matchContext && (_context$options$2 = context.options[0]) !== null && _context$options$2 !== void 0 && _context$options$2.match ? context.options[0].match : _jsdocUtils.default.enforcedContexts(context, ruleConfig.contextDefaults, ruleConfig.nonGlobalSettings ? {} : settings);
@@ -1098,23 +2049,33 @@ function iterateJsdoc(iterator, ruleConfig) {
         }
         const hasPlainAny = (_contexts = contexts) === null || _contexts === void 0 ? void 0 : _contexts.includes('any');
         const hasObjectAny = !hasPlainAny && ((_contexts2 = contexts) === null || _contexts2 === void 0 ? void 0 : _contexts2.find(ctxt => {
+          if (typeof ctxt === 'string') {
+            return false;
+          }
           return (ctxt === null || ctxt === void 0 ? void 0 : ctxt.context) === 'any';
         }));
         if (hasPlainAny || hasObjectAny) {
-          return iterateAllJsdocs(iterator, ruleConfig, hasObjectAny ? contexts : null, ruleConfig.matchContext).create(context);
+          return iterateAllJsdocs(iterator, ruleConfig, hasObjectAny ? /** @type {ContextObject[]} */contexts : null, ruleConfig.matchContext).create(context);
         }
       }
       const sourceCode = context.getSourceCode();
       const {
         lines
       } = sourceCode;
+
+      /* eslint-disable jsdoc/no-undefined-types -- TS */
+      /** @type {Partial<StateObject>} */
       const state = {};
+      /* eslint-enable jsdoc/no-undefined-types -- TS */
+
+      /** @type {CheckJsdoc} */
       const checkJsdoc = (info, handler, node) => {
         const jsdocNode = (0, _jsdoccomment.getJSDocComment)(sourceCode, node, settings);
         if (!jsdocNode) {
           return;
         }
-        const [indent, jsdoc] = getIndentAndJSDoc(lines, jsdocNode);
+        const [indent, jsdoc] = getIndentAndJSDoc(lines, /** @type {import('estree').Comment} */
+        jsdocNode);
         if (
         // Note, `handler` should already be bound in its first argument
         //  with these only to be called after the value of
@@ -1122,8 +2083,11 @@ function iterateJsdoc(iterator, ruleConfig) {
         handler && handler(jsdoc) === false) {
           return;
         }
-        iterate(info, indent, jsdoc, ruleConfig, context, lines, jsdocNode, node, settings, sourceCode, iterator, state);
+        iterate(info, indent, jsdoc, ruleConfig, context, lines, jsdocNode, node, settings, sourceCode, iterator, /** @type {StateObject} */
+        state);
       };
+
+      /** @type {import('eslint').Rule.RuleListener} */
       let contextObject = {};
       if (contexts && (ruleConfig.contextDefaults || ruleConfig.contextSelected || ruleConfig.matchContext)) {
         contextObject = _jsdocUtils.default.getContextObject(contexts, checkJsdoc, (0, _jsdoccomment.commentHandler)(settings));
@@ -1134,15 +2098,21 @@ function iterateJsdoc(iterator, ruleConfig) {
           }, null);
         }
       }
-      if (ruleConfig.exit) {
+      if (typeof ruleConfig.exit === 'function') {
         contextObject['Program:exit'] = () => {
+          const ste = /** @type {StateObject} */state;
+          /* eslint-disable jsdoc/no-undefined-types -- Bug */
+          // @ts-expect-error `utils` not needed at this point
+          /** @type {Required<RuleConfig>} */
           ruleConfig.exit({
             context,
             settings,
-            state
+            state: ste
           });
+          /* eslint-enable jsdoc/no-undefined-types -- Bug */
         };
       }
+
       return contextObject;
     },
     meta: ruleConfig.meta