{"record":{"id":"ef4bc8f26f1b1408","repo":"oxc-project/oxc","slug":"missing-jsdoc-returns-description","errorCode":null,"errorMessage":"Missing JSDoc `@returns` description.","messagePattern":"Missing JSDoc `@returns` description\\.","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/jsdoc/require_returns_description.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_description_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Missing JSDoc `@returns` description.\")\n        .with_help(\"Add description comment to `@returns` tag.\")\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone)]\npub struct RequireReturnsDescription;\n\ndeclare_oxc_lint!(\n    /// ### What it does\n    ///\n    /// Requires that the `@returns` tag has a description value.\n    /// The error will not be reported if the return value is `void `or `undefined` or if it is `Promise<void>` or `Promise<undefined>`.\n    ///\n    /// ### Why is this bad?\n    ///\n    /// A `@returns` tag should have a description value.\n    ///\n    /// ### Examples","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/jsdoc/require_returns_description.rs#L1-L32","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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\"`)."],"exampleFix":"// before\n/**\n * @param {number} x\n * @returns {number}\n */\nfunction double(x) { return x * 2; }\n\n// after\n/**\n * @param {number} x\n * @returns {number} Twice the input value.\n */\nfunction double(x) { return x * 2; }","handlingStrategy":"validation","validationCode":"// Pre-commit check: flag @returns tags with no description (void/undefined exempt)\nconst src = require('fs').readFileSync(file, 'utf8');\nconst bad = src.match(/@returns?\\s*(\\{[^}]*\\})?\\s*\\*?\\s*$/gm);\nif (bad) console.error('jsdoc/require-returns-description will fire:', file);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"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"}