oxc-project/oxc · warning · OxcDiagnostic

Missing JSDoc `@yields` description.

Error message

Missing JSDoc `@yields` description.

What it means

This is the oxlint `jsdoc/require-yields-description` diagnostic. It fires when a generator's `@yields` tag has no free-text description (e.g. only `@yields {Row}`). It mirrors `require-returns-description` but for generator yield values.

Source

Thrown at crates/oxc_linter/src/rules/jsdoc/require_yields_description.rs:12

use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

use crate::{
    context::LintContext,
    rule::Rule,
    utils::{should_ignore_as_internal, should_ignore_as_private},
};

fn require_yields_description_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Missing JSDoc `@yields` description.")
        .with_help("Add description comment to `@yields` tag.")
        .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct RequireYieldsDescription;

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Requires a description for `@yields` tags.
    ///
    /// ### Why is this bad?
    ///
    /// A `@yields` tag should explain what the generator yields.
    ///
    /// ### Examples
    ///

View on GitHub (pinned to e1e7af627c)

Solutions

1. Describe what is yielded: `@yields {Chunk} Decoded chunk of the stream.`
2. Exempt the block with `@private`/`@internal` when appropriate.
3. Disable `"jsdoc/require-yields-description"` if type-only yields docs are your convention.

Example fix

// before
/**
 * @yields {number}
 */
function* fib() { /* ... */ }

// after
/**
 * @yields {number} The next Fibonacci number.
 */
function* fib() { /* ... */ }

// Flag @yields tags with no description text
const src = require('fs').readFileSync(file, 'utf8');
const bare = /@yields?(?:\s+\{[^}]*\})?\s*$/m.exec(src);
if (bare) console.error('jsdoc/require-yields-description will fire:', file);

When it happens

Trigger: A function's attached JSDoc contains a `@yields` tag with empty comment text after the tag/type. Private/internal-tagged blocks and custom skips are exempt per JSDoc settings.

Common situations: Teams that add `@yields {T}` types to satisfy `require-yields-type` but never write prose; enabling the whole jsdoc plugin's `require-*` family at once.

Related errors

• Missing JSDoc `@yields` declaration for generator function.
• Duplicate `@yields` tags.
• `@yields` tag is required when using `@generator` tag.
• 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/063c2372c028beba. Report an issue: GitHub.