refactor: more descriptive var. naming; better use of jsdoc ourselves

src/iterateJsdoc.js

@@ -15,6 +15,26 @@ const {
   seedTokens,
 } = util;
 
+// todo: Change these `any` types once importing types properly.
+
+/**
+ * Should use ESLint rule's typing.
+ *
+ * @typedef {any} EslintRuleMeta
+ */
+
+/**
+ * A plain object for tracking state as needed by rules across iterations.
+ *
+ * @typedef {any} StateObject
+ */
+
+/**
+ * The Node AST as supplied by the parser.
+ *
+ * @typedef {any} Node
+ */
+
 /*
 const {
    align as commentAlign,
@@ -875,7 +895,7 @@ const makeReport = (context, commentNode) => {
   return report;
 };
 
-/* eslint-disable jsdoc/no-undefined-types -- Need to build this in; see https://www.typescriptlang.org/docs/handbook/utility-types.html */
+/* eslint-disable jsdoc/no-undefined-types -- canonical still using an older version where not defined */
 /**
  * @typedef {ReturnType<typeof getUtils>} Utils
  * @typedef {ReturnType<typeof getSettings>} Settings
@@ -886,14 +906,14 @@ const makeReport = (context, commentNode) => {
  *     indent: string,
  *     jsdoc: object,
  *     jsdocNode: object,
- *     node: object | null,
+ *     node: Node | null,
  *     report: ReturnType<typeof makeReport>,
  *     settings: Settings,
  *     utils: Utils,
  *   }
  * ) => any } JsdocVisitor
  */
-/* eslint-enable jsdoc/no-undefined-types -- Need to build this in */
+/* eslint-enable jsdoc/no-undefined-types -- canonical still using an older version where not defined */
 
 const iterate = (
   info,
@@ -969,16 +989,43 @@ const getIndentAndJSDoc = function (lines, jsdocNode) {
   ];
 };
 
+/**
+ *
+ * @typedef {{node: Node, state: StateObject}} NonCommentArgs
+ */
+
+/**
+ * Our internal dynamic set of utilities.
+ *
+ * @todo Document
+ * @typedef {any} Utils
+ */
+
+/**
+ * @typedef {object} RuleConfig
+ * @property {EslintRuleMeta} meta ESLint rule meta
+ * @property {import('./jsdocUtils').DefaultContexts} [contextDefaults] Any default contexts
+ * @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
+ *   to be supplied nodes without comments
+ */
+
 /**
  * Create an eslint rule that iterates over all JSDocs, regardless of whether
  * they are attached to a function-like node.
  *
  * @param {JsdocVisitor} iterator
- * @param {{meta: any}} ruleConfig
- * @param contexts
- * @param {boolean} additiveContexts
+ * @param {RuleConfig} ruleConfig The rule's configuration
+ * @param 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.
  */
-const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveContexts) => {
+const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContexts) => {
   const trackedJsdocs = new Set();
 
   let handler;
@@ -1002,7 +1049,7 @@ const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveContexts) => {
         lines, jsdocNode,
       );
 
-      if (additiveContexts) {
+      if (additiveCommentContexts) {
         for (const [
           idx,
           {
@@ -1146,7 +1193,7 @@ const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveContexts) => {
  * they are attached to a function-like node.
  *
  * @param {JsdocVisitor} iterator
- * @param {{meta: any}} ruleConfig
+ * @param {RuleConfig} ruleConfig
  */
 const checkFile = (iterator, ruleConfig) => {
   return {
@@ -1189,12 +1236,7 @@ export {
 
 /**
  * @param {JsdocVisitor} iterator
- * @param {{
- *   meta: any,
- *   contextDefaults?: true | string[],
- *   contextSelected?: true,
- *   iterateAllJsdocs?: true,
- * }} ruleConfig
+ * @param {RuleConfig} ruleConfig
  */
 export default function iterateJsdoc (iterator, ruleConfig) {
   const metaType = ruleConfig?.meta?.type;

src/jsdocUtils.js

@@ -1295,13 +1295,17 @@ const parseClosureTemplateTag = (tag) => {
     });
 };
 
+/**
+ * @typedef {true|string[]} DefaultContexts
+ */
+
 /**
  * Checks user option for `contexts` array, defaulting to
  *   contexts designated by the rule. Returns an array of
  *   ESTree AST types, indicating allowable contexts.
  *
  * @param {*} context
- * @param {true|string[]} defaultContexts
+ * @param {DefaultContexts} defaultContexts
  * @returns {string[]}
  */
 const enforcedContexts = (context, defaultContexts) => {