microsoft / microsoft/TypeScript

Hover documentation for parameters documented with jsdoc renders improperly

Open
#63,573 1 comment 0 reactions 0 assignees View on GitHub
Experience Enhancement Suggestion
Dominant language
Go
Stars
111k
Forks
14.3k
PR merge metrics
PR metrics pending

Description

### 🔎 Search Terms

parameter hover documentation
jsdoc parameter hyphen
jsdoc parameter
vscode jsdoc parameter hover

### 🕗 Version & Regression Information

~~- This changed between versions ______ and _______~~
~~- This changed in commit or PR _______~~
- This is the behavior in every version I tried, and I reviewed the entire FAQ for anything that might be related to this
- I was unable to test this on prior versions because this is not a regression in typescript itself, it is a VSCode issue which I know, based on experience, will get moved to this repository.

### ⏯ Playground Link

Won't show vscode hover, so not worth pasting.

### 💻 Code

issue 1:
```ts
/**
* Foo method
* @param arg - Documentation for arg
*/
function ex1(arg: string) {
return arg;
}
```

issue 2:
```ts
/**
* Foo method
*
* @param arg Documentation for arg but it ends up being long enough that we
* must split it across lines to stay within max column width
* @param arg2 Documentation for arg but it ends up being long enough that we must split it across lines to stay within max column width
*/
function ex2(arg: string) {
return arg;
}
```

### 🙁 Actual behavior

Issue 1

The hover doc shows a bullet point when the hyphen is present (note the hover for the method itself renders properly)

Image

Issue 2

Image

### 🙂 Expected behavior

Issue 1

In example 1: The hover for `arg` should match what it does when there is no hyphen:

Image

Issue 2:

The description for arg1 should appear exactly as arg2 does.

### Additional information about the issue

Issue #61603 identified the first issue, but framed it as a bug related to not supporting TSDoc. Since jsdoc explicitly mentions the [optional hyphen](https://jsdoc.app/tags-param), this is not an issue specific to TSdoc. TypeScript support in VSCode should render this properly.

Contributor guide

Open the contributing guide

Research direction

Reproduce the two TypeScript/JSDoc examples in VS Code and inspect the hover-rendering path for parameter documentation. Compare hyphenated and wrapped descriptions; done means the optional hyphen does not create an unintended bullet and wrapped @param text renders like the unwrapped parameter description.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript, vscode
Domain
developer-experience, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 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.