Add options for monospace font and whitespace preservation in IntelliSense quick info boxes

[Neonit]

TL;DR / Quick Peek / Example Screenshots

Without reading any further you can see from the screenshots, what I would like to add to VS Code. It has been implemented already. Upvote this post, if you support my merge request. Just a quick entry hint: It's about the boxes with documentation text that pop up when you hover over a symbol (as known from IntelliSense).

https://imgur.com/a/elIpGTg

Motivation

The original motivation for this feature request is the treatment of documentation comments in JavaScript and TypeScript. Users of other languages providing IntelliSense quick information data could profit from this as well.

Have a look at the following JavaScript snippet.

/**
 * This inverts a number.
 * @param x {number} the number to invert; must not be zero
 * @return x inverted
 */
function invert (x)
{ return 1 / x; }

VS Code provides IntelliSense support for JavaScript and TypeScript out of the box. If the user hovers over a reference to foo somewhere in the code, a quick info box will pop up displaying the function signature and the documentation from the comment above its declaration. The documentation comment will be formatted as Markdown and some common JSDoc tags will be parsed, too, and displayed more or less fancy.

Users with other preferences for documentation comment formatting or styling may run into ugly problems because of some Markdown and HTML habits. Although they are not using JSDoc and maybe not even Markdown (completely or maybe only on the level of logical text structure, i.e. paragraphs), some might want to enjoy getting the documentation displayed when hovering over a reference.

/**
	This inverts a number.
	<=	x : number - the number to invert; must not be zero
	=>	x inverted
*/
function invert (x)
{ return 1 / x; }

While this looks good in the code itself, the quick info box will display a messy text, partly due to some bugs (see caveats below), mainly due to the way Markdown/HTML treat whitespace characters. HTML reduces any sequence of whitespace characters to a normal space, including tabs and newlines. Markdown only begins a new paragraph after two consecutive newlines. Thus, the above documentation will look kind of like this:

This inverts a number. <= x : number - the number to invert; must not be zero => x inverted

Solution

The proposed feature adds two new settings for the user to opt-in to for the text displayed in quick information boxes:

1. Toggle usage of a monospace font.
2. Setup the treatment of whitespace characters conforming to the CSS-property white-space. This should only have an effect inside paragraphs (<p>) so basic Markdown (such as headings or lists) still works normally and doesn't insert lots of newlines.

With both features configured, the display of the documentation in the second code snippet could look kind of like this:

This inverts a number.
<=	x : number - the number to invert; must not be zero
=>	x inverted

Caveats / Known Bugs

1. TypeScript is responsible for parsing JSDoc comments. Currently there exists a bug where whitespace characters at the beginning of lines within the documentation comment get stripped away. (fix and pull request are there already)
2. VS Code uses marked.js for parsing the Markdown in the documentation comments. This library unfortunately replaces all tabs by four spaces each due to some internal weaknesses. I have attempted to remove the replacement, but the linked comment left me thinking it's not a good idea. The problem are not so much the tabs used for indentation, but the tabs used for alignment, which may be less than four characters long. I'm planning to alter the replacement algorithm so mid-text tabs are replaced accordingly or not replaced at all.

Conclusion

As this is an opt-in feature it would not change the experience of users, who do not want or need it. It would, however, enrich VS Code with a new possibility to customize quick information styling.

I have implemented the feature already, so this request is merely for explanation and for linking the PR to. I am open for criticism or suggestions.

[octref]

I'm not sure if this is the right direction to go to. Currently the language server can choose to use code block or prose to choose between using monospace or proportional font.

For your example, a language server can opt into monospace font (and whitespace aware display) with:

```
	This inverts a number.
	<=	x : number - the number to invert; must not be zero
	=>	x inverted
```

This give the choice to users, and I don't feel it's a good idea. /cc @mjbvz @jrieken what do you think?

[mjbvz]

Yes I feel this should be left up to each language/extension. They would be in a better place to know how users document their code in that language

[Neonit]

A language extension should know better how users document their code than the users? This feature explicitly aims at users, who do not want an extension or language to dictate how they have to document their code. Plus, it's fully opt-in, so what do all the others lose? And with VS Code's settings system they can limit it to specific languages and/or workspaces.

[jrieken]

If these are actual bugs with TypeScript and marked.js then we should get them fixed, not use settings. Having a setting that says, don't render my doc comments the way I have authored it sounds wrong.

[Neonit]

I feel not all here are on the same page. I have made some screenshots of VS Code with my PR applied (and also the Typescript fix). Maybe this is easier to follow and understand. The two new options both do not change the basic formatting of the documentation. Markdown still works fully and JSDoc is parsed fully.

https://imgur.com/a/elIpGTg

[mjbvz]

Languages are in a better position to know how users of that language write comments. A VS Code setting is a very course approach that will likely not make sense in many languages while also not addressing the more specific needs of comment formatting of other languages

I'm marking this as backlog candidate to give the community an opportunity to chime in with other use cases