oxc-project/oxc · warning · OxcDiagnostic

Missing JSDoc `@returns` type.

Error message

Missing JSDoc `@returns` type.

What it means

This is the oxlint `jsdoc/require-returns-type` diagnostic. It fires when a `@returns` tag is present on a function's JSDoc but has no type in curly brackets. The rule enforces machine-readable return types in documentation so tooling (and humans) can check the declared shape of the return value.

Source

Thrown at crates/oxc_linter/src/rules/jsdoc/require_returns_type.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_type_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Missing JSDoc `@returns` type.")
        .with_help("Add {type} to the `@returns` tag.")
        .with_label(span)
}

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

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Requires that the `@returns` tag has a type value (in curly brackets).
    ///
    /// ### Why is this bad?
    ///
    /// A `@returns` tag should have a type value.
    ///
    /// ### Examples
    ///

View on GitHub (pinned to e1e7af627c)

Solutions

1. Add the type in braces: `@returns {Promise<User[]>} Resolved users.`
2. For functions returning nothing, use `@returns {void}` which also exempts sibling description rules.
3. Disable the rule (`"jsdoc/require-returns-type": "off"`) when your project treats TS signatures as the source of truth.

Example fix

// before
/**
 * Fetch a user.
 * @returns The user record.
 */
function getUser() {}

// after
/**
 * Fetch a user.
 * @returns {Promise<User>} The user record.
 */
function getUser() {}

// Flag @returns tags lacking a {type} part before linting
const src = require('fs').readFileSync(file, 'utf8');
const noType = /@returns?\s+[^{\s]/.exec(src);
if (noType) console.error('jsdoc/require-returns-type will fire:', file);

When it happens

Trigger: A documented function has `@returns Some description` or a bare `@returns` with no `{Type}` part. Only the type-in-brackets component is checked; the description itself is handled by `require-returns-description`.

Common situations: Adopting the jsdoc plugin rules on a codebase where only prose was written; TypeScript projects that rely on the type signature and skip the JSDoc type; copying doc comments from READMEs that never had `{types}`.

Related errors

• Invalid access level is specified or missing.
• Missing JSDoc `@returns` description.
• Missing JSDoc `@throws` description.
• Missing JSDoc `@throws` type.
• Missing JSDoc `@yields` declaration for generator function.

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