eslint-plugin-jsdoc/dist/rules/requireYields.cjs.map

JSDoc linting rules for ESLint.

{"version":3,"file":"requireYields.cjs","names":["iterateJsdoc"],"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":[]}