eslint-plugin-jsdoc 58.1.1 → 59.0.1

package/dist/rules/requireReturnsCheck.cjs

@@ -80,7 +80,7 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
 }, {
   meta: {
     docs: {
-      description: 'Requires a return statement in function body if a `@returns` tag is specified in jsdoc comment.',
+      description: 'Requires a return statement in function body if a `@returns` tag is specified in JSDoc comment(and reports if multiple `@returns` tags are present).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-check.md#repos-sticky-header'
     },
     schema: [{
@@ -88,13 +88,34 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
       properties: {
         exemptAsync: {
           default: true,
+          description: `By default, functions which return a \`Promise\` that are not
+detected as resolving with a non-\`undefined\` value and \`async\` functions
+(even ones that do not explicitly return a value, as these are returning a
+\`Promise\` implicitly) will be exempted from reporting by this rule.
+If you wish to insist that only \`Promise\`'s which resolve to
+non-\`undefined\` values or \`async\` functions with explicit \`return\`'s will
+be exempted from reporting (i.e., that \`async\` functions can be reported
+if they lack an explicit (non-\`undefined\`) \`return\` when a \`@returns\` is
+present), you can set \`exemptAsync\` to \`false\` on the options object.`,
           type: 'boolean'
         },
         exemptGenerators: {
+          description: `Because a generator might be labeled as having a
+\`IterableIterator\` \`@returns\` value (along with an iterator type
+corresponding to the type of any \`yield\` statements), projects might wish to
+leverage \`@returns\` in generators even without a \`return\` statement. This
+option is therefore \`true\` by default in \`typescript\` mode (in "jsdoc" mode,
+one might be more likely to take advantage of \`@yields\`). Set it to \`false\`
+if you wish for a missing \`return\` to be flagged regardless.`,
           type: 'boolean'
         },
         reportMissingReturnForUndefinedTypes: {
           default: false,
+          description: `If \`true\` and no return or
+resolve value is found, this setting will even insist that reporting occur
+with \`void\` or \`undefined\` (including as an indicated \`Promise\` type).
+Unlike \`require-returns\`, with this option in the rule, one can
+*discourage* the labeling of \`undefined\` types. Defaults to \`false\`.`,
           type: 'boolean'
         }
       },

package/dist/rules/requireReturnsCheck.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"requireReturnsCheck.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","canSkip","utils","settings","voidingTags","mode","push","hasATag","isConstructor","classHasTag","_default","exports","iterateJsdoc","context","node","report","exemptAsync","exemptGenerators","reportMissingReturnForUndefinedTypes","options","isAsync","tagName","getPreferredTagName","tags","getTags","length","tag","type","trim","test","returnNever","hasValueOrExecutorHasNonEmptyResolveValue","mayBeUndefinedTypeTag","Boolean","generator","meta","docs","description","url","schema","additionalProperties","properties","module"],"sources":["../../src/rules/requireReturnsCheck.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\n/**\n * @param {import('../iterateJsdoc.js').Utils} utils\n * @param {import('../iterateJsdoc.js').Settings} settings\n * @returns {boolean}\n */\nconst canSkip = (utils, settings) => {\n  const voidingTags = [\n    // An abstract function is by definition incomplete\n    // so it is perfectly fine if a return is documented but\n    // not present within the function.\n    // A subclass may inherit the doc and implement the\n    // missing return.\n    'abstract',\n    'virtual',\n\n    // A constructor function returns `this` by default, so may be `@returns`\n    //   tag indicating this but no explicit return\n    'class',\n    'constructor',\n    'interface',\n  ];\n\n  if (settings.mode === 'closure') {\n    // Structural Interface in GCC terms, equivalent to @interface tag as far as this rule is concerned\n    voidingTags.push('record');\n  }\n\n  return utils.hasATag(voidingTags) ||\n    utils.isConstructor() ||\n    utils.classHasTag('interface') ||\n    settings.mode === 'closure' && utils.classHasTag('record');\n};\n\nexport default iterateJsdoc(({\n  context,\n  node,\n  report,\n  settings,\n  utils,\n}) => {\n  const {\n    exemptAsync = true,\n    exemptGenerators = settings.mode === 'typescript',\n    reportMissingReturnForUndefinedTypes = false,\n  } = context.options[0] || {};\n\n  if (canSkip(utils, settings)) {\n    return;\n  }\n\n  if (exemptAsync && utils.isAsync()) {\n    return;\n  }\n\n  const tagName = /** @type {string} */ (utils.getPreferredTagName({\n    tagName: 'returns',\n  }));\n  if (!tagName) {\n    return;\n  }\n\n  const tags = utils.getTags(tagName);\n\n  if (tags.length === 0) {\n    return;\n  }\n\n  if (tags.length > 1) {\n    report(`Found more than one @${tagName} declaration.`);\n\n    return;\n  }\n\n  const [\n    tag,\n  ] = tags;\n\n  const type = tag.type.trim();\n\n  // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n  if (/asserts\\s/v.test(type)) {\n    return;\n  }\n\n  const returnNever = type === 'never';\n\n  if (returnNever && utils.hasValueOrExecutorHasNonEmptyResolveValue(false)) {\n    report(`JSDoc @${tagName} declaration set with \"never\" but return expression is present in function.`);\n\n    return;\n  }\n\n  // In case a return value is declared in JSDoc, we also expect one in the code.\n  if (\n    !returnNever &&\n    (\n      reportMissingReturnForUndefinedTypes ||\n      !utils.mayBeUndefinedTypeTag(tag)\n    ) &&\n    (tag.type === '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(\n      exemptAsync,\n    ) ||\n    tag.type !== '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(\n      exemptAsync,\n      true,\n    )) &&\n    Boolean(\n      !exemptGenerators || !node ||\n      !('generator' in /** @type {import('../iterateJsdoc.js').Node} */ (node)) ||\n      !(/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */ (node)).generator,\n    )\n  ) {\n    report(`JSDoc @${tagName} declaration present but return expression not available in function.`);\n  }\n}, {\n  meta: {\n    docs: {\n      description: 'Requires a return statement in function body if a `@returns` tag is specified in jsdoc comment.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-check.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          exemptAsync: {\n            default: true,\n            type: 'boolean',\n          },\n          exemptGenerators: {\n            type: 'boolean',\n          },\n          reportMissingReturnForUndefinedTypes: {\n            default: false,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"requireReturnsCheck.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","canSkip","utils","settings","voidingTags","mode","push","hasATag","isConstructor","classHasTag","_default","exports","iterateJsdoc","context","node","report","exemptAsync","exemptGenerators","reportMissingReturnForUndefinedTypes","options","isAsync","tagName","getPreferredTagName","tags","getTags","length","tag","type","trim","test","returnNever","hasValueOrExecutorHasNonEmptyResolveValue","mayBeUndefinedTypeTag","Boolean","generator","meta","docs","description","url","schema","additionalProperties","properties","module"],"sources":["../../src/rules/requireReturnsCheck.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\n/**\n * @param {import('../iterateJsdoc.js').Utils} utils\n * @param {import('../iterateJsdoc.js').Settings} settings\n * @returns {boolean}\n */\nconst canSkip = (utils, settings) => {\n  const voidingTags = [\n    // An abstract function is by definition incomplete\n    // so it is perfectly fine if a return is documented but\n    // not present within the function.\n    // A subclass may inherit the doc and implement the\n    // missing return.\n    'abstract',\n    'virtual',\n\n    // A constructor function returns `this` by default, so may be `@returns`\n    //   tag indicating this but no explicit return\n    'class',\n    'constructor',\n    'interface',\n  ];\n\n  if (settings.mode === 'closure') {\n    // Structural Interface in GCC terms, equivalent to @interface tag as far as this rule is concerned\n    voidingTags.push('record');\n  }\n\n  return utils.hasATag(voidingTags) ||\n    utils.isConstructor() ||\n    utils.classHasTag('interface') ||\n    settings.mode === 'closure' && utils.classHasTag('record');\n};\n\nexport default iterateJsdoc(({\n  context,\n  node,\n  report,\n  settings,\n  utils,\n}) => {\n  const {\n    exemptAsync = true,\n    exemptGenerators = settings.mode === 'typescript',\n    reportMissingReturnForUndefinedTypes = false,\n  } = context.options[0] || {};\n\n  if (canSkip(utils, settings)) {\n    return;\n  }\n\n  if (exemptAsync && utils.isAsync()) {\n    return;\n  }\n\n  const tagName = /** @type {string} */ (utils.getPreferredTagName({\n    tagName: 'returns',\n  }));\n  if (!tagName) {\n    return;\n  }\n\n  const tags = utils.getTags(tagName);\n\n  if (tags.length === 0) {\n    return;\n  }\n\n  if (tags.length > 1) {\n    report(`Found more than one @${tagName} declaration.`);\n\n    return;\n  }\n\n  const [\n    tag,\n  ] = tags;\n\n  const type = tag.type.trim();\n\n  // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n  if (/asserts\\s/v.test(type)) {\n    return;\n  }\n\n  const returnNever = type === 'never';\n\n  if (returnNever && utils.hasValueOrExecutorHasNonEmptyResolveValue(false)) {\n    report(`JSDoc @${tagName} declaration set with \"never\" but return expression is present in function.`);\n\n    return;\n  }\n\n  // In case a return value is declared in JSDoc, we also expect one in the code.\n  if (\n    !returnNever &&\n    (\n      reportMissingReturnForUndefinedTypes ||\n      !utils.mayBeUndefinedTypeTag(tag)\n    ) &&\n    (tag.type === '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(\n      exemptAsync,\n    ) ||\n    tag.type !== '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(\n      exemptAsync,\n      true,\n    )) &&\n    Boolean(\n      !exemptGenerators || !node ||\n      !('generator' in /** @type {import('../iterateJsdoc.js').Node} */ (node)) ||\n      !(/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */ (node)).generator,\n    )\n  ) {\n    report(`JSDoc @${tagName} declaration present but return expression not available in function.`);\n  }\n}, {\n  meta: {\n    docs: {\n      description: 'Requires a return statement in function body if a `@returns` tag is specified in JSDoc comment(and reports if multiple `@returns` tags are present).',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-check.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          exemptAsync: {\n            default: true,\n            description: `By default, functions which return a \\`Promise\\` that are not\ndetected as resolving with a non-\\`undefined\\` value and \\`async\\` functions\n(even ones that do not explicitly return a value, as these are returning a\n\\`Promise\\` implicitly) will be exempted from reporting by this rule.\nIf you wish to insist that only \\`Promise\\`'s which resolve to\nnon-\\`undefined\\` values or \\`async\\` functions with explicit \\`return\\`'s will\nbe exempted from reporting (i.e., that \\`async\\` functions can be reported\nif they lack an explicit (non-\\`undefined\\`) \\`return\\` when a \\`@returns\\` is\npresent), you can set \\`exemptAsync\\` to \\`false\\` on the options object.`,\n            type: 'boolean',\n          },\n          exemptGenerators: {\n            description: `Because a generator might be labeled as having a\n\\`IterableIterator\\` \\`@returns\\` value (along with an iterator type\ncorresponding to the type of any \\`yield\\` statements), projects might wish to\nleverage \\`@returns\\` in generators even without a \\`return\\` statement. This\noption is therefore \\`true\\` by default in \\`typescript\\` mode (in \"jsdoc\" mode,\none might be more likely to take advantage of \\`@yields\\`). Set it to \\`false\\`\nif you wish for a missing \\`return\\` to be flagged regardless.`,\n            type: 'boolean',\n          },\n          reportMissingReturnForUndefinedTypes: {\n            default: false,\n            description: `If \\`true\\` and no return or\nresolve value is found, this setting will even insist that reporting occur\nwith \\`void\\` or \\`undefined\\` (including as an indicated \\`Promise\\` type).\nUnlike \\`require-returns\\`, with this option in the rule, one can\n*discourage* the labeling of \\`undefined\\` types. Defaults to \\`false\\`.`,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}

package/dist/rules/requireReturnsDescription.cjs

@@ -23,13 +23,27 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
   contextDefaults: true,
   meta: {
     docs: {
-      description: 'Requires that the `@returns` tag has a `description` value.',
+      description: 'Requires that the `@returns` tag has a `description` value (not including `void`/`undefined` type returns).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-description.md#repos-sticky-header'
     },
     schema: [{
       additionalProperties: false,
       properties: {
         contexts: {
+          description: `Set this to an array of strings representing the AST context (or an object with
+optional \`context\` and \`comment\` properties) where you wish the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`).
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
           items: {
             anyOf: [{
               type: 'string'

package/dist/rules/requireReturnsDescription.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"requireReturnsDescription.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","_default","exports","iterateJsdoc","report","utils","forEachPreferredTag","jsdocTag","targetTagName","type","trim","includes","description","contextDefaults","meta","docs","url","schema","additionalProperties","properties","contexts","items","anyOf","comment","context","module"],"sources":["../../src/rules/requireReturnsDescription.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n  report,\n  utils,\n}) => {\n  utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {\n    const type = jsdocTag.type && jsdocTag.type.trim();\n\n    if ([\n      'Promise<undefined>', 'Promise<void>', 'undefined', 'void',\n    ].includes(type)) {\n      return;\n    }\n\n    if (!jsdocTag.description.trim()) {\n      report(`Missing JSDoc @${targetTagName} description.`, null, jsdocTag);\n    }\n  });\n}, {\n  contextDefaults: true,\n  meta: {\n    docs: {\n      description: 'Requires that the `@returns` tag has a `description` value.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-description.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          contexts: {\n            items: {\n              anyOf: [\n                {\n                  type: 'string',\n                },\n                {\n                  additionalProperties: false,\n                  properties: {\n                    comment: {\n                      type: 'string',\n                    },\n                    context: {\n                      type: 'string',\n                    },\n                  },\n                  type: 'object',\n                },\n              ],\n            },\n            type: 'array',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":";;;;;;AAAA,IAAAA,aAAA,GAAAC,sBAAA,CAAAC,OAAA;AAA8C,SAAAD,uBAAAE,CAAA,WAAAA,CAAA,IAAAA,CAAA,CAAAC,UAAA,GAAAD,CAAA,KAAAE,OAAA,EAAAF,CAAA;AAAA,IAAAG,QAAA,GAAAC,OAAA,CAAAF,OAAA,GAE/B,IAAAG,qBAAY,EAAC,CAAC;EAC3BC,MAAM;EACNC;AACF,CAAC,KAAK;EACJA,KAAK,CAACC,mBAAmB,CAAC,SAAS,EAAE,CAACC,QAAQ,EAAEC,aAAa,KAAK;IAChE,MAAMC,IAAI,GAAGF,QAAQ,CAACE,IAAI,IAAIF,QAAQ,CAACE,IAAI,CAACC,IAAI,CAAC,CAAC;IAElD,IAAI,CACF,oBAAoB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,CAC3D,CAACC,QAAQ,CAACF,IAAI,CAAC,EAAE;MAChB;IACF;IAEA,IAAI,CAACF,QAAQ,CAACK,WAAW,CAACF,IAAI,CAAC,CAAC,EAAE;MAChCN,MAAM,CAAC,kBAAkBI,aAAa,eAAe,EAAE,IAAI,EAAED,QAAQ,CAAC;IACxE;EACF,CAAC,CAAC;AACJ,CAAC,EAAE;EACDM,eAAe,EAAE,IAAI;EACrBC,IAAI,EAAE;IACJC,IAAI,EAAE;MACJH,WAAW,EAAE,6DAA6D;MAC1EI,GAAG,EAAE;IACP,CAAC;IACDC,MAAM,EAAE,CACN;MACEC,oBAAoB,EAAE,KAAK;MAC3BC,UAAU,EAAE;QACVC,QAAQ,EAAE;UACRC,KAAK,EAAE;YACLC,KAAK,EAAE,CACL;cACEb,IAAI,EAAE;YACR,CAAC,EACD;cACES,oBAAoB,EAAE,KAAK;cAC3BC,UAAU,EAAE;gBACVI,OAAO,EAAE;kBACPd,IAAI,EAAE;gBACR,CAAC;gBACDe,OAAO,EAAE;kBACPf,IAAI,EAAE;gBACR;cACF,CAAC;cACDA,IAAI,EAAE;YACR,CAAC;UAEL,CAAC;UACDA,IAAI,EAAE;QACR;MACF,CAAC;MACDA,IAAI,EAAE;IACR,CAAC,CACF;IACDA,IAAI,EAAE;EACR;AACF,CAAC,CAAC;AAAAgB,MAAA,CAAAvB,OAAA,GAAAA,OAAA,CAAAF,OAAA","ignoreList":[]}
+{"version":3,"file":"requireReturnsDescription.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","_default","exports","iterateJsdoc","report","utils","forEachPreferredTag","jsdocTag","targetTagName","type","trim","includes","description","contextDefaults","meta","docs","url","schema","additionalProperties","properties","contexts","items","anyOf","comment","context","module"],"sources":["../../src/rules/requireReturnsDescription.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n  report,\n  utils,\n}) => {\n  utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {\n    const type = jsdocTag.type && jsdocTag.type.trim();\n\n    if ([\n      'Promise<undefined>', 'Promise<void>', 'undefined', 'void',\n    ].includes(type)) {\n      return;\n    }\n\n    if (!jsdocTag.description.trim()) {\n      report(`Missing JSDoc @${targetTagName} description.`, null, jsdocTag);\n    }\n  });\n}, {\n  contextDefaults: true,\n  meta: {\n    docs: {\n      description: 'Requires that the `@returns` tag has a `description` value (not including `void`/`undefined` type returns).',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-description.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          contexts: {\n            description: `Set this to an array of strings representing the AST context (or an object with\noptional \\`context\\` and \\`comment\\` properties) where you wish the rule to be applied.\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`). Set to \\`\"any\"\\` if you want\nthe rule to apply to any JSDoc block throughout your files (as is necessary\nfor finding function blocks not attached to a function declaration or\nexpression, i.e., \\`@callback\\` or \\`@function\\` (or its aliases \\`@func\\` or\n\\`@method\\`) (including those associated with an \\`@interface\\`).\n\nSee the [\"AST and Selectors\"](../#advanced-ast-and-selectors)\nsection of our Advanced docs for more on the expected format.`,\n            items: {\n              anyOf: [\n                {\n                  type: 'string',\n                },\n                {\n                  additionalProperties: false,\n                  properties: {\n                    comment: {\n                      type: 'string',\n                    },\n                    context: {\n                      type: 'string',\n                    },\n                  },\n                  type: 'object',\n                },\n              ],\n            },\n            type: 'array',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":";;;;;;AAAA,IAAAA,aAAA,GAAAC,sBAAA,CAAAC,OAAA;AAA8C,SAAAD,uBAAAE,CAAA,WAAAA,CAAA,IAAAA,CAAA,CAAAC,UAAA,GAAAD,CAAA,KAAAE,OAAA,EAAAF,CAAA;AAAA,IAAAG,QAAA,GAAAC,OAAA,CAAAF,OAAA,GAE/B,IAAAG,qBAAY,EAAC,CAAC;EAC3BC,MAAM;EACNC;AACF,CAAC,KAAK;EACJA,KAAK,CAACC,mBAAmB,CAAC,SAAS,EAAE,CAACC,QAAQ,EAAEC,aAAa,KAAK;IAChE,MAAMC,IAAI,GAAGF,QAAQ,CAACE,IAAI,IAAIF,QAAQ,CAACE,IAAI,CAACC,IAAI,CAAC,CAAC;IAElD,IAAI,CACF,oBAAoB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,CAC3D,CAACC,QAAQ,CAACF,IAAI,CAAC,EAAE;MAChB;IACF;IAEA,IAAI,CAACF,QAAQ,CAACK,WAAW,CAACF,IAAI,CAAC,CAAC,EAAE;MAChCN,MAAM,CAAC,kBAAkBI,aAAa,eAAe,EAAE,IAAI,EAAED,QAAQ,CAAC;IACxE;EACF,CAAC,CAAC;AACJ,CAAC,EAAE;EACDM,eAAe,EAAE,IAAI;EACrBC,IAAI,EAAE;IACJC,IAAI,EAAE;MACJH,WAAW,EAAE,6GAA6G;MAC1HI,GAAG,EAAE;IACP,CAAC;IACDC,MAAM,EAAE,CACN;MACEC,oBAAoB,EAAE,KAAK;MAC3BC,UAAU,EAAE;QACVC,QAAQ,EAAE;UACRR,WAAW,EAAE;AACzB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,8DAA8D;UAClDS,KAAK,EAAE;YACLC,KAAK,EAAE,CACL;cACEb,IAAI,EAAE;YACR,CAAC,EACD;cACES,oBAAoB,EAAE,KAAK;cAC3BC,UAAU,EAAE;gBACVI,OAAO,EAAE;kBACPd,IAAI,EAAE;gBACR,CAAC;gBACDe,OAAO,EAAE;kBACPf,IAAI,EAAE;gBACR;cACF,CAAC;cACDA,IAAI,EAAE;YACR,CAAC;UAEL,CAAC;UACDA,IAAI,EAAE;QACR;MACF,CAAC;MACDA,IAAI,EAAE;IACR,CAAC,CACF;IACDA,IAAI,EAAE;EACR;AACF,CAAC,CAAC;AAAAgB,MAAA,CAAAvB,OAAA,GAAAA,OAAA,CAAAF,OAAA","ignoreList":[]}

package/dist/rules/requireReturnsType.cjs

@@ -19,13 +19,27 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
   contextDefaults: true,
   meta: {
     docs: {
-      description: 'Requires that `@returns` tag has `type` value.',
+      description: 'Requires that `@returns` tag has type value (in curly brackets).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-type.md#repos-sticky-header'
     },
     schema: [{
       additionalProperties: false,
       properties: {
         contexts: {
+          description: `Set this to an array of strings representing the AST context (or an object with
+optional \`context\` and \`comment\` properties) where you wish the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`).
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
           items: {
             anyOf: [{
               type: 'string'

package/dist/rules/requireReturnsType.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"requireReturnsType.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","_default","exports","iterateJsdoc","report","utils","forEachPreferredTag","jsdocTag","targetTagName","type","contextDefaults","meta","docs","description","url","schema","additionalProperties","properties","contexts","items","anyOf","comment","context","module"],"sources":["../../src/rules/requireReturnsType.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n  report,\n  utils,\n}) => {\n  utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {\n    if (!jsdocTag.type) {\n      report(`Missing JSDoc @${targetTagName} type.`, null, jsdocTag);\n    }\n  });\n}, {\n  contextDefaults: true,\n  meta: {\n    docs: {\n      description: 'Requires that `@returns` tag has `type` value.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-type.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          contexts: {\n            items: {\n              anyOf: [\n                {\n                  type: 'string',\n                },\n                {\n                  additionalProperties: false,\n                  properties: {\n                    comment: {\n                      type: 'string',\n                    },\n                    context: {\n                      type: 'string',\n                    },\n                  },\n                  type: 'object',\n                },\n              ],\n            },\n            type: 'array',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":";;;;;;AAAA,IAAAA,aAAA,GAAAC,sBAAA,CAAAC,OAAA;AAA8C,SAAAD,uBAAAE,CAAA,WAAAA,CAAA,IAAAA,CAAA,CAAAC,UAAA,GAAAD,CAAA,KAAAE,OAAA,EAAAF,CAAA;AAAA,IAAAG,QAAA,GAAAC,OAAA,CAAAF,OAAA,GAE/B,IAAAG,qBAAY,EAAC,CAAC;EAC3BC,MAAM;EACNC;AACF,CAAC,KAAK;EACJA,KAAK,CAACC,mBAAmB,CAAC,SAAS,EAAE,CAACC,QAAQ,EAAEC,aAAa,KAAK;IAChE,IAAI,CAACD,QAAQ,CAACE,IAAI,EAAE;MAClBL,MAAM,CAAC,kBAAkBI,aAAa,QAAQ,EAAE,IAAI,EAAED,QAAQ,CAAC;IACjE;EACF,CAAC,CAAC;AACJ,CAAC,EAAE;EACDG,eAAe,EAAE,IAAI;EACrBC,IAAI,EAAE;IACJC,IAAI,EAAE;MACJC,WAAW,EAAE,gDAAgD;MAC7DC,GAAG,EAAE;IACP,CAAC;IACDC,MAAM,EAAE,CACN;MACEC,oBAAoB,EAAE,KAAK;MAC3BC,UAAU,EAAE;QACVC,QAAQ,EAAE;UACRC,KAAK,EAAE;YACLC,KAAK,EAAE,CACL;cACEX,IAAI,EAAE;YACR,CAAC,EACD;cACEO,oBAAoB,EAAE,KAAK;cAC3BC,UAAU,EAAE;gBACVI,OAAO,EAAE;kBACPZ,IAAI,EAAE;gBACR,CAAC;gBACDa,OAAO,EAAE;kBACPb,IAAI,EAAE;gBACR;cACF,CAAC;cACDA,IAAI,EAAE;YACR,CAAC;UAEL,CAAC;UACDA,IAAI,EAAE;QACR;MACF,CAAC;MACDA,IAAI,EAAE;IACR,CAAC,CACF;IACDA,IAAI,EAAE;EACR;AACF,CAAC,CAAC;AAAAc,MAAA,CAAArB,OAAA,GAAAA,OAAA,CAAAF,OAAA","ignoreList":[]}
+{"version":3,"file":"requireReturnsType.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","_default","exports","iterateJsdoc","report","utils","forEachPreferredTag","jsdocTag","targetTagName","type","contextDefaults","meta","docs","description","url","schema","additionalProperties","properties","contexts","items","anyOf","comment","context","module"],"sources":["../../src/rules/requireReturnsType.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n  report,\n  utils,\n}) => {\n  utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {\n    if (!jsdocTag.type) {\n      report(`Missing JSDoc @${targetTagName} type.`, null, jsdocTag);\n    }\n  });\n}, {\n  contextDefaults: true,\n  meta: {\n    docs: {\n      description: 'Requires that `@returns` tag has type value (in curly brackets).',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-type.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          contexts: {\n            description: `Set this to an array of strings representing the AST context (or an object with\noptional \\`context\\` and \\`comment\\` properties) where you wish the rule to be applied.\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`). Set to \\`\"any\"\\` if you want\nthe rule to apply to any JSDoc block throughout your files (as is necessary\nfor finding function blocks not attached to a function declaration or\nexpression, i.e., \\`@callback\\` or \\`@function\\` (or its aliases \\`@func\\` or\n\\`@method\\`) (including those associated with an \\`@interface\\`).\n\nSee the [\"AST and Selectors\"](../#advanced-ast-and-selectors)\nsection of our Advanced docs for more on the expected format.`,\n            items: {\n              anyOf: [\n                {\n                  type: 'string',\n                },\n                {\n                  additionalProperties: false,\n                  properties: {\n                    comment: {\n                      type: 'string',\n                    },\n                    context: {\n                      type: 'string',\n                    },\n                  },\n                  type: 'object',\n                },\n              ],\n            },\n            type: 'array',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":";;;;;;AAAA,IAAAA,aAAA,GAAAC,sBAAA,CAAAC,OAAA;AAA8C,SAAAD,uBAAAE,CAAA,WAAAA,CAAA,IAAAA,CAAA,CAAAC,UAAA,GAAAD,CAAA,KAAAE,OAAA,EAAAF,CAAA;AAAA,IAAAG,QAAA,GAAAC,OAAA,CAAAF,OAAA,GAE/B,IAAAG,qBAAY,EAAC,CAAC;EAC3BC,MAAM;EACNC;AACF,CAAC,KAAK;EACJA,KAAK,CAACC,mBAAmB,CAAC,SAAS,EAAE,CAACC,QAAQ,EAAEC,aAAa,KAAK;IAChE,IAAI,CAACD,QAAQ,CAACE,IAAI,EAAE;MAClBL,MAAM,CAAC,kBAAkBI,aAAa,QAAQ,EAAE,IAAI,EAAED,QAAQ,CAAC;IACjE;EACF,CAAC,CAAC;AACJ,CAAC,EAAE;EACDG,eAAe,EAAE,IAAI;EACrBC,IAAI,EAAE;IACJC,IAAI,EAAE;MACJC,WAAW,EAAE,kEAAkE;MAC/EC,GAAG,EAAE;IACP,CAAC;IACDC,MAAM,EAAE,CACN;MACEC,oBAAoB,EAAE,KAAK;MAC3BC,UAAU,EAAE;QACVC,QAAQ,EAAE;UACRL,WAAW,EAAE;AACzB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,8DAA8D;UAClDM,KAAK,EAAE;YACLC,KAAK,EAAE,CACL;cACEX,IAAI,EAAE;YACR,CAAC,EACD;cACEO,oBAAoB,EAAE,KAAK;cAC3BC,UAAU,EAAE;gBACVI,OAAO,EAAE;kBACPZ,IAAI,EAAE;gBACR,CAAC;gBACDa,OAAO,EAAE;kBACPb,IAAI,EAAE;gBACR;cACF,CAAC;cACDA,IAAI,EAAE;YACR,CAAC;UAEL,CAAC;UACDA,IAAI,EAAE;QACR;MACF,CAAC;MACDA,IAAI,EAAE;IACR,CAAC,CACF;IACDA,IAAI,EAAE;EACR;AACF,CAAC,CAAC;AAAAc,MAAA,CAAArB,OAAA,GAAAA,OAAA,CAAAF,OAAA","ignoreList":[]}

package/dist/rules/requireTemplate.cjs

@@ -166,19 +166,35 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Requires template tags for each generic type parameter',
+      description: 'Requires `@template` tags be present when type parameters are used.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-template.md#repos-sticky-header'
     },
     schema: [{
       additionalProperties: false,
       properties: {
         exemptedBy: {
+          description: `Array of tags (e.g., \`['type']\`) whose presence on the document
+block avoids the need for a \`@template\`. Defaults to an array with
+\`inheritdoc\`. If you set this array, it will overwrite the default,
+so be sure to add back \`inheritdoc\` if you wish its presence to cause
+exemption of the rule.`,
           items: {
             type: 'string'
           },
           type: 'array'
         },
         requireSeparateTemplates: {
+          description: `Requires that each template have its own separate line, i.e., preventing
+templates of this format:
+
+\`\`\`js
+/**
+ * @template T, U, V
+ */
+\`\`\`
+
+Defaults to \`false\`.
+`,
           type: 'boolean'
         }
       },

package/dist/rules/requireTemplate.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"requireTemplate.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","_jsdoccomment","e","__esModule","default","_default","exports","iterateJsdoc","context","node","report","settings","utils","avoidDocs","requireSeparateTemplates","options","mode","usedNames","Set","templateTags","getTags","templateNames","flatMap","tag","parseClosureTemplateTag","names","length","checkTypeParams","aliasDeclaration","params","typeParameters","name","add","usedName","includes","handleTypes","nde","type","declaration","usedNameToTag","Map","checkForUsedTypes","potentialTag","parsedType","tryParseType","parseType","traverse","value","test","has","set","checkTagsAndTemplates","tagNames","tagName","preferredTagName","getPreferredTagName","matchingTags","matchingTag","get","callbackTags","functionTags","typedefTags","potentialTypedef","iterateAllJsdocs","meta","docs","description","url","schema","additionalProperties","properties","exemptedBy","items","module"],"sources":["../../src/rules/requireTemplate.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport {\n  parse as parseType,\n  traverse,\n  tryParse as tryParseType,\n} from '@es-joy/jsdoccomment';\n\nexport default iterateJsdoc(({\n  context,\n  node,\n  report,\n  settings,\n  utils,\n}) => {\n  if (utils.avoidDocs()) {\n    return;\n  }\n\n  const {\n    requireSeparateTemplates = false,\n  } = context.options[0] || {};\n\n  const {\n    mode,\n  } = settings;\n\n  const usedNames = new Set();\n  const templateTags = utils.getTags('template');\n  const templateNames = templateTags.flatMap((tag) => {\n    return utils.parseClosureTemplateTag(tag);\n  });\n\n  if (requireSeparateTemplates) {\n    for (const tag of templateTags) {\n      const names = utils.parseClosureTemplateTag(tag);\n      if (names.length > 1) {\n        report(`Missing separate @template for ${names[1]}`, null, tag);\n      }\n    }\n  }\n\n  /**\n   * @param {import('@typescript-eslint/types').TSESTree.FunctionDeclaration|\n   *   import('@typescript-eslint/types').TSESTree.ClassDeclaration|\n   *   import('@typescript-eslint/types').TSESTree.TSDeclareFunction|\n   *   import('@typescript-eslint/types').TSESTree.TSInterfaceDeclaration|\n   *   import('@typescript-eslint/types').TSESTree.TSTypeAliasDeclaration} aliasDeclaration\n   */\n  const checkTypeParams = (aliasDeclaration) => {\n    const {\n      params,\n      /* c8 ignore next -- Guard */\n    } = aliasDeclaration.typeParameters ?? {\n      /* c8 ignore next -- Guard */\n      params: [],\n    };\n    for (const {\n      name: {\n        name,\n      },\n    } of params) {\n      usedNames.add(name);\n    }\n\n    for (const usedName of usedNames) {\n      if (!templateNames.includes(usedName)) {\n        report(`Missing @template ${usedName}`);\n      }\n    }\n  };\n\n  const handleTypes = () => {\n    const nde = /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (\n      node\n    );\n    if (!nde) {\n      return;\n    }\n\n    switch (nde.type) {\n      case 'ClassDeclaration':\n      case 'FunctionDeclaration':\n      case 'TSDeclareFunction':\n      case 'TSInterfaceDeclaration':\n      case 'TSTypeAliasDeclaration':\n        checkTypeParams(nde);\n        break;\n      case 'ExportDefaultDeclaration':\n        switch (nde.declaration?.type) {\n          case 'ClassDeclaration':\n          case 'FunctionDeclaration':\n          case 'TSInterfaceDeclaration':\n            checkTypeParams(nde.declaration);\n            break;\n        }\n\n        break;\n      case 'ExportNamedDeclaration':\n        switch (nde.declaration?.type) {\n          case 'ClassDeclaration':\n          case 'FunctionDeclaration':\n          case 'TSDeclareFunction':\n          case 'TSInterfaceDeclaration':\n          case 'TSTypeAliasDeclaration':\n            checkTypeParams(nde.declaration);\n            break;\n        }\n\n        break;\n    }\n  };\n\n  const usedNameToTag = new Map();\n\n  /**\n   * @param {import('comment-parser').Spec} potentialTag\n   */\n  const checkForUsedTypes = (potentialTag) => {\n    let parsedType;\n    try {\n      parsedType = mode === 'permissive' ?\n        tryParseType(/** @type {string} */ (potentialTag.type)) :\n        parseType(/** @type {string} */ (potentialTag.type), mode);\n    } catch {\n      return;\n    }\n\n    traverse(parsedType, (nde) => {\n      const {\n        type,\n        value,\n      } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);\n      if (type === 'JsdocTypeName' && (/^[A-Z]$/v).test(value)) {\n        usedNames.add(value);\n        if (!usedNameToTag.has(value)) {\n          usedNameToTag.set(value, potentialTag);\n        }\n      }\n    });\n  };\n\n  /**\n   * @param {string[]} tagNames\n   */\n  const checkTagsAndTemplates = (tagNames) => {\n    for (const tagName of tagNames) {\n      const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({\n        tagName,\n      }));\n      const matchingTags = utils.getTags(preferredTagName);\n      for (const matchingTag of matchingTags) {\n        checkForUsedTypes(matchingTag);\n      }\n    }\n\n    // Could check against whitelist/blacklist\n    for (const usedName of usedNames) {\n      if (!templateNames.includes(usedName)) {\n        report(`Missing @template ${usedName}`, null, usedNameToTag.get(usedName));\n      }\n    }\n  };\n\n  const callbackTags = utils.getTags('callback');\n  const functionTags = utils.getTags('function');\n  if (callbackTags.length || functionTags.length) {\n    checkTagsAndTemplates([\n      'param', 'returns',\n    ]);\n    return;\n  }\n\n  const typedefTags = utils.getTags('typedef');\n  if (!typedefTags.length || typedefTags.length >= 2) {\n    handleTypes();\n    return;\n  }\n\n  const potentialTypedef = typedefTags[0];\n  checkForUsedTypes(potentialTypedef);\n\n  checkTagsAndTemplates([\n    'property',\n  ]);\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Requires template tags for each generic type parameter',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-template.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          exemptedBy: {\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          requireSeparateTemplates: {\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"requireTemplate.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","_jsdoccomment","e","__esModule","default","_default","exports","iterateJsdoc","context","node","report","settings","utils","avoidDocs","requireSeparateTemplates","options","mode","usedNames","Set","templateTags","getTags","templateNames","flatMap","tag","parseClosureTemplateTag","names","length","checkTypeParams","aliasDeclaration","params","typeParameters","name","add","usedName","includes","handleTypes","nde","type","declaration","usedNameToTag","Map","checkForUsedTypes","potentialTag","parsedType","tryParseType","parseType","traverse","value","test","has","set","checkTagsAndTemplates","tagNames","tagName","preferredTagName","getPreferredTagName","matchingTags","matchingTag","get","callbackTags","functionTags","typedefTags","potentialTypedef","iterateAllJsdocs","meta","docs","description","url","schema","additionalProperties","properties","exemptedBy","items","module"],"sources":["../../src/rules/requireTemplate.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport {\n  parse as parseType,\n  traverse,\n  tryParse as tryParseType,\n} from '@es-joy/jsdoccomment';\n\nexport default iterateJsdoc(({\n  context,\n  node,\n  report,\n  settings,\n  utils,\n}) => {\n  if (utils.avoidDocs()) {\n    return;\n  }\n\n  const {\n    requireSeparateTemplates = false,\n  } = context.options[0] || {};\n\n  const {\n    mode,\n  } = settings;\n\n  const usedNames = new Set();\n  const templateTags = utils.getTags('template');\n  const templateNames = templateTags.flatMap((tag) => {\n    return utils.parseClosureTemplateTag(tag);\n  });\n\n  if (requireSeparateTemplates) {\n    for (const tag of templateTags) {\n      const names = utils.parseClosureTemplateTag(tag);\n      if (names.length > 1) {\n        report(`Missing separate @template for ${names[1]}`, null, tag);\n      }\n    }\n  }\n\n  /**\n   * @param {import('@typescript-eslint/types').TSESTree.FunctionDeclaration|\n   *   import('@typescript-eslint/types').TSESTree.ClassDeclaration|\n   *   import('@typescript-eslint/types').TSESTree.TSDeclareFunction|\n   *   import('@typescript-eslint/types').TSESTree.TSInterfaceDeclaration|\n   *   import('@typescript-eslint/types').TSESTree.TSTypeAliasDeclaration} aliasDeclaration\n   */\n  const checkTypeParams = (aliasDeclaration) => {\n    const {\n      params,\n      /* c8 ignore next -- Guard */\n    } = aliasDeclaration.typeParameters ?? {\n      /* c8 ignore next -- Guard */\n      params: [],\n    };\n    for (const {\n      name: {\n        name,\n      },\n    } of params) {\n      usedNames.add(name);\n    }\n\n    for (const usedName of usedNames) {\n      if (!templateNames.includes(usedName)) {\n        report(`Missing @template ${usedName}`);\n      }\n    }\n  };\n\n  const handleTypes = () => {\n    const nde = /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (\n      node\n    );\n    if (!nde) {\n      return;\n    }\n\n    switch (nde.type) {\n      case 'ClassDeclaration':\n      case 'FunctionDeclaration':\n      case 'TSDeclareFunction':\n      case 'TSInterfaceDeclaration':\n      case 'TSTypeAliasDeclaration':\n        checkTypeParams(nde);\n        break;\n      case 'ExportDefaultDeclaration':\n        switch (nde.declaration?.type) {\n          case 'ClassDeclaration':\n          case 'FunctionDeclaration':\n          case 'TSInterfaceDeclaration':\n            checkTypeParams(nde.declaration);\n            break;\n        }\n\n        break;\n      case 'ExportNamedDeclaration':\n        switch (nde.declaration?.type) {\n          case 'ClassDeclaration':\n          case 'FunctionDeclaration':\n          case 'TSDeclareFunction':\n          case 'TSInterfaceDeclaration':\n          case 'TSTypeAliasDeclaration':\n            checkTypeParams(nde.declaration);\n            break;\n        }\n\n        break;\n    }\n  };\n\n  const usedNameToTag = new Map();\n\n  /**\n   * @param {import('comment-parser').Spec} potentialTag\n   */\n  const checkForUsedTypes = (potentialTag) => {\n    let parsedType;\n    try {\n      parsedType = mode === 'permissive' ?\n        tryParseType(/** @type {string} */ (potentialTag.type)) :\n        parseType(/** @type {string} */ (potentialTag.type), mode);\n    } catch {\n      return;\n    }\n\n    traverse(parsedType, (nde) => {\n      const {\n        type,\n        value,\n      } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);\n      if (type === 'JsdocTypeName' && (/^[A-Z]$/v).test(value)) {\n        usedNames.add(value);\n        if (!usedNameToTag.has(value)) {\n          usedNameToTag.set(value, potentialTag);\n        }\n      }\n    });\n  };\n\n  /**\n   * @param {string[]} tagNames\n   */\n  const checkTagsAndTemplates = (tagNames) => {\n    for (const tagName of tagNames) {\n      const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({\n        tagName,\n      }));\n      const matchingTags = utils.getTags(preferredTagName);\n      for (const matchingTag of matchingTags) {\n        checkForUsedTypes(matchingTag);\n      }\n    }\n\n    // Could check against whitelist/blacklist\n    for (const usedName of usedNames) {\n      if (!templateNames.includes(usedName)) {\n        report(`Missing @template ${usedName}`, null, usedNameToTag.get(usedName));\n      }\n    }\n  };\n\n  const callbackTags = utils.getTags('callback');\n  const functionTags = utils.getTags('function');\n  if (callbackTags.length || functionTags.length) {\n    checkTagsAndTemplates([\n      'param', 'returns',\n    ]);\n    return;\n  }\n\n  const typedefTags = utils.getTags('typedef');\n  if (!typedefTags.length || typedefTags.length >= 2) {\n    handleTypes();\n    return;\n  }\n\n  const potentialTypedef = typedefTags[0];\n  checkForUsedTypes(potentialTypedef);\n\n  checkTagsAndTemplates([\n    'property',\n  ]);\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Requires `@template` tags be present when type parameters are used.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-template.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          exemptedBy: {\n            description: `Array of tags (e.g., \\`['type']\\`) whose presence on the document\nblock avoids the need for a \\`@template\\`. Defaults to an array with\n\\`inheritdoc\\`. If you set this array, it will overwrite the default,\nso be sure to add back \\`inheritdoc\\` if you wish its presence to cause\nexemption of the rule.`,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          requireSeparateTemplates: {\n            description: `Requires that each template have its own separate line, i.e., preventing\ntemplates of this format:\n\n\\`\\`\\`js\n/**\n * @template T, U, V\n */\n\\`\\`\\`\n\nDefaults to \\`false\\`.\n`,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}

package/dist/rules/requireThrows.cjs

@@ -60,13 +60,25 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
   contextDefaults: true,
   meta: {
     docs: {
-      description: 'Requires that throw statements are documented.',
+      description: 'Requires that throw statements are documented with `@throws` tags.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-throws.md#repos-sticky-header'
     },
     schema: [{
       additionalProperties: false,
       properties: {
         contexts: {
+          description: `Set this to an array of strings representing the AST context
+(or objects with optional \`context\` and \`comment\` properties) where you wish
+the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`).`,
           items: {
             anyOf: [{
               type: 'string'
@@ -86,6 +98,11 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
           type: 'array'
         },
         exemptedBy: {
+          description: `Array of tags (e.g., \`['type']\`) whose presence on the
+document block avoids the need for a \`@throws\`. Defaults to an array
+with \`inheritdoc\`. If you set this array, it will overwrite the default,
+so be sure to add back \`inheritdoc\` if you wish its presence to cause
+exemption of the rule.`,
           items: {
             type: 'string'
           },

package/dist/rules/requireThrows.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"requireThrows.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","canSkip","utils","hasATag","avoidDocs","_default","exports","iterateJsdoc","report","tagName","getPreferredTagName","tags","getTags","iteratingFunction","isIteratingFunction","tag","missingThrowsTag","shouldReport","type","trim","hasThrowValue","contextDefaults","meta","docs","description","url","schema","additionalProperties","properties","contexts","items","anyOf","comment","context","exemptedBy","module"],"sources":["../../src/rules/requireThrows.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\n/**\n * We can skip checking for a throws value, in case the documentation is inherited\n * or the method is either a constructor or an abstract method.\n * @param {import('../iterateJsdoc.js').Utils} utils a reference to the utils which are used to probe if a tag is present or not.\n * @returns {boolean} true in case deep checking can be skipped; otherwise false.\n */\nconst canSkip = (utils) => {\n  return utils.hasATag([\n    // inheritdoc implies that all documentation is inherited\n    // see https://jsdoc.app/tags-inheritdoc.html\n    //\n    // Abstract methods are by definition incomplete,\n    // so it is not necessary to document that they throw an error.\n    'abstract',\n    'virtual',\n\n    // The designated type can itself document `@throws`\n    'type',\n  ]) ||\n    utils.avoidDocs();\n};\n\nexport default iterateJsdoc(({\n  report,\n  utils,\n}) => {\n  // A preflight check. We do not need to run a deep check for abstract\n  //  functions.\n  if (canSkip(utils)) {\n    return;\n  }\n\n  const tagName = /** @type {string} */ (utils.getPreferredTagName({\n    tagName: 'throws',\n  }));\n  if (!tagName) {\n    return;\n  }\n\n  const tags = utils.getTags(tagName);\n  const iteratingFunction = utils.isIteratingFunction();\n\n  // In case the code returns something, we expect a return value in JSDoc.\n  const [\n    tag,\n  ] = tags;\n  const missingThrowsTag = typeof tag === 'undefined' || tag === null;\n\n  const shouldReport = () => {\n    if (!missingThrowsTag) {\n      if (tag.type.trim() === 'never' && iteratingFunction && utils.hasThrowValue()) {\n        report(`JSDoc @${tagName} declaration set to \"never\" but throw value found.`);\n      }\n\n      return false;\n    }\n\n    return iteratingFunction && utils.hasThrowValue();\n  };\n\n  if (shouldReport()) {\n    report(`Missing JSDoc @${tagName} declaration.`);\n  }\n}, {\n  contextDefaults: true,\n  meta: {\n    docs: {\n      description: 'Requires that throw statements are documented.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-throws.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          contexts: {\n            items: {\n              anyOf: [\n                {\n                  type: 'string',\n                },\n                {\n                  additionalProperties: false,\n                  properties: {\n                    comment: {\n                      type: 'string',\n                    },\n                    context: {\n                      type: 'string',\n                    },\n                  },\n                  type: 'object',\n                },\n              ],\n            },\n            type: 'array',\n          },\n          exemptedBy: {\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":";;;;;;AAAA,IAAAA,aAAA,GAAAC,sBAAA,CAAAC,OAAA;AAA8C,SAAAD,uBAAAE,CAAA,WAAAA,CAAA,IAAAA,CAAA,CAAAC,UAAA,GAAAD,CAAA,KAAAE,OAAA,EAAAF,CAAA;AAE9C;AACA;AACA;AACA;AACA;AACA;AACA,MAAMG,OAAO,GAAIC,KAAK,IAAK;EACzB,OAAOA,KAAK,CAACC,OAAO,CAAC;EACnB;EACA;EACA;EACA;EACA;EACA,UAAU,EACV,SAAS;EAET;EACA,MAAM,CACP,CAAC,IACAD,KAAK,CAACE,SAAS,CAAC,CAAC;AACrB,CAAC;AAAC,IAAAC,QAAA,GAAAC,OAAA,CAAAN,OAAA,GAEa,IAAAO,qBAAY,EAAC,CAAC;EAC3BC,MAAM;EACNN;AACF,CAAC,KAAK;EACJ;EACA;EACA,IAAID,OAAO,CAACC,KAAK,CAAC,EAAE;IAClB;EACF;EAEA,MAAMO,OAAO,GAAG,qBAAuBP,KAAK,CAACQ,mBAAmB,CAAC;IAC/DD,OAAO,EAAE;EACX,CAAC,CAAE;EACH,IAAI,CAACA,OAAO,EAAE;IACZ;EACF;EAEA,MAAME,IAAI,GAAGT,KAAK,CAACU,OAAO,CAACH,OAAO,CAAC;EACnC,MAAMI,iBAAiB,GAAGX,KAAK,CAACY,mBAAmB,CAAC,CAAC;;EAErD;EACA,MAAM,CACJC,GAAG,CACJ,GAAGJ,IAAI;EACR,MAAMK,gBAAgB,GAAG,OAAOD,GAAG,KAAK,WAAW,IAAIA,GAAG,KAAK,IAAI;EAEnE,MAAME,YAAY,GAAGA,CAAA,KAAM;IACzB,IAAI,CAACD,gBAAgB,EAAE;MACrB,IAAID,GAAG,CAACG,IAAI,CAACC,IAAI,CAAC,CAAC,KAAK,OAAO,IAAIN,iBAAiB,IAAIX,KAAK,CAACkB,aAAa,CAAC,CAAC,EAAE;QAC7EZ,MAAM,CAAC,UAAUC,OAAO,oDAAoD,CAAC;MAC/E;MAEA,OAAO,KAAK;IACd;IAEA,OAAOI,iBAAiB,IAAIX,KAAK,CAACkB,aAAa,CAAC,CAAC;EACnD,CAAC;EAED,IAAIH,YAAY,CAAC,CAAC,EAAE;IAClBT,MAAM,CAAC,kBAAkBC,OAAO,eAAe,CAAC;EAClD;AACF,CAAC,EAAE;EACDY,eAAe,EAAE,IAAI;EACrBC,IAAI,EAAE;IACJC,IAAI,EAAE;MACJC,WAAW,EAAE,gDAAgD;MAC7DC,GAAG,EAAE;IACP,CAAC;IACDC,MAAM,EAAE,CACN;MACEC,oBAAoB,EAAE,KAAK;MAC3BC,UAAU,EAAE;QACVC,QAAQ,EAAE;UACRC,KAAK,EAAE;YACLC,KAAK,EAAE,CACL;cACEb,IAAI,EAAE;YACR,CAAC,EACD;cACES,oBAAoB,EAAE,KAAK;cAC3BC,UAAU,EAAE;gBACVI,OAAO,EAAE;kBACPd,IAAI,EAAE;gBACR,CAAC;gBACDe,OAAO,EAAE;kBACPf,IAAI,EAAE;gBACR;cACF,CAAC;cACDA,IAAI,EAAE;YACR,CAAC;UAEL,CAAC;UACDA,IAAI,EAAE;QACR,CAAC;QACDgB,UAAU,EAAE;UACVJ,KAAK,EAAE;YACLZ,IAAI,EAAE;UACR,CAAC;UACDA,IAAI,EAAE;QACR;MACF,CAAC;MACDA,IAAI,EAAE;IACR,CAAC,CACF;IACDA,IAAI,EAAE;EACR;AACF,CAAC,CAAC;AAAAiB,MAAA,CAAA7B,OAAA,GAAAA,OAAA,CAAAN,OAAA","ignoreList":[]}
+{"version":3,"file":"requireThrows.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","canSkip","utils","hasATag","avoidDocs","_default","exports","iterateJsdoc","report","tagName","getPreferredTagName","tags","getTags","iteratingFunction","isIteratingFunction","tag","missingThrowsTag","shouldReport","type","trim","hasThrowValue","contextDefaults","meta","docs","description","url","schema","additionalProperties","properties","contexts","items","anyOf","comment","context","exemptedBy","module"],"sources":["../../src/rules/requireThrows.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\n/**\n * We can skip checking for a throws value, in case the documentation is inherited\n * or the method is either a constructor or an abstract method.\n * @param {import('../iterateJsdoc.js').Utils} utils a reference to the utils which are used to probe if a tag is present or not.\n * @returns {boolean} true in case deep checking can be skipped; otherwise false.\n */\nconst canSkip = (utils) => {\n  return utils.hasATag([\n    // inheritdoc implies that all documentation is inherited\n    // see https://jsdoc.app/tags-inheritdoc.html\n    //\n    // Abstract methods are by definition incomplete,\n    // so it is not necessary to document that they throw an error.\n    'abstract',\n    'virtual',\n\n    // The designated type can itself document `@throws`\n    'type',\n  ]) ||\n    utils.avoidDocs();\n};\n\nexport default iterateJsdoc(({\n  report,\n  utils,\n}) => {\n  // A preflight check. We do not need to run a deep check for abstract\n  //  functions.\n  if (canSkip(utils)) {\n    return;\n  }\n\n  const tagName = /** @type {string} */ (utils.getPreferredTagName({\n    tagName: 'throws',\n  }));\n  if (!tagName) {\n    return;\n  }\n\n  const tags = utils.getTags(tagName);\n  const iteratingFunction = utils.isIteratingFunction();\n\n  // In case the code returns something, we expect a return value in JSDoc.\n  const [\n    tag,\n  ] = tags;\n  const missingThrowsTag = typeof tag === 'undefined' || tag === null;\n\n  const shouldReport = () => {\n    if (!missingThrowsTag) {\n      if (tag.type.trim() === 'never' && iteratingFunction && utils.hasThrowValue()) {\n        report(`JSDoc @${tagName} declaration set to \"never\" but throw value found.`);\n      }\n\n      return false;\n    }\n\n    return iteratingFunction && utils.hasThrowValue();\n  };\n\n  if (shouldReport()) {\n    report(`Missing JSDoc @${tagName} declaration.`);\n  }\n}, {\n  contextDefaults: true,\n  meta: {\n    docs: {\n      description: 'Requires that throw statements are documented with `@throws` tags.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-throws.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          contexts: {\n            description: `Set this to an array of strings representing the AST context\n(or objects with optional \\`context\\` and \\`comment\\` properties) where you wish\nthe rule to be applied.\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`). Set to \\`\"any\"\\` if you want\nthe rule to apply to any JSDoc block throughout your files (as is necessary\nfor finding function blocks not attached to a function declaration or\nexpression, i.e., \\`@callback\\` or \\`@function\\` (or its aliases \\`@func\\` or\n\\`@method\\`) (including those associated with an \\`@interface\\`).`,\n            items: {\n              anyOf: [\n                {\n                  type: 'string',\n                },\n                {\n                  additionalProperties: false,\n                  properties: {\n                    comment: {\n                      type: 'string',\n                    },\n                    context: {\n                      type: 'string',\n                    },\n                  },\n                  type: 'object',\n                },\n              ],\n            },\n            type: 'array',\n          },\n          exemptedBy: {\n            description: `Array of tags (e.g., \\`['type']\\`) whose presence on the\ndocument block avoids the need for a \\`@throws\\`. Defaults to an array\nwith \\`inheritdoc\\`. If you set this array, it will overwrite the default,\nso be sure to add back \\`inheritdoc\\` if you wish its presence to cause\nexemption of the rule.`,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}

package/dist/rules/requireYields.cjs

@@ -114,13 +114,30 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
   contextDefaults: true,
   meta: {
     docs: {
-      description: 'Requires yields are documented.',
+      description: 'Requires yields are documented with `@yields` tags.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields.md#repos-sticky-header'
     },
     schema: [{
       additionalProperties: false,
       properties: {
         contexts: {
+          description: `Set this to an array of strings representing the AST context
+(or objects with optional \`context\` and \`comment\` properties) where you wish
+the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`). This
+rule will only apply on non-default contexts when there is such a tag
+present and the \`forceRequireYields\` option is set or if the
+\`withGeneratorTag\` option is set with a present \`@generator\` tag
+(since we are not checking against the actual \`yield\` values in these
+cases).`,
           items: {
             anyOf: [{
               type: 'string'
@@ -140,6 +157,11 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
           type: 'array'
         },
         exemptedBy: {
+          description: `Array of tags (e.g., \`['type']\`) whose presence on the
+document block avoids the need for a \`@yields\`. Defaults to an array
+with \`inheritdoc\`. If you set this array, it will overwrite the default,
+so be sure to add back \`inheritdoc\` if you wish its presence to cause
+exemption of the rule.`,
           items: {
             type: 'string'
           },
@@ -147,22 +169,49 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
         },
         forceRequireNext: {
           default: false,
+          description: `Set to \`true\` to always insist on
+\`@next\` documentation even if there are no \`yield\` statements in the
+function or none return values. May be desired to flag that a project is
+aware of the expected yield return being \`undefined\`. Defaults to \`false\`.`,
           type: 'boolean'
         },
         forceRequireYields: {
           default: false,
+          description: `Set to \`true\` to always insist on
+\`@yields\` documentation for generators even if there are only
+expressionless \`yield\` statements in the function. May be desired to flag
+that a project is aware of an \`undefined\`/\`void\` yield. Defaults to
+\`false\`.`,
           type: 'boolean'
         },
         next: {
           default: false,
+          description: `If \`true\`, this option will insist that any use of a \`yield\` return
+value (e.g., \`const rv = yield;\` or \`const rv = yield value;\`) has a
+(non-standard) \`@next\` tag (in addition to any \`@yields\` tag) so as to be
+able to document the type expected to be supplied into the iterator
+(the \`Generator\` iterator that is returned by the call to the generator
+function) to the iterator (e.g., \`it.next(value)\`). The tag will not be
+expected if the generator function body merely has plain \`yield;\` or
+\`yield value;\` statements without returning the values. Defaults to
+\`false\`.`,
           type: 'boolean'
         },
         nextWithGeneratorTag: {
           default: false,
+          description: `If a \`@generator\` tag is present on a block, require
+(non-standard ) \`@next\` (see \`next\` option). This will require using \`void\`
+or \`undefined\` in cases where generators do not use the \`next()\`-supplied
+incoming \`yield\`-returned value. Defaults to \`false\`. See \`contexts\` to
+\`any\` if you want to catch \`@generator\` with \`@callback\` or such not
+attached to a function.`,
           type: 'boolean'
         },
         withGeneratorTag: {
           default: true,
+          description: `If a \`@generator\` tag is present on a block, require
+\`@yields\`/\`@yield\`. Defaults to \`true\`. See \`contexts\` to \`any\` if you want
+to catch \`@generator\` with \`@callback\` or such not attached to a function.`,
           type: 'boolean'
         }
       },

package/dist/rules/requireYields.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"requireYields.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","canSkip","utils","hasATag","avoidDocs","checkTagName","report","tagName","preferredTagName","getPreferredTagName","tags","getTags","length","tag","missingTag","_default","exports","iterateJsdoc","context","forceRequireNext","forceRequireYields","next","nextWithGeneratorTag","withGeneratorTag","options","iteratingFunction","isIteratingFunction","preferredYieldTagName","missingYieldTag","shouldReportYields","hasTag","isGenerator","hasYieldValue","preferredNextTagName","missingNextTag","shouldReportNext","hasYieldReturnValue","contextDefaults","meta","docs","description","url","schema","additionalProperties","properties","contexts","items","anyOf","type","comment","exemptedBy","module"],"sources":["../../src/rules/requireYields.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\n/**\n * We can skip checking for a yield value, in case the documentation is inherited\n * or the method has a constructor or abstract tag.\n *\n * In either of these cases the yield value is optional or not defined.\n * @param {import('../iterateJsdoc.js').Utils} utils a reference to the utils which are used to probe if a tag is present or not.\n * @returns {boolean} true in case deep checking can be skipped; otherwise false.\n */\nconst canSkip = (utils) => {\n  return utils.hasATag([\n    // inheritdoc implies that all documentation is inherited\n    // see https://jsdoc.app/tags-inheritdoc.html\n    //\n    // Abstract methods are by definition incomplete,\n    // so it is not an error if it declares a yield value but does not implement it.\n    'abstract',\n    'virtual',\n\n    // Constructors do not have a yield value\n    // so we can bail out here, too.\n    'class',\n    'constructor',\n\n    // Yield (and any `next`) type is specified accompanying the targeted\n    //   @type\n    'type',\n\n    // This seems to imply a class as well\n    'interface',\n  ]) ||\n    utils.avoidDocs();\n};\n\n/**\n * @param {import('../iterateJsdoc.js').Utils} utils\n * @param {import('../iterateJsdoc.js').Report} report\n * @param {string} tagName\n * @returns {[preferredTagName?: string, missingTag?: boolean]}\n */\nconst checkTagName = (utils, report, tagName) => {\n  const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({\n    tagName,\n  }));\n  if (!preferredTagName) {\n    return [];\n  }\n\n  const tags = utils.getTags(preferredTagName);\n\n  if (tags.length > 1) {\n    report(`Found more than one @${preferredTagName} declaration.`);\n  }\n\n  // In case the code yields something, we expect a yields value in JSDoc.\n  const [\n    tag,\n  ] = tags;\n  const missingTag = typeof tag === 'undefined' || tag === null;\n\n  return [\n    preferredTagName, missingTag,\n  ];\n};\n\nexport default iterateJsdoc(({\n  context,\n  report,\n  utils,\n}) => {\n  const {\n    forceRequireNext = false,\n    forceRequireYields = false,\n    next = false,\n    nextWithGeneratorTag = false,\n    withGeneratorTag = true,\n  } = context.options[0] || {};\n\n  // A preflight check. We do not need to run a deep check\n  // in case the @yield comment is optional or undefined.\n  if (canSkip(utils)) {\n    return;\n  }\n\n  const iteratingFunction = utils.isIteratingFunction();\n\n  const [\n    preferredYieldTagName,\n    missingYieldTag,\n  ] = checkTagName(\n    utils, report, 'yields',\n  );\n  if (preferredYieldTagName) {\n    const shouldReportYields = () => {\n      if (!missingYieldTag) {\n        return false;\n      }\n\n      if (\n        withGeneratorTag && utils.hasTag('generator') ||\n        forceRequireYields && iteratingFunction && utils.isGenerator()\n      ) {\n        return true;\n      }\n\n      return iteratingFunction && utils.isGenerator() && utils.hasYieldValue();\n    };\n\n    if (shouldReportYields()) {\n      report(`Missing JSDoc @${preferredYieldTagName} declaration.`);\n    }\n  }\n\n  if (next || nextWithGeneratorTag || forceRequireNext) {\n    const [\n      preferredNextTagName,\n      missingNextTag,\n    ] = checkTagName(\n      utils, report, 'next',\n    );\n    if (!preferredNextTagName) {\n      return;\n    }\n\n    const shouldReportNext = () => {\n      if (!missingNextTag) {\n        return false;\n      }\n\n      if (\n        nextWithGeneratorTag && utils.hasTag('generator')) {\n        return true;\n      }\n\n      if (\n        !next && !forceRequireNext ||\n        !iteratingFunction ||\n        !utils.isGenerator()\n      ) {\n        return false;\n      }\n\n      return forceRequireNext || utils.hasYieldReturnValue();\n    };\n\n    if (shouldReportNext()) {\n      report(`Missing JSDoc @${preferredNextTagName} declaration.`);\n    }\n  }\n}, {\n  contextDefaults: true,\n  meta: {\n    docs: {\n      description: 'Requires yields are documented.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          contexts: {\n            items: {\n              anyOf: [\n                {\n                  type: 'string',\n                },\n                {\n                  additionalProperties: false,\n                  properties: {\n                    comment: {\n                      type: 'string',\n                    },\n                    context: {\n                      type: 'string',\n                    },\n                  },\n                  type: 'object',\n                },\n              ],\n            },\n            type: 'array',\n          },\n          exemptedBy: {\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          forceRequireNext: {\n            default: false,\n            type: 'boolean',\n          },\n          forceRequireYields: {\n            default: false,\n            type: 'boolean',\n          },\n          next: {\n            default: false,\n            type: 'boolean',\n          },\n          nextWithGeneratorTag: {\n            default: false,\n            type: 'boolean',\n          },\n          withGeneratorTag: {\n            default: true,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"requireYields.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","canSkip","utils","hasATag","avoidDocs","checkTagName","report","tagName","preferredTagName","getPreferredTagName","tags","getTags","length","tag","missingTag","_default","exports","iterateJsdoc","context","forceRequireNext","forceRequireYields","next","nextWithGeneratorTag","withGeneratorTag","options","iteratingFunction","isIteratingFunction","preferredYieldTagName","missingYieldTag","shouldReportYields","hasTag","isGenerator","hasYieldValue","preferredNextTagName","missingNextTag","shouldReportNext","hasYieldReturnValue","contextDefaults","meta","docs","description","url","schema","additionalProperties","properties","contexts","items","anyOf","type","comment","exemptedBy","module"],"sources":["../../src/rules/requireYields.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\n/**\n * We can skip checking for a yield value, in case the documentation is inherited\n * or the method has a constructor or abstract tag.\n *\n * In either of these cases the yield value is optional or not defined.\n * @param {import('../iterateJsdoc.js').Utils} utils a reference to the utils which are used to probe if a tag is present or not.\n * @returns {boolean} true in case deep checking can be skipped; otherwise false.\n */\nconst canSkip = (utils) => {\n  return utils.hasATag([\n    // inheritdoc implies that all documentation is inherited\n    // see https://jsdoc.app/tags-inheritdoc.html\n    //\n    // Abstract methods are by definition incomplete,\n    // so it is not an error if it declares a yield value but does not implement it.\n    'abstract',\n    'virtual',\n\n    // Constructors do not have a yield value\n    // so we can bail out here, too.\n    'class',\n    'constructor',\n\n    // Yield (and any `next`) type is specified accompanying the targeted\n    //   @type\n    'type',\n\n    // This seems to imply a class as well\n    'interface',\n  ]) ||\n    utils.avoidDocs();\n};\n\n/**\n * @param {import('../iterateJsdoc.js').Utils} utils\n * @param {import('../iterateJsdoc.js').Report} report\n * @param {string} tagName\n * @returns {[preferredTagName?: string, missingTag?: boolean]}\n */\nconst checkTagName = (utils, report, tagName) => {\n  const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({\n    tagName,\n  }));\n  if (!preferredTagName) {\n    return [];\n  }\n\n  const tags = utils.getTags(preferredTagName);\n\n  if (tags.length > 1) {\n    report(`Found more than one @${preferredTagName} declaration.`);\n  }\n\n  // In case the code yields something, we expect a yields value in JSDoc.\n  const [\n    tag,\n  ] = tags;\n  const missingTag = typeof tag === 'undefined' || tag === null;\n\n  return [\n    preferredTagName, missingTag,\n  ];\n};\n\nexport default iterateJsdoc(({\n  context,\n  report,\n  utils,\n}) => {\n  const {\n    forceRequireNext = false,\n    forceRequireYields = false,\n    next = false,\n    nextWithGeneratorTag = false,\n    withGeneratorTag = true,\n  } = context.options[0] || {};\n\n  // A preflight check. We do not need to run a deep check\n  // in case the @yield comment is optional or undefined.\n  if (canSkip(utils)) {\n    return;\n  }\n\n  const iteratingFunction = utils.isIteratingFunction();\n\n  const [\n    preferredYieldTagName,\n    missingYieldTag,\n  ] = checkTagName(\n    utils, report, 'yields',\n  );\n  if (preferredYieldTagName) {\n    const shouldReportYields = () => {\n      if (!missingYieldTag) {\n        return false;\n      }\n\n      if (\n        withGeneratorTag && utils.hasTag('generator') ||\n        forceRequireYields && iteratingFunction && utils.isGenerator()\n      ) {\n        return true;\n      }\n\n      return iteratingFunction && utils.isGenerator() && utils.hasYieldValue();\n    };\n\n    if (shouldReportYields()) {\n      report(`Missing JSDoc @${preferredYieldTagName} declaration.`);\n    }\n  }\n\n  if (next || nextWithGeneratorTag || forceRequireNext) {\n    const [\n      preferredNextTagName,\n      missingNextTag,\n    ] = checkTagName(\n      utils, report, 'next',\n    );\n    if (!preferredNextTagName) {\n      return;\n    }\n\n    const shouldReportNext = () => {\n      if (!missingNextTag) {\n        return false;\n      }\n\n      if (\n        nextWithGeneratorTag && utils.hasTag('generator')) {\n        return true;\n      }\n\n      if (\n        !next && !forceRequireNext ||\n        !iteratingFunction ||\n        !utils.isGenerator()\n      ) {\n        return false;\n      }\n\n      return forceRequireNext || utils.hasYieldReturnValue();\n    };\n\n    if (shouldReportNext()) {\n      report(`Missing JSDoc @${preferredNextTagName} declaration.`);\n    }\n  }\n}, {\n  contextDefaults: true,\n  meta: {\n    docs: {\n      description: 'Requires yields are documented with `@yields` tags.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          contexts: {\n            description: `Set this to an array of strings representing the AST context\n(or objects with optional \\`context\\` and \\`comment\\` properties) where you wish\nthe rule to be applied.\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`). Set to \\`\"any\"\\` if you want\nthe rule to apply to any JSDoc block throughout your files (as is necessary\nfor finding function blocks not attached to a function declaration or\nexpression, i.e., \\`@callback\\` or \\`@function\\` (or its aliases \\`@func\\` or\n\\`@method\\`) (including those associated with an \\`@interface\\`). This\nrule will only apply on non-default contexts when there is such a tag\npresent and the \\`forceRequireYields\\` option is set or if the\n\\`withGeneratorTag\\` option is set with a present \\`@generator\\` tag\n(since we are not checking against the actual \\`yield\\` values in these\ncases).`,\n            items: {\n              anyOf: [\n                {\n                  type: 'string',\n                },\n                {\n                  additionalProperties: false,\n                  properties: {\n                    comment: {\n                      type: 'string',\n                    },\n                    context: {\n                      type: 'string',\n                    },\n                  },\n                  type: 'object',\n                },\n              ],\n            },\n            type: 'array',\n          },\n          exemptedBy: {\n            description: `Array of tags (e.g., \\`['type']\\`) whose presence on the\ndocument block avoids the need for a \\`@yields\\`. Defaults to an array\nwith \\`inheritdoc\\`. If you set this array, it will overwrite the default,\nso be sure to add back \\`inheritdoc\\` if you wish its presence to cause\nexemption of the rule.`,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          forceRequireNext: {\n            default: false,\n            description: `Set to \\`true\\` to always insist on\n\\`@next\\` documentation even if there are no \\`yield\\` statements in the\nfunction or none return values. May be desired to flag that a project is\naware of the expected yield return being \\`undefined\\`. Defaults to \\`false\\`.`,\n            type: 'boolean',\n          },\n          forceRequireYields: {\n            default: false,\n            description: `Set to \\`true\\` to always insist on\n\\`@yields\\` documentation for generators even if there are only\nexpressionless \\`yield\\` statements in the function. May be desired to flag\nthat a project is aware of an \\`undefined\\`/\\`void\\` yield. Defaults to\n\\`false\\`.`,\n            type: 'boolean',\n          },\n          next: {\n            default: false,\n            description: `If \\`true\\`, this option will insist that any use of a \\`yield\\` return\nvalue (e.g., \\`const rv = yield;\\` or \\`const rv = yield value;\\`) has a\n(non-standard) \\`@next\\` tag (in addition to any \\`@yields\\` tag) so as to be\nable to document the type expected to be supplied into the iterator\n(the \\`Generator\\` iterator that is returned by the call to the generator\nfunction) to the iterator (e.g., \\`it.next(value)\\`). The tag will not be\nexpected if the generator function body merely has plain \\`yield;\\` or\n\\`yield value;\\` statements without returning the values. Defaults to\n\\`false\\`.`,\n            type: 'boolean',\n          },\n          nextWithGeneratorTag: {\n            default: false,\n            description: `If a \\`@generator\\` tag is present on a block, require\n(non-standard ) \\`@next\\` (see \\`next\\` option). This will require using \\`void\\`\nor \\`undefined\\` in cases where generators do not use the \\`next()\\`-supplied\nincoming \\`yield\\`-returned value. Defaults to \\`false\\`. See \\`contexts\\` to\n\\`any\\` if you want to catch \\`@generator\\` with \\`@callback\\` or such not\nattached to a function.`,\n            type: 'boolean',\n          },\n          withGeneratorTag: {\n            default: true,\n            description: `If a \\`@generator\\` tag is present on a block, require\n\\`@yields\\`/\\`@yield\\`. Defaults to \\`true\\`. See \\`contexts\\` to \\`any\\` if you want\nto catch \\`@generator\\` with \\`@callback\\` or such not attached to a function.`,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}

package/dist/rules/requireYieldsCheck.cjs

@@ -112,7 +112,7 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
 }, {
   meta: {
     docs: {
-      description: 'Requires a yield statement in function body if a `@yields` tag is specified in jsdoc comment.',
+      description: 'Ensures that if a `@yields` is present that a `yield` (or `yield` with a value) is present in the function body (or that if a `@next` is present that there is a yield with a return value present).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-check.md#repos-sticky-header'
     },
     schema: [{
@@ -120,9 +120,22 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
       properties: {
         checkGeneratorsOnly: {
           default: false,
+          description: `Avoids checking the function body and merely insists
+that all generators have \`@yields\`. This can be an optimization with the
+ESLint \`require-yield\` rule, as that rule already ensures a \`yield\` is
+present in generators, albeit assuming the generator is not empty).
+Defaults to \`false\`.`,
           type: 'boolean'
         },
         contexts: {
+          description: `Set this to an array of strings representing the AST context
+(or objects with optional \`context\` and \`comment\` properties) where you wish
+the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`).`,
           items: {
             anyOf: [{
               type: 'string'
@@ -141,14 +154,19 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
           },
           type: 'array'
         },
-        exemptedBy: {
-          items: {
-            type: 'string'
-          },
-          type: 'array'
-        },
         next: {
           default: false,
+          description: `If \`true\`, this option will insist that any use of a (non-standard)
+\`@next\` tag (in addition to any \`@yields\` tag) will be matched by a \`yield\`
+which uses a return value in the body of the generator (e.g.,
+\`const rv = yield;\` or \`const rv = yield value;\`). This (non-standard)
+tag is intended to be used to indicate a type and/or description of
+the value expected to be supplied by the user when supplied to the iterator
+by its \`next\` method, as with \`it.next(value)\` (with the iterator being
+the \`Generator\` iterator that is returned by the call to the generator
+function). This option will report an error if the generator function body
+merely has plain \`yield;\` or \`yield value;\` statements without returning
+the values. Defaults to \`false\`.`,
           type: 'boolean'
         }
       },