{"record":{"id":"11f88b21baa772ff","repo":"oxc-project/oxc","slug":"missing-jsdoc-throws-description","errorCode":null,"errorMessage":"Missing JSDoc `@throws` description.","messagePattern":"Missing JSDoc `@throws` description\\.","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/jsdoc/require_throws_description.rs","lineNumber":12,"sourceCode":"use oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::Span;\n\nuse crate::{\n    context::LintContext,\n    rule::Rule,\n    utils::{should_ignore_as_internal, should_ignore_as_private},\n};\n\nfn require_throws_description_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Missing JSDoc `@throws` description.\")\n        .with_help(\"Add description comment to `@throws` tag.\")\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone)]\npub struct RequireThrowsDescription;\n\ndeclare_oxc_lint!(\n    /// ### What it does\n    ///\n    /// Requires a description for `@throws` tags.\n    ///\n    /// ### Why is this bad?\n    ///\n    /// A `@throws` tag should explain the condition or reason an error may be thrown.\n    ///\n    /// ### Examples\n    ///","sourceCodeStart":1,"sourceCodeEnd":30,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/jsdoc/require_throws_description.rs#L1-L30","documentation":"This is the oxlint `jsdoc/require-throws-description` diagnostic. It fires when a function's JSDoc has a `@throws` tag with no description text. The point of `@throws` is to tell callers what failure occurred, so a bare `@throws {Error}` conveys nothing actionable.","triggerScenarios":"A function's attached JSDoc contains `@throws {TypeError}` or bare `@throws` with empty comment text after the tag/type. The block is not exempted via `@private`/`@internal` or JSDoc settings.","commonSituations":"Enabling stricter jsdoc rules over legacy doc comments that list exception types only; bulk-enabling `jsdoc/*` rules in `.oxlintrc.json` during an ESLint-to-oxlint migration.","solutions":["Describe the failure condition: `@throws {TypeError} When `id` is not a string.`","Exempt internal helpers with `@private`/`@internal` when their docs are not user-facing.","Turn the rule off if your team documents exceptions in prose instead (`\"jsdoc/require-throws-description\": \"off\"`)."],"exampleFix":"// before\n/**\n * @throws {RangeError}\n */\nfunction parsePort(input) {}\n\n// after\n/**\n * @throws {RangeError} When `input` is not between 0 and 65535.\n */\nfunction parsePort(input) {}","handlingStrategy":"validation","validationCode":"// Flag @throws tags with no description (type-only or bare)\nconst src = require('fs').readFileSync(file, 'utf8');\nconst bare = /@throws(?:\\s+\\{[^}]*\\})?\\s*$/m.exec(src);\nif (bare) console.error('jsdoc/require-throws-description will fire:', file);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Write @throws as `@throws {ErrType} condition-that-triggers-it` from the start.","During code review, require any new `throw` site to have a matching described @throws tag.","Run oxlint in the pre-commit hook so doc drift cannot land."],"tags":["jsdoc","documentation","lint","oxlint"],"backgroundTag":"jsdoc-throws-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"}