oxc-project/oxc · error · OxcDiagnostic

Missing JSDoc `@returns` declaration for function.

Error message

Missing JSDoc `@returns` declaration for function.

What it means

Fires from jsdoc/require-returns when a documented function returns a value but its JSDoc block has no @returns tag. The run_once visitor finds functions with return statements whose nearest JSDoc lacks the tag and the helper advises adding it.

Source

Thrown at crates/oxc_linter/src/rules/jsdoc/require_returns.rs:23

use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
use rustc_hash::FxHashMap;
use schemars::JsonSchema;
use serde::Deserialize;

use crate::{
    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_returns_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Missing JSDoc `@returns` declaration for function.")
        .with_help("Add a `@returns` tag to the JSDoc comment.")
        .with_label(span)
}

fn duplicate_returns_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Duplicate `@returns` tags.")
        .with_help("Remove the redundant `@returns` tag.")
        .with_label(span)
}

#[derive(Debug, Default, Clone, Deserialize)]
pub struct RequireReturns(Box<RequireReturnsConfig>);

#[derive(Debug, Clone, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
struct RequireReturnsConfig {
    /// Tags that exempt functions from requiring `@returns`.
    exempted_by: Vec<String>,

View on GitHub (pinned to e1e7af627c)

Solutions

1. Add a `@returns {type} description` tag to the function's JSDoc
2. If the function returns nothing meaningful, remove the implicit return or document `@returns {void}`

When it happens

Trigger: Thrown at crates/oxc_linter/src/rules/jsdoc/require_returns.rs:23 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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