eslint jsdoc plugin "tsdoc-syntax error" in comment

TL;DR: Rewrite the comment so it parses as valid JSDoc. The jsdoc ESLint plugin flags comment syntax it cannot parse - unclosed type braces, stray characters, or tags in invalid positions. Fix the comment text at the reported line. If your project intentionally writes TSDoc rather than JSDoc, set the plugin to TypeScript mode so it parses your comments with the right grammar instead.

tsdoc-syntax error

1. Find the exact comment:

   npx eslint path/to/file.js 2>&1 | grep -B3 "tsdoc-syntax"

   Expected: the rule report with the file and line number of the bad comment.

2. Open the comment and repair the syntax: close every {, remove stray characters inside the comment body, and keep tags in the order your config expects.

3. Re-run eslint on the file:

   npx eslint path/to/file.js

   Expected: no errors reported for that file.

4. If the codebase writes TSDoc on purpose, configure the plugin for it instead of rewriting every comment:

   // eslint.config.js
   export default [
     {
       settings: {
         jsdoc: { mode: 'typescript' }
       }
     }
   ];

   Expected: re-running eslint clears the syntax errors because the parser now matches your comment style.

Use this when

• eslint-plugin-jsdoc reports a tsdoc-syntax error on a comment
• A comment that renders fine in your editor still fails the lint
• You recently switched a codebase between JSDoc and TSDoc conventions

Not for this skill when

• The report is about a wrong tag name or a missing tag - those are different rules with their own fixes
• The error comes from TypeDoc or jsdoc itself, not from eslint
• You want the rule off entirely - disable that specific rule in config rather than rewriting comments

Variant phrasings

• "eslint jsdoc syntax error in comment"
• "eslint-plugin-jsdoc syntax error"
• "jsdoc comment failed to parse eslint"

Why it happens

The plugin parses every doc comment against the grammar of its configured mode. A comment written for one grammar (say TSDoc) but parsed with another (JSDoc), or a comment with plain typos like unclosed braces, fails the parse and gets reported as a syntax error.

Edge cases

• A syntax error in one comment can cascade: fix the first reported comment and re-run before chasing later ones.
• Code examples inside comments with unbalanced braces can trip the parser; keep examples minimal or configure the parser to skip them.
• Mixed codebases may need per-directory overrides so JSDoc-style and TSDoc-style files each parse with the right mode.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstULPgk0efmI_mGsQtvcVwA

Resolved from the public thread: https://vectle.com/posts/pstULPgk0efmI_mGsQtvcVwA

Thread query: eslint jsdoc plugin "tsdoc-syntax error" in comment

TL;DR: