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

JSDoc linting rules for ESLint.

{"version":3,"file":"requireYieldsCheck.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/requireYieldsCheck.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 yield is documented but\n    // not present within the function.\n    // A subclass may inherit the doc and implement the\n    // missing yield.\n    'abstract',\n    'virtual',\n\n    // Constructor functions do not have a yield value\n    //  so we can bail here, too.\n    'class',\n    'constructor',\n\n    // This seems to imply a class as well\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\n/**\n * @param {import('../iterateJsdoc.js').Utils} utils\n * @param {import('../iterateJsdoc.js').Report} report\n * @param {string} tagName\n * @returns {[]|[preferredTagName: string, tag: import('comment-parser').Spec]}\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 === 0) {\n    return [];\n  }\n\n  if (tags.length > 1) {\n    report(`Found more than one @${preferredTagName} declaration.`);\n\n    return [];\n  }\n\n  return [\n    preferredTagName, tags[0],\n  ];\n};\n\nexport default iterateJsdoc(({\n  context,\n  report,\n  settings,\n  utils,\n}) => {\n  if (canSkip(utils, settings)) {\n    return;\n  }\n\n  const {\n    checkGeneratorsOnly = false,\n    next = false,\n  } = context.options[0] || {};\n\n  const [\n    preferredYieldTagName,\n    yieldTag,\n  ] = checkTagName(\n    utils, report, 'yields',\n  );\n  if (preferredYieldTagName) {\n    const shouldReportYields = () => {\n      if (\n        /** @type {import('comment-parser').Spec} */ (\n          yieldTag\n        ).type.trim() === 'never'\n      ) {\n        if (utils.hasYieldValue()) {\n          report(`JSDoc @${preferredYieldTagName} declaration set with \"never\" but yield expression is present in function.`);\n        }\n\n        return false;\n      }\n\n      if (checkGeneratorsOnly && !utils.isGenerator()) {\n        return true;\n      }\n\n      return !utils.mayBeUndefinedTypeTag(\n        /** @type {import('comment-parser').Spec} */\n        (yieldTag),\n      ) && !utils.hasYieldValue();\n    };\n\n    // In case a yield value is declared in JSDoc, we also expect one in the code.\n    if (shouldReportYields()) {\n      report(`JSDoc @${preferredYieldTagName} declaration present but yield expression not available in function.`);\n    }\n  }\n\n  if (next) {\n    const [\n      preferredNextTagName,\n      nextTag,\n    ] = checkTagName(\n      utils, report, 'next',\n    );\n    if (preferredNextTagName) {\n      const shouldReportNext = () => {\n        if (\n          /** @type {import('comment-parser').Spec} */ (\n            nextTag\n          ).type.trim() === 'never'\n        ) {\n          if (utils.hasYieldReturnValue()) {\n            report(`JSDoc @${preferredNextTagName} declaration set with \"never\" but yield expression with return value is present in function.`);\n          }\n\n          return false;\n        }\n\n        if (checkGeneratorsOnly && !utils.isGenerator()) {\n          return true;\n        }\n\n        return !utils.mayBeUndefinedTypeTag(\n          /** @type {import('comment-parser').Spec} */\n          (nextTag),\n        ) && !utils.hasYieldReturnValue();\n      };\n\n      if (shouldReportNext()) {\n        report(`JSDoc @${preferredNextTagName} declaration present but yield expression with return value not available in function.`);\n      }\n    }\n  }\n}, {\n  meta: {\n    docs: {\n      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).',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-check.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          checkGeneratorsOnly: {\n            default: false,\n            description: `Avoids checking the function body and merely insists\nthat all generators have \\`@yields\\`. This can be an optimization with the\nESLint \\`require-yield\\` rule, as that rule already ensures a \\`yield\\` is\npresent in generators, albeit assuming the generator is not empty).\nDefaults to \\`false\\`.`,\n            type: 'boolean',\n          },\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\\`).`,\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          next: {\n            default: false,\n            description: `If \\`true\\`, this option will insist that any use of a (non-standard)\n\\`@next\\` tag (in addition to any \\`@yields\\` tag) will be matched by a \\`yield\\`\nwhich uses a return value in the body of the generator (e.g.,\n\\`const rv = yield;\\` or \\`const rv = yield value;\\`). This (non-standard)\ntag is intended to be used to indicate a type and/or description of\nthe value expected to be supplied by the user when supplied to the iterator\nby its \\`next\\` method, as with \\`it.next(value)\\` (with the iterator being\nthe \\`Generator\\` iterator that is returned by the call to the generator\nfunction). This option will report an error if the generator function body\nmerely has plain \\`yield;\\` or \\`yield value;\\` statements without returning\nthe values. 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":[]}