microsoft / microsoft/TypeScript

Hover documentation for typescript uses jsdoc rules and not tsdoc

Open
#61,603 8 comments 5 reactions 0 assignees View on GitHub
Awaiting More Feedback Suggestion
Dominant language
Go
Stars
111k
Forks
14.3k
PR merge metrics
PR metrics pending

Description

- VS Code Version: 1.99.3
17baf841131aa23349f217ca7c570c76ee87b957
x64
- OS Version: N/A (happens on all)

Steps to Reproduce:

1. Write some typescript code and use the syntax required by tsdoc
2. Observe that hover documentation and highlighting completely ignore tsdoc and instead assume parity with jsdoc
3. Cry in pain as you realize that despite being written in typescript, VSCode has shoddy typescript support

Examples:

Thinking that the [mandatory hyphen](https://tsdoc.org/pages/tags/param/) after a parameter name is a markdown hint for a bullet point
![Image](https://github.com/user-attachments/assets/bbe5ae33-38e6-42dc-a00e-98e163313c33)

Not recognizing the `@defaultValue` tag, and assuming `@default` and `@defaultvalue`

![Image](https://github.com/user-attachments/assets/9c34bfaf-e412-429b-9d27-6ee7b7c19107)

Not understanding [`@remarks`](https://tsdoc.org/pages/tags/remarks/), which is marked as [core](https://tsdoc.org/pages/spec/standardization_groups/), meaning you are expected to recognize it

Not providing hover for `@typeParam`
 ![Image](https://github.com/user-attachments/assets/82c94ee5-44a5-47fb-a7c6-e42740205fd0)

(The list goes on...)

Also, this last remark isn't a bug, but it would be really, _really_ great if you would support [`@inheritDoc`](https://tsdoc.org/pages/tags/inheritdoc/) for hover.

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the listed TSDoc examples in VS Code 1.99.3, comparing hover text and highlighting with the linked TSDoc rules. Trace the TypeScript hover documentation path that handles JSDoc tags, then verify that core tags such as @param, @defaultValue, @remarks, and @typeParam are recognized with the expected formatting.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
developer-experience
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.