Fix inline JSDoc links in optional type positions by mbarinov · Pull Request #64732 · microsoft/TypeScript

Max Barinov (mbarinov) · 2026-10-11T13:22:18Z

An inline JSDoc link immediately after @throws or @returns, such as @throws {@link C}, is parsed as a type expression. This splits the documentation into extra tags and prevents the link from resolving in hover and go-to-definition.

Move the existing inline-link lookahead from the name-first parameter path into tryParseTypeExpression, so optional type positions consistently recognize link, linkcode, and linkplain. Remove the redundant parameter guard. Ordinary {Type} annotations keep their existing behavior.

Parser tests cover all three link forms after @throws, @returns, and name-first @param, plus ordinary type annotations. A fourslash test checks hover and definition targets. Both regression tests fail on unchanged main and pass with the fix; the two new baselines were inspected before acceptance.

Validation passed: npx hereby generate, build, test, test:all, lint, format, and check:format; the documented API and extension builds/tests; and module/workspace checks. The Go suite reported 2,149 skipped tests. Local parser benchmarks showed unchanged allocation counts and overlapping timing ranges. git diff --check flags only trailing spaces produced by the baseline generator; source checks and repository formatting pass.

AI disclosure: I used Codex to prepare the fix and tests. I have reviewed and understand the final patch, and I will handle review feedback myself.

Copilot

🟢 Approval recommended

The focused parser change is correct and covered by parser, hover, definition, and regression tests.

0 open findings

What changed in this PR

Fixes JSDoc inline links being misparsed as optional type annotations.

Changes:

Excludes link, linkcode, and linkplain from optional type parsing.
Adds parser and language-service regression coverage.
Preserves ordinary JSDoc type annotation behavior.

File	Description
`tsc/internal/parser/jsdoc.go`	Moves inline-link detection into optional type parsing.
`tsc/internal/parser/parser_test.go`	Tests link forms and ordinary types.
`tsc/internal/fourslash/tests/jsdocInlineLinksInTypePosition_test.go`	Tests hover and definition behavior.
`tsc/testdata/baselines/reference/fourslash/quickInfo/jsdocInlineLinksInTypePosition.baseline`	Records expected hover output.
`tsc/testdata/baselines/reference/fourslash/goToDefinition/jsdocInlineLinksInTypePosition.baseline.jsonc`	Records expected definition targets.

🧠 Review effort: Balanced

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

Max Barinov (mbarinov) · 2026-10-11T13:41:06Z

@microsoft-github-policy-service agree

Jake Bailey (jakebailey) · 2026-10-12T18:54:12Z

TypeScript Bot (@typescript-bot) test it

typescript-automation · 2026-10-12T18:54:19Z

Starting jobs; this comment will be updated as builds start and complete.

Command	Status	Results
`test top400`	✅ Started	✅ Results
`user test this`	✅ Started	✅ Results
`run dt`	✅ Started	✅ Results
`perf test this faster`	✅ Started	👀 Results

typescript-automation · 2026-10-12T19:18:56Z

Hey Jake Bailey (@jakebailey), the results of running the DT tests are ready.

Everything looks the same!

You can check the log here.

typescript-automation · 2026-10-12T19:24:09Z

Jake Bailey (@jakebailey)
The results of the perf run you requested are in!

Here they are:

tsc

Comparison Report - baseline..pr

_Metric	_baseline	_pr	_Delta	_Best	_Worst	_p-value
_{Compiler-Unions - native}
_Errors	₄₁	₄₁	_~	_~	_~	_{p=1.000 n=12}
_Symbols	_115,276	_115,276	_~	_~	_~	_{p=1.000 n=12}
_Types	_79,613	_79,613	_~	_~	_~	_{p=1.000 n=12}
_{Memory Used}	_{133,876k (± 0.06%)}	_{133,853k (± 0.04%)}	_~	_133,761k	_134,007k	_{p=0.702 n=12}
_{Memory Allocs}	_{2,189,959 (± 0.00%)}	_{2,189,977 (± 0.00%)}	_~	_2,189,840	_2,190,371	_{p=0.830 n=12}
_{Config Time}	_0.000s	_0.000s	_~	_~	_~	_{p=1.000 n=12}
_{Parse Time}	_{0.040s (± 2.92%)}	_{0.040s (± 3.78%)}	_~	_0.036s	_0.044s	_{p=0.762 n=12}
_{Bind Time}	_{0.012s (±11.67%)}	_{0.014s (±14.03%)}	_~	_0.010s	_0.019s	_{p=0.147 n=12}
_{Check Time}	_{0.498s (± 0.64%)}	_{0.492s (± 0.73%)}	_{-0.006s (- 1.12%)}	_0.485s	_0.503s	_{p=0.021 n=12}
_{Emit Time}	_{0.273s (± 1.30%)}	_{0.269s (± 0.82%)}	_{-0.005s (- 1.65%)}	_0.262s	_0.275s	_{p=0.029 n=12}
_{Total Time}	_{0.830s (± 0.72%)}	_{0.821s (± 0.39%)}	_{-0.008s (- 1.02%)}	_0.810s	_0.829s	_{p=0.025 n=12}
_{angular-1 - native}
_Errors	₃	₃	_~	_~	_~	_{p=1.000 n=12}
_Symbols	_{845,303 (± 0.06%)}	_{845,220 (± 0.07%)}	_~	_842,818	_846,224	_{p=1.000 n=12}
_Types	_{248,125 (± 0.00%)}	_{248,125 (± 0.00%)}	_~	_248,120	_248,135	_{p=0.759 n=12}
_{Memory Used}	_{750,417k (± 0.02%)}	_{750,399k (± 0.02%)}	_~	_750,060k	_750,784k	_{p=0.378 n=12}
_{Memory Allocs}	_{12,915,727 (± 0.03%)}	_{12,918,912 (± 0.04%)}	_~	_12,910,178	_12,937,884	_{p=0.410 n=12}
_{Config Time}	_0.017s	_0.017s	_~	_~	_~	_{p=1.000 n=12}
_{Parse Time}	_{0.259s (± 2.43%)}	_{0.256s (± 2.82%)}	_~	_0.232s	_0.269s	_{p=0.599 n=12}
_{Bind Time}	_{0.058s (± 1.08%)}	_{0.067s (±18.28%)}	_~	_0.056s	_0.117s	_{p=0.895 n=12}
_{Check Time}	_0s	_0s	_~	_~	_~	_{p=1.000 n=12}
_{Emit Time}	_{1.556s (± 0.62%)}	_{1.568s (± 0.97%)}	_~	_1.544s	_1.617s	_{p=0.117 n=12}
_{Total Time}	_{1.903s (± 0.66%)}	_{1.922s (± 1.20%)}	_~	_1.895s	_2.003s	_{p=0.326 n=12}
_{mui-docs - native}
_Errors	_11,405	_11,405	_~	_~	_~	_{p=1.000 n=12}
_Symbols	_4,359,614	_4,359,614	_~	_~	_~	_{p=1.000 n=12}
_Types	_1,376,379	_1,376,379	_~	_~	_~	_{p=1.000 n=12}
_{Memory Used}	_{2,812,387k (± 0.06%)}	_{2,812,379k (± 0.07%)}	_~	_2,808,440k	_2,819,422k	_{p=0.977 n=12}
_{Memory Allocs}	_{32,812,661 (± 0.05%)}	_{32,801,883 (± 0.06%)}	_~	_32,767,908	_32,853,687	_{p=0.291 n=12}
_{Config Time}	_0.017s	_0.017s	_~	_~	_~	_{p=1.000 n=12}
_{Parse Time}	_{0.511s (± 1.71%)}	_{0.488s (± 2.84%)}	_{🟩-0.023s (- 4.52%)}	_0.453s	_0.524s	_{p=0.011 n=12}
_{Bind Time}	_0.002s	_0.002s	_~	_~	_~	_{p=1.000 n=12}
_{Check Time}	_{8.637s (± 0.55%)}	_{8.659s (± 0.33%)}	_~	_8.530s	_8.721s	_{p=0.514 n=12}
_{Emit Time}	_{0.455s (± 7.05%)}	_{0.448s (± 4.63%)}	_~	_0.426s	_0.519s	_{p=0.324 n=12}
_{Total Time}	_{10.386s (± 0.62%)}	_{10.380s (± 0.50%)}	_~	_10.195s	_10.497s	_{p=0.854 n=12}
_{strada-build-src - native}
_Errors	₀	₀	_~	_~	_~	_{p=1.000 n=12}
_Symbols	_1,390,229	_1,390,229	_~	_~	_~	_{p=1.000 n=12}
_Types	_441,498	_441,498	_~	_~	_~	_{p=1.000 n=12}
_{Memory Used}	_{1,632,946k (± 0.85%)}	_{1,624,990k (± 0.70%)}	_~	_1,602,015k	_1,661,706k	_{p=0.478 n=12}
_{Memory Allocs}	_{92,209,891 (± 0.08%)}	_{91,955,722 (± 0.17%)}	_{-254,169 (- 0.28%)}	_91,667,917	_92,290,303	_{p=0.017 n=12}
_{Config Time}	_{0.003s (±15.93%)}	_{0.003s (±11.47%)}	_~	_0.002s	_0.004s	_{p=0.355 n=12}
_{Parse Time}	_{0.200s (± 3.73%)}	_{0.193s (± 3.90%)}	_~	_0.173s	_0.209s	_{p=0.311 n=12}
_{Bind Time}	_0.000s	_0.000s	_~	_~	_~	_{p=1.000 n=12}
_{Check Time}	_{1.797s (± 0.27%)}	_{1.800s (± 0.69%)}	_~	_1.776s	_1.847s	_{p=1.000 n=12}
_{Emit Time}	_{0.306s (± 3.88%)}	_{0.298s (± 4.55%)}	_~	_0.258s	_0.327s	_{p=0.311 n=12}
_{Total Time}	_{23.452s (± 0.53%)}	_{23.204s (± 0.84%)}	_{-0.248s (- 1.06%)}	_22.640s	_23.554s	_{p=0.045 n=12}
_{strada-compiler - native}
_Errors	₀	₀	_~	_~	_~	_{p=1.000 n=12}
_Symbols	_334,953	_334,953	_~	_~	_~	_{p=1.000 n=12}
_Types	_197,616	_197,616	_~	_~	_~	_{p=1.000 n=12}
_{Memory Used}	_{297,312k (± 0.01%)}	_{297,297k (± 0.03%)}	_~	_297,063k	_297,479k	_{p=0.932 n=12}
_{Memory Allocs}	_{4,621,106 (± 0.01%)}	_{4,620,939 (± 0.01%)}	_~	_4,619,678	_4,622,213	_{p=0.682 n=12}
_{Config Time}	_0.001s	_0.001s	_~	_~	_~	_{p=1.000 n=12}
_{Parse Time}	_{0.113s (± 5.11%)}	_{0.111s (± 4.56%)}	_~	_0.099s	_0.125s	_{p=0.660 n=12}
_{Bind Time}	_0.000s	_0.000s	_~	_~	_~	_{p=1.000 n=12}
_{Check Time}	_{1.043s (± 0.38%)}	_{1.039s (± 0.71%)}	_~	_1.024s	_1.058s	_{p=0.468 n=12}
_{Emit Time}	_{0.146s (± 5.68%)}	_{0.147s (± 9.10%)}	_~	_0.094s	_0.175s	_{p=0.831 n=12}
_{Total Time}	_{1.355s (± 0.91%)}	_{1.351s (± 0.88%)}	_~	_1.321s	_1.383s	_{p=0.580 n=12}
_{ts-pre-modules - native}
_Errors	₈₇	₈₇	_~	_~	_~	_{p=1.000 n=12}
_Symbols	_303,834	_303,834	_~	_~	_~	_{p=1.000 n=12}
_Types	_181,663	_181,663	_~	_~	_~	_{p=1.000 n=12}
_{Memory Used}	_{258,136k (± 0.02%)}	_{258,140k (± 0.02%)}	_~	_258,022k	_258,238k	_{p=0.966 n=12}
_{Memory Allocs}	_{1,613,622 (± 0.02%)}	_{1,613,789 (± 0.02%)}	_~	_1,613,217	_1,615,061	_{p=0.630 n=12}
_{Config Time}	_0.000s	_{0.000s (±217.90%)}	_~	_0.000s	_0.001s	_{p=1.000 n=12}
_{Parse Time}	_{0.098s (± 4.55%)}	_{0.100s (± 3.97%)}	_~	_0.090s	_0.113s	_{p=0.338 n=12}
_{Bind Time}	_{0.039s (±11.61%)}	_{0.038s (±13.50%)}	_~	_0.027s	_0.053s	_{p=0.619 n=12}
_{Check Time}	_{0.813s (± 0.92%)}	_{0.816s (± 0.79%)}	_~	_0.800s	_0.831s	_{p=0.504 n=12}
_{Emit Time}	_0.000s	_0.000s	_~	_~	_~	_{p=1.000 n=12}
_{Total Time}	_{0.963s (± 0.58%)}	_{0.968s (± 0.67%)}	_~	_0.945s	_0.981s	_{p=0.147 n=12}
_{vscode - native}
_Errors	₃₉₅	₃₉₅	_~	_~	_~	_{p=1.000 n=12}
_Symbols	_11,287,880	_11,288,749	_{+869 (+ 0.01%)}	_~	_~	_{p=0.000 n=12}
_Types	_3,740,417	_3,740,641	_{+224 (+ 0.01%)}	_~	_~	_{p=0.000 n=12}
_{Memory Used}	_{6,524,010k (± 0.01%)}	_{6,523,619k (± 0.01%)}	_~	_6,521,930k	_6,526,897k	_{p=0.291 n=12}
_{Memory Allocs}	_{55,470,816 (± 0.01%)}	_{55,472,277 (± 0.02%)}	_~	_55,457,310	_55,525,224	_{p=0.590 n=12}
_{Config Time}	_{0.075s (± 0.24%)}	_{0.075s (± 0.48%)}	_~	_0.074s	_0.076s	_{p=0.590 n=12}
_{Parse Time}	_{1.872s (± 3.93%)}	_{1.881s (± 2.92%)}	_~	_1.716s	_2.001s	_{p=0.875 n=12}
_{Bind Time}	_{0.549s (±18.57%)}	_{0.536s (±17.32%)}	_~	_0.445s	_0.910s	_{p=0.522 n=12}
_{Check Time}	_{14.056s (± 1.02%)}	_{14.133s (± 0.86%)}	_~	_13.733s	_14.297s	_{p=0.418 n=12}
_{Emit Time}	_{4.677s (± 9.08%)}	_{4.591s (± 9.04%)}	_~	_4.146s	_5.818s	_{p=0.755 n=12}
_{Total Time}	_{21.313s (± 1.58%)}	_{21.299s (± 1.56%)}	_~	_20.875s	_22.382s	_{p=0.856 n=12}
_{webpack - native}
_Errors	₅₈₄	₅₈₄	_~	_~	_~	_{p=1.000 n=12}
_Symbols	_1,310,990	_1,310,990	_~	_~	_~	_{p=1.000 n=12}
_Types	_619,725	_619,725	_~	_~	_~	_{p=1.000 n=12}
_{Memory Used}	_{945,219k (± 0.01%)}	_{945,238k (± 0.01%)}	_~	_944,966k	_945,517k	_{p=0.799 n=12}
_{Memory Allocs}	_{6,647,238 (± 0.03%)}	_{6,645,139 (± 0.02%)}	_~	_6,642,762	_6,649,048	_{p=0.078 n=12}
_{Config Time}	_0.009s	_0.009s	_~	_~	_~	_{p=1.000 n=12}
_{Parse Time}	_{0.301s (± 3.37%)}	_{0.292s (± 2.64%)}	_~	_0.268s	_0.314s	_{p=0.213 n=12}
_{Bind Time}	_{0.083s (±14.88%)}	_{0.091s (±18.43%)}	_~	_0.064s	_0.136s	_{p=0.619 n=12}
_{Check Time}	_{2.073s (± 0.67%)}	_{2.079s (± 1.07%)}	_~	_2.037s	_2.138s	_{p=0.681 n=12}
_{Emit Time}	_0.000s	_0.000s	_~	_~	_~	_{p=1.000 n=12}
_{Total Time}	_{2.503s (± 0.55%)}	_{2.507s (± 0.62%)}	_~	_2.481s	_2.566s	_{p=0.966 n=12}
_{xstate-main - native}
_Errors	₀	₀	_~	_~	_~	_{p=1.000 n=12}
_Symbols	_1,061,928	_1,061,928	_~	_~	_~	_{p=1.000 n=12}
_Types	_389,645	_389,645	_~	_~	_~	_{p=1.000 n=12}
_{Memory Used}	_{554,323k (± 0.02%)}	_{554,249k (± 0.02%)}	_~	_554,071k	_554,528k	_{p=0.219 n=12}
_{Memory Allocs}	_{4,886,322 (± 0.10%)}	_{4,884,023 (± 0.09%)}	_~	_4,874,838	_4,898,610	_{p=0.319 n=12}
_{Config Time}	_0.003s	_0.003s	_~	_~	_~	_{p=1.000 n=12}
_{Parse Time}	_{0.148s (± 4.01%)}	_{0.149s (± 2.95%)}	_~	_0.140s	_0.163s	_{p=0.659 n=12}
_{Bind Time}	_{0.046s (±12.90%)}	_{0.039s (±12.39%)}	_~	_0.033s	_0.058s	_{p=0.096 n=12}
_{Check Time}	_{1.129s (± 0.45%)}	_{1.132s (± 0.56%)}	_~	_1.117s	_1.149s	_{p=0.385 n=12}
_{Emit Time}	_0.000s	_0.000s	_~	_~	_~	_{p=1.000 n=12}
_{Total Time}	_{1.336s (± 0.71%)}	_{1.334s (± 0.81%)}	_~	_1.307s	_1.367s	_{p=0.681 n=12}

System info unknown

Hosts

native

Scenarios

Compiler-Unions - native
angular-1 - native
mui-docs - native
strada-build-src - native
strada-compiler - native
ts-pre-modules - native
vscode - native
webpack - native
xstate-main - native

_Benchmark	_Name	_Iterations
_Current	_pr	₁₂
_Baseline	_baseline	₁₂

Developer Information:

Download Benchmarks

typescript-automation · 2026-10-12T19:25:18Z

Jake Bailey (@jakebailey) Here are the results of running the user tests with tsc comparing baseline and pr:

Everything looks good!

typescript-automation · 2026-10-12T20:11:28Z

Jake Bailey (@jakebailey) Here are the results of running the top 400 repos with tsc comparing baseline and pr:

Everything looks good!

fix(parser): preserve inline JSDoc links in optional type positions

808691f

Copilot AI balanced review requested due to automatic review settings October 11, 2026 13:22

github-project-automation Bot added this to PR Backlog Oct 11, 2026

typescript-automation Bot added the For Backlog Bug PRs that fix a backlog bug label Oct 11, 2026

Copilot started reviewing on behalf of Max Barinov (mbarinov) October 11, 2026 13:23

View session

Copilot AI reviewed Oct 11, 2026

View reviewed changes

Max Barinov (mbarinov) added 3 commits October 13, 2026 14:24

Merge branch 'main' into fix/jsdoc-inline-type-position-62244

fa91ac3

Merge branch 'main' into fix/jsdoc-inline-type-position-62244

4ea5176

Merge branch 'main' into fix/jsdoc-inline-type-position-62244

6375273

Navigation Menu

Repository navigation

Fix inline JSDoc links in optional type positions - #64732

Fix inline JSDoc links in optional type positions#64732
Max Barinov (mbarinov) wants to merge 4 commits into
microsoft:mainfrom
mbarinov:fix/jsdoc-inline-type-position-62244

Max Barinov (mbarinov) commented Oct 11, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Max Barinov (mbarinov) commented Oct 11, 2026

Uh oh!

Jake Bailey (jakebailey) commented Oct 12, 2026

Uh oh!

typescript-automation Bot commented Oct 12, 2026 •

edited

Loading

Uh oh!

typescript-automation Bot commented Oct 12, 2026

Uh oh!

typescript-automation Bot commented Oct 12, 2026

tsc

Uh oh!

typescript-automation Bot commented Oct 12, 2026

Uh oh!

typescript-automation Bot commented Oct 12, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Max Barinov (mbarinov) commented Oct 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Max Barinov (mbarinov) commented Oct 11, 2026

Uh oh!

Jake Bailey (jakebailey) commented Oct 12, 2026

Uh oh!

typescript-automation Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

typescript-automation Bot commented Oct 12, 2026

Uh oh!

typescript-automation Bot commented Oct 12, 2026

tsc

Uh oh!

typescript-automation Bot commented Oct 12, 2026

Uh oh!

typescript-automation Bot commented Oct 12, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

typescript-automation Bot commented Oct 12, 2026 •

edited

Loading