oxc-project/oxc · warning · OxcDiagnostic

Missing JSDoc `@yields` declaration for generator function.

Error message

Missing JSDoc `@yields` declaration for generator function.

What it means

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.

Source

Thrown at crates/oxc_linter/src/rules/jsdoc/require_yields.rs:23

use oxc_macros::declare_oxc_lint;
use oxc_semantic::{JSDoc, JSDocTag};
use oxc_span::Span;
use schemars::JsonSchema;
use serde::Deserialize;

use crate::{
    AstNode,
    context::LintContext,
    rule::{DefaultRuleConfig, Rule},
    utils::{
        get_function_nearest_jsdoc_node, is_duplicated_special_tag, is_missing_special_tag,
        should_ignore_as_avoid, should_ignore_as_custom_skip, should_ignore_as_internal,
        should_ignore_as_private,
    },
};

fn missing_yields(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Missing JSDoc `@yields` declaration for generator function.")
        .with_help("Add `@yields` tag to the JSDoc comment.")
        .with_label(span)
}

fn duplicate_yields(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Duplicate `@yields` tags.")
        .with_help("Remove redundant `@yields` tag.")
        .with_label(span)
}

fn missing_yields_with_generator(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("`@yields` tag is required when using `@generator` tag.")
        .with_help("Add `@yields` tag to the JSDoc comment.")
        .with_label(span)
}

#[derive(Debug, Default, Clone, Deserialize)]
pub struct RequireYields(Box<RequireYieldsConfig>);

View on GitHub (pinned to e1e7af627c)

Solutions

1. Add `@yields {Type} Description` to the generator's JSDoc.
2. Add `@inheritdoc` when the generator implements a documented interface member.
3. Extend `exemptedBy` in the rule config for your project's exemption tag.
4. Disable the rule if documenting yields is not part of your conventions.

Example fix

// before
/**
 * Iterates rows.
 * @returns {Iterator<void>}
 */
function* rows(table) {
  yield table.head;
  yield* table.body;
}

// after
/**
 * Iterates rows.
 * @yields {Row} Each row of the table, header first.
 */
function* rows(table) {
  yield table.head;
  yield* table.body;
}

// Flag generator functions that yield a value but have JSDoc without @yields
const src = require('fs').readFileSync(file, 'utf8');
const fn = /\/\*\*([\s\S]*?)\*\/\s*(?:export\s+)?function\s*\*\s*(\w+)/g;
for (const m of src.matchAll(fn)) {
  if (!/@yields?/.test(m[1]) && /yield\s+[^;\n]/.test(src)) console.error('require-yields will fire on', m[2]);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Duplicate `@yields` tags.
• `@yields` tag is required when using `@generator` tag.
• Missing JSDoc `@yields` description.
• Missing JSDoc `@yields` type.
• Invalid access level is specified or missing.

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/db8cf0981785d0f1. Report an issue: GitHub.