Line breaks in JSDocs/Markdown comments render inconsistent space in Intellisense boxes.

[craxal]

• VSCode Version: 1.4.0
• OS Version: Windows 10

If I have a JSDocs header like this:

/**
 * @summary Does something.
 * @description This is a long description. In code, this description can get pretty long,
 * so I will break it up into multiple lines for easier reading.
 * - Example bullet
 * - Example bullet
 *
 * @returns A value.
 * 
 */

VS Code's Intellisense box renders it like this:

@summary Does something.
@description This is a long description. In code, this description can get
pretty long,
so I will break it up into multiple lines for easier reading.

• Example bullet
• Example bullet

@returns A value.
function ...

When I'm expecting something more like this:

Does something.

This is a long description. In code, this description can get
pretty long, so I will break it up into multiple lines for
easier reading.

• Example bullet
• Example bullet

@returns A value.

function ...

[joaomoreno]

@jrieken Isn't this up to each language to implement? Understanding @summary and @description?

[jrieken]

I believe this is about spacing in LI-tags

[joaomoreno]

I don't think so.

@craxal If the list item spacing bothers you, #11101 is the issue to follow. If, on the other hand, you want the language server to understand @summary and @description in docs, vscode-typescript is where you should file that issue.

[craxal]

To clarify, I see these problems when writing in Typescript. Apologies if this should be brought to the Typescript team.

This is about line spacing more than the @summary and @description tags. The Intellisense boxes (or whatever they're called) render lots of extra whitespace. For example, it doesn't seem to distinguish paragraphs well. When I break up a long description comment into multiple lines, the box renders those breaks as-typed. It shouldn't actually do that unless an empty line is in between the breaks. Similarly, the box renders a log of space between list items.

I bring up the tags, however, because @param tags seem to be handled well enough. Hovering over a parameter name in a function definition opens up a box that renders the correct @param text. It even drops the JDocs type information. If @param is recognized, why not other tags, such as those I mentioned?

[joaomoreno]

Yep, for spacing, follow #2330 (also see last comment).

As for understanding tags, that is definitely another issue.

[craxal]

Ah. Great. Good to know this is being worked on. Thanks!