oxc-project/oxc · warning · OxcDiagnostic

`@yields` tag is required when using `@generator` tag.

Error message

`@yields` tag is required when using `@generator` tag.

What it means

This is the oxlint `jsdoc/require-yields` diagnostic for the `@generator` case. When the rule option `withGeneratorTag` (upstream `forceRequireGenerator`) is enabled, any JSDoc block that declares `@generator` must also declare `@yields`; otherwise the generator's output is undocumented. It is off by default and only fires when you opted in via rule config.

Source

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

        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>);

impl Deref for RequireYields {
    type Target = RequireYieldsConfig;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

#[derive(Debug, Clone, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
pub struct RequireYieldsConfig {

View on GitHub (pinned to e1e7af627c)

Solutions

1. Add a `@yields` tag (even `@yields {void}`) next to `@generator` in the block.
2. Remove the redundant `@generator` tag — the `function*` syntax already conveys it.
3. If the coupling is unwanted, set `"withGeneratorTag": false` or omit the option (it defaults to false).

Example fix

// before
/**
 * @generator
 */
function* ids(start) { yield start; }

// after
/**
 * @generator
 * @yields {number} Sequential ids from `start`.
 */
function* ids(start) { yield start; }

// Only fires when withGeneratorTag is enabled: flag @generator blocks without @yields
const src = require('fs').readFileSync(file, 'utf8');
for (const block of src.matchAll(/\/\*\*[\s\S]*?\*\//g)) {
  if (/@generator\b/.test(block[0]) && !/@yields?\b/.test(block[0])) console.error('require-yields (@generator) will fire');
}

When it happens

Trigger: Rule config sets `"withGeneratorTag": true` (jsdoc/require-yields) and a function's JSDoc contains a `@generator` tag but no `@yields` tag. The diagnostic is labeled on the `@generator` tag's span.

Common situations: Porting an ESLint config that used `require-yields` with `forceRequireGenerator: true`; doc pipelines that emit `@generator` boilerplate automatically (e.g. some typedoc templates) without a matching `@yields`.

Related errors

• Missing JSDoc `@yields` declaration for generator function.
• Duplicate `@yields` tags.
• 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/8a65546a574d91a5. Report an issue: GitHub.