{"record":{"id":"db8cf0981785d0f1","repo":"oxc-project/oxc","slug":"missing-jsdoc-yields-declaration-for-generator","errorCode":null,"errorMessage":"Missing JSDoc `@yields` declaration for generator function.","messagePattern":"Missing JSDoc `@yields` declaration for generator function\\.","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/jsdoc/require_yields.rs","lineNumber":23,"sourceCode":"use oxc_macros::declare_oxc_lint;\nuse oxc_semantic::{JSDoc, JSDocTag};\nuse oxc_span::Span;\nuse schemars::JsonSchema;\nuse serde::Deserialize;\n\nuse crate::{\n    AstNode,\n    context::LintContext,\n    rule::{DefaultRuleConfig, Rule},\n    utils::{\n        get_function_nearest_jsdoc_node, is_duplicated_special_tag, is_missing_special_tag,\n        should_ignore_as_avoid, should_ignore_as_custom_skip, should_ignore_as_internal,\n        should_ignore_as_private,\n    },\n};\n\nfn missing_yields(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Missing JSDoc `@yields` declaration for generator function.\")\n        .with_help(\"Add `@yields` tag to the JSDoc comment.\")\n        .with_label(span)\n}\n\nfn duplicate_yields(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Duplicate `@yields` tags.\")\n        .with_help(\"Remove redundant `@yields` tag.\")\n        .with_label(span)\n}\n\nfn missing_yields_with_generator(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"`@yields` tag is required when using `@generator` tag.\")\n        .with_help(\"Add `@yields` tag to the JSDoc comment.\")\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone, Deserialize)]\npub struct RequireYields(Box<RequireYieldsConfig>);","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/jsdoc/require_yields.rs#L5-L41","documentation":"This is the oxlint `jsdoc/require-yields` diagnostic (missing case). It fires when a generator function that yields a value has an attached JSDoc comment but no `@yields` tag. The rule documents what a generator produces per iteration; `@returns` covers only the iterator object itself. The check walks up from a `yield <value>` expression to the nearest enclosing generator function, so `yield` with no argument never triggers it. Blocks tagged `@inheritdoc` (the default `exemptedBy`) are skipped.","triggerScenarios":"A `function*` contains `yield someValue` (non-empty argument), the nearest enclosing generator function has an attached JSDoc block, and that block has no `@yields`/`@yield` tag (tag name resolvable via `settings.jsdoc.tagName`). With `forceRequireYields: true` even empty-bodied or value-less generators are reported.","commonSituations":"Documenting generator utilities whose authors used `@returns` for the yielded sequence; enabling `jsdoc/require-yields` during lint-config tightening; `exempted_by` customization removing the default `@inheritdoc` exemption.","solutions":["Add `@yields {Type} Description` to the generator's JSDoc.","Add `@inheritdoc` when the generator implements a documented interface member.","Extend `exemptedBy` in the rule config for your project's exemption tag.","Disable the rule if documenting yields is not part of your conventions."],"exampleFix":"// before\n/**\n * Iterates rows.\n * @returns {Iterator<void>}\n */\nfunction* rows(table) {\n  yield table.head;\n  yield* table.body;\n}\n\n// after\n/**\n * Iterates rows.\n * @yields {Row} Each row of the table, header first.\n */\nfunction* rows(table) {\n  yield table.head;\n  yield* table.body;\n}","handlingStrategy":"validation","validationCode":"// Flag generator functions that yield a value but have JSDoc without @yields\nconst src = require('fs').readFileSync(file, 'utf8');\nconst fn = /\\/\\*\\*([\\s\\S]*?)\\*\\/\\s*(?:export\\s+)?function\\s*\\*\\s*(\\w+)/g;\nfor (const m of src.matchAll(fn)) {\n  if (!/@yields?/.test(m[1]) && /yield\\s+[^;\\n]/.test(src)) console.error('require-yields will fire on', m[2]);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Document generators with `@yields {T} ...` at authoring time, not after lint complains.","Use `@inheritdoc` for overrides (it is the default exemption).","If you intentionally skip yield docs, set `exemptedBy` or disable the rule instead of sprinkling ignores."],"tags":["jsdoc","generator","documentation","lint","oxlint"],"backgroundTag":"jsdoc-yields-tag-missing","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}