What causes "Missing JSDoc `@returns` description." in oxc-project/oxc?

Add a description after the type: `@returns {string} The canonicalized user name.`

oxc-project/oxc · warning · OxcDiagnostic

Missing JSDoc `@returns` description.

Error message

Missing JSDoc `@returns` description.

What it means

This is the oxlint `jsdoc/require-returns-description` diagnostic. It fires when a function's JSDoc comment has a `@returns` (or `@return`) tag that carries no free-text description, e.g. only `@returns {string}`. The rule exists because a bare type tells callers nothing about the meaning or shape of the value. Functions documented as returning `void`, `undefined`, `Promise<void>` or `Promise<undefined>` are exempt.

Source

Thrown at crates/oxc_linter/src/rules/jsdoc/require_returns_description.rs:14

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

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

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

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

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Requires that the `@returns` tag has a description value.
    /// The error will not be reported if the return value is `void `or `undefined` or if it is `Promise<void>` or `Promise<undefined>`.
    ///
    /// ### Why is this bad?
    ///
    /// A `@returns` tag should have a description value.
    ///
    /// ### Examples

View on GitHub (pinned to e1e7af627c)

Solutions

Add a description after the type: `@returns {string} The canonicalized user name.`
If the function truly returns nothing meaningful, document `@returns {void}` so the rule skips it.
Mark the function `@private` or `@internal` (or add it to `ignorePrivate`/`ignoreInternal` settings) when docs are not required.
If terse `@returns {Type}` style is your team convention, turn the rule off in `.oxlintrc.json` (`"jsdoc/require-returns-description": "off"`).

Example fix

// before
/**
 * @param {number} x
 * @returns {number}
 */
function double(x) { return x * 2; }

// after
/**
 * @param {number} x
 * @returns {number} Twice the input value.
 */
function double(x) { return x * 2; }

Defensive patterns

Strategy: validation

Validate before calling

// Pre-commit check: flag @returns tags with no description (void/undefined exempt)
const src = require('fs').readFileSync(file, 'utf8');
const bad = src.match(/@returns?\s*(\{[^}]*\})?\s*\*?\s*$/gm);
if (bad) console.error('jsdoc/require-returns-description will fire:', file);

Prevention

Enable the rule early in a project so missing descriptions never accumulate.
Use an editor snippet that expands `@returns {type} description` with the description placeholder.
Run oxlint in CI and pre-commit hooks so doc gaps block the merge, not the release.
Prefer `@returns {void}` on functions returning nothing to get an intentional exemption.

When it happens

Trigger: A function has an attached JSDoc block containing a `@returns` tag whose comment text after the `{type}` (or after the tag name when no type is given) is empty. The JSDoc is not marked `@private`, `@internal`, or skipped via `@inheritdoc`/ignore settings.

Common situations: Enabling the `jsdoc` plugin's stricter `require-*` rules when adopting oxlint in a codebase that documents types only; migrating from ESLint `jsdoc/require-returns-description` and expecting identical behavior; auto-generated stubs that emit `@returns {T}` without prose.

Related errors

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