oxc-project/oxc · warning · OxcDiagnostic

Duplicate `@yields` tags.

Error message

Duplicate `@yields` tags.

What it means

This is the oxlint `jsdoc/require-yields` diagnostic (duplicate case). The same rule also reports JSDoc blocks that contain more than one `@yields` tag, because a generator has exactly one yield signature and duplicated tags confuse doc generators.

Source

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

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

impl Deref for RequireYields {
    type Target = RequireYieldsConfig;

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

View on GitHub (pinned to 1f902a6962)

Solutions

1. Keep a single `@yields` tag and express unions in the type: `@yields {Row|Separator}`.
2. Delete the stale duplicate left over from edits or merges.

Example fix

// before
/**
 * @yields {undefined}
 * @yields {void}
 */
function* quux(foo) {}

// after
/**
 * @yields {void} Nothing per iteration.
 */
function* quux(foo) {}

// Flag JSDoc blocks containing more than one @yields tag
const src = require('fs').readFileSync(file, 'utf8');
for (const block of src.matchAll(/\/\*\*[\s\S]*?\*\//g)) {
  const n = (block[0].match(/@yields?\b/g) || []).length;
  if (n > 1) console.error('duplicate @yields will fire');
}

When it happens

Trigger: A generator function's JSDoc block contains two or more `@yields` tags, e.g. `@yields {undefined}` followed by `@yields {void}` (the rule's own documented bad example).

Common situations: Copy-pasted doc blocks; merge artifacts where a union type was expressed as two tags instead of one `{A|B}` type; editing `@returns` to `@yields` without deleting the old tag.

Related errors

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

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