{"record":{"id":"60f5193964ec05ca","repo":"oxc-project/oxc","slug":"missing-jsdoc-returns-type","errorCode":null,"errorMessage":"Missing JSDoc `@returns` type.","messagePattern":"Missing JSDoc `@returns` type\\.","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/jsdoc/require_returns_type.rs","lineNumber":14,"sourceCode":"use oxc_ast::AstKind;\nuse oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::Span;\n\nuse crate::{\n    AstNode,\n    context::LintContext,\n    rule::Rule,\n    utils::{get_function_nearest_jsdoc_node, should_ignore_as_internal, should_ignore_as_private},\n};\n\nfn missing_type_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Missing JSDoc `@returns` type.\")\n        .with_help(\"Add {type} to the `@returns` tag.\")\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone)]\npub struct RequireReturnsType;\n\ndeclare_oxc_lint!(\n    /// ### What it does\n    ///\n    /// Requires that the `@returns` tag has a type value (in curly brackets).\n    ///\n    /// ### Why is this bad?\n    ///\n    /// A `@returns` tag should have a type value.\n    ///\n    /// ### Examples\n    ///","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/jsdoc/require_returns_type.rs#L1-L32","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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}`.","solutions":["Add the type in braces: `@returns {Promise<User[]>} Resolved users.`","For functions returning nothing, use `@returns {void}` which also exempts sibling description rules.","Disable the rule (`\"jsdoc/require-returns-type\": \"off\"`) when your project treats TS signatures as the source of truth."],"exampleFix":"// before\n/**\n * Fetch a user.\n * @returns The user record.\n */\nfunction getUser() {}\n\n// after\n/**\n * Fetch a user.\n * @returns {Promise<User>} The user record.\n */\nfunction getUser() {}","handlingStrategy":"validation","validationCode":"// Flag @returns tags lacking a {type} part before linting\nconst src = require('fs').readFileSync(file, 'utf8');\nconst noType = /@returns?\\s+[^{\\s]/.exec(src);\nif (noType) console.error('jsdoc/require-returns-type will fire:', file);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Adopt a doc template that always includes the curly-bracket type on @returns.","In TypeScript files, mirror the signature type into the JSDoc to keep them in sync.","Add oxlint to CI so @returns-type regressions fail fast."],"tags":["jsdoc","documentation","lint","oxlint"],"backgroundTag":"jsdoc-returns-tag-missing","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}