For checkJS, error when JSDoc @see tag text starts with [

[jaydenseric]

Bug Report

In a JS file with TS checking enabled, JSDoc @see tag text content that begins with [ (e.g. when the text content is a markdown link) incorrectly results in a TS error Identifier expected. at the [.

🔎 Search Terms

jsdoc @see tag Identifier expected

🕗 Version & Regression Information

Error seen in v4.1.5 and v4.3.5; probably the bug exists in every version so far that parses JSDoc @see tags.

⏯ Playground Link

// @checkJs
// @filename: a.js

/**
 * @see [TypeScript docs](https://www.typescriptlang.org/docs).
 */

Workbench Repro

💻 Code

In a.js:

// @ts-check

/**
 * @see [TypeScript docs](https://www.typescriptlang.org/docs).
 */

🙁 Actual behavior

TS error Identifier expected. at the opening [ of the JSDoc @see tag markdown text.

🙂 Expected behavior

No TS error.

[jaydenseric]

What's funny is that even with the TS errors, VS Code can still render such @see tag markdown correctly in tooltips (although the syntax highlighting of the source is bugged):

[Kingwl]

I guess it's should fallback to raw comments here? /cc: @sandersn

What's funny is that

Markdown render is provided by vscode. And the diagnostic is provided by TypeScript.

[sandersn]

Note that checkJS is the only mode that shows jsdoc parse errors because in that mode we assume you want to write correct tags -- that is, one that the compiler understands. However, markdown links should count as 'correct' for @see, even though the compiler doesn't understand them.