Proposal: treat CompletionItem#description as markdown

[rictic]

In the polymer language server we have the same documentation available for a symbol whether we're autocompleting it or giving the docs on hover. I expect most other servers to be in a similar boat. The markdown rendering for hover documentation is great, and we'd like to have similar rendering for the same content.

[svenefftinge]

In general whenever the LSP passes a strings to be displayed to the user (also showMessage for instance) it should allow the same kind of mark up.
Always assuming markdown seems good enough to me.

[dbaeumer]

@rictic are you talking about details or documentation. I agree it would make sense to allow markdown in the documentation part.

@jrieken did you have such requests against the VS Code API as well ?

[rictic]

@dbaeumer Yeah, I'm talking about documentation. No opinion on details.

[jrieken]

Yes - we have request to allow markdown in more places but haven't tackled that yet

[dbaeumer]

@jrieken cool. We keep it as a feature request then.

[felixfbecker]

The PHP stubs for the PHP standard libraries all contain HTML in their docblocks, which looks awful at the moment. Using markdown in docblocks is very common, and would also solve the HTML case, since markdown can contain HTML.

[jrieken]

and would also solve the HTML case, since markdown can contain HTML.

fyi - we currently don't allow html in markdown

[felixfbecker]

Any reason why?

[jrieken]

script execution

[felixfbecker]

Good point, but I think it would be pretty easy to not allow any <script>, <style>, onclick etc. but only basic elements like <b>, <br>, <table>, etc. If the markdown parser you're using doesn't provide this, sanitize-html is super easy to use.

[jrieken]

I still haven't found a complete list of onclick etc attributes...

[felixfbecker]

Instead of blacklisting all script execution attributes, you can just whitelist safe attributes. Normally you don't use that many attributes in HTML in markdown, it's mostly basic elements like the ones I mentioned above that could also be represented in markdown.

[rcjsuen]

Would also love it if the documentation field on CompletionItem supported Markdown.

[dbaeumer]

See microsoft/vscode-languageserver-node#276

[dbaeumer]

Implemented in the npm node modules as speced in the protocol in a backwards compatible way.

[dbaeumer]

Besides CompletionItem, SignatureHelp can provide Markdown as well.