eslint-plugin-jsdoc 63.3.3 → 64.0.0

package/dist/rules/requireYieldsCheck.cjs

@@ -1,179 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc.cjs"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-/**
- * @param {import('../iterateJsdoc.js').Utils} utils
- * @param {import('../iterateJsdoc.js').Settings} settings
- * @returns {boolean}
- */
-const canSkip = (utils, settings) => {
-  const voidingTags = [
-  // An abstract function is by definition incomplete
-  // so it is perfectly fine if a yield is documented but
-  // not present within the function.
-  // A subclass may inherit the doc and implement the
-  // missing yield.
-  'abstract', 'virtual',
-  // Constructor functions do not have a yield value
-  //  so we can bail here, too.
-  'class', 'constructor',
-  // This seems to imply a class as well
-  'interface'];
-  if (settings.mode === 'closure') {
-    // Structural Interface in GCC terms, equivalent to @interface tag as far as this rule is concerned
-    voidingTags.push('record');
-  }
-  return utils.hasATag(voidingTags) || utils.isConstructor() || utils.classHasTag('interface') || settings.mode === 'closure' && utils.classHasTag('record');
-};
-
-/**
- * @param {import('../iterateJsdoc.js').Utils} utils
- * @param {import('../iterateJsdoc.js').Report} report
- * @param {string} tagName
- * @returns {[]|[preferredTagName: string, tag: import('comment-parser').Spec]}
- */
-const checkTagName = (utils, report, tagName) => {
-  const preferredTagName = /** @type {string} */utils.getPreferredTagName({
-    tagName
-  });
-  if (!preferredTagName) {
-    return [];
-  }
-  const tags = utils.getTags(preferredTagName);
-  if (tags.length === 0) {
-    return [];
-  }
-  if (tags.length > 1) {
-    report(`Found more than one @${preferredTagName} declaration.`);
-    return [];
-  }
-  return [preferredTagName, tags[0]];
-};
-var _default = exports.default = (0, _iterateJsdoc.default)(({
-  context,
-  report,
-  settings,
-  utils
-}) => {
-  if (canSkip(utils, settings)) {
-    return;
-  }
-  const {
-    checkGeneratorsOnly = false,
-    next = false
-  } = context.options[0] || {};
-  const [preferredYieldTagName, yieldTag] = checkTagName(utils, report, 'yields');
-  if (preferredYieldTagName) {
-    const shouldReportYields = () => {
-      if (/** @type {import('comment-parser').Spec} */yieldTag.type.trim() === 'never') {
-        if (utils.hasYieldValue()) {
-          report(`JSDoc @${preferredYieldTagName} declaration set with "never" but yield expression is present in function.`);
-        }
-        return false;
-      }
-      if (checkGeneratorsOnly && !utils.isGenerator()) {
-        return true;
-      }
-      return !utils.mayBeUndefinedTypeTag(/** @type {import('comment-parser').Spec} */
-      yieldTag) && !utils.hasYieldValue();
-    };
-
-    // In case a yield value is declared in JSDoc, we also expect one in the code.
-    if (shouldReportYields()) {
-      report(`JSDoc @${preferredYieldTagName} declaration present but yield expression not available in function.`);
-    }
-  }
-  if (next) {
-    const [preferredNextTagName, nextTag] = checkTagName(utils, report, 'next');
-    if (preferredNextTagName) {
-      const shouldReportNext = () => {
-        if (/** @type {import('comment-parser').Spec} */nextTag.type.trim() === 'never') {
-          if (utils.hasYieldReturnValue()) {
-            report(`JSDoc @${preferredNextTagName} declaration set with "never" but yield expression with return value is present in function.`);
-          }
-          return false;
-        }
-        if (checkGeneratorsOnly && !utils.isGenerator()) {
-          return true;
-        }
-        return !utils.mayBeUndefinedTypeTag(/** @type {import('comment-parser').Spec} */
-        nextTag) && !utils.hasYieldReturnValue();
-      };
-      if (shouldReportNext()) {
-        report(`JSDoc @${preferredNextTagName} declaration present but yield expression with return value not available in function.`);
-      }
-    }
-  }
-}, {
-  meta: {
-    docs: {
-      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: [{
-      additionalProperties: false,
-      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'
-            }, {
-              additionalProperties: false,
-              properties: {
-                comment: {
-                  type: 'string'
-                },
-                context: {
-                  type: 'string'
-                }
-              },
-              type: 'object'
-            }]
-          },
-          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'
-        }
-      },
-      type: 'object'
-    }],
-    type: 'suggestion'
-  }
-});
-module.exports = exports.default;
-//# sourceMappingURL=requireYieldsCheck.cjs.map

package/dist/rules/requireYieldsCheck.cjs.map

@@ -1 +0,0 @@
-{"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":[]}