Microsoft/TypeScript

JSDoc tags not parsed when a type may be present

Open

#62,244 opened on Aug 9, 2025

View on GitHub
 (2 comments) (1 reaction) (0 assignees)TypeScript (48,455 stars) (6,726 forks)batch import
BugDomain: JSDocHelp Wanted

Description

🔎 Search Terms

jsdoc links missing in possible type position

🕗 Version & Regression Information

  • This is the behavior in every version I tried, and I reviewed the FAQ for entries about JSDoc

⏯ Playground Link

https://www.typescriptlang.org/play/?#code/MYGwhgzhAEDC0G8BQBfJB6AVJp1PQAEAXACwCcB7AdxgQJAEsA7AazjT3SQDMBXJ4EQYUm0LJnSxYACgCUiVEA

💻 Code

class C {
}
/**
 * @throws {@link C}
 */
function /**/CC() {
}

🙁 Actual behavior

TypeScript does not resolve {@link C}.

Hover on the playground shows:

@throws — {
@link — C}

🙂 Expected behavior

TypeScript should resolve {@link C}

Hover on the playground should show this (or even better rendered links like it does in vscode)

@throws — {@link C }

Additional information about the issue

Originally reported in https://github.com/TypeStrong/typedoc/issues/2993

Contributor guide

Tech stack
typescript
Domain
toolingdeveloper experience
Issue type
bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
4
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
TypeScriptJSDocTypeScript compiler architecture
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
40
Research direction
The bug is in TypeScript's JSDoc parsing when a type is present before a tag. Look at the parser source in `src/compiler/parser.ts` for how JSDoc tags are lexed and resolved. The playground link at https://www.typescriptlang.org/play/?#code/MYGwhgzhAEDC0G8BQBfJB6AVJp1PQAEAXACwCcB7AdxgQJAEsA7AazjT3SQDMBXJ4EQYUm0LJnSxYACgCUiVEA shows the issue. Check how `{@link}` is handled when preceded by a type.