Provide API to return formatted content from suggest and parameter hints

[joaomoreno]

Take the following snippet:

/**
 * Some documentation is **nice**.
 * 
 * Example usage:
 * 
 * ```
 * function main() {
 *   return hello('world');
 * }
 * ```
 */
function hello(world: string): number {
    return 1337;
}

Here's how it looks in different widgets:

Hover

Suggest

Parameter hints

Widgets look now somewhat aligned, since #2330. Their contents, on the other hand, could be a bit more.

Hover looks great, since at some point we provided the possibility of returning MarkedString through the API.

Both suggest and parameter hints lack that and look pretty pale in comparison.

We got to find a way to advance the API allowing users to return formatted content from certain API calls without bloating the API too much.

[joaomoreno]

@jrieken Not sure whether we already have an issue for this.

[aeschli]

API wise, I'd suggest the following non breaking changes: Whats new are the | MarkedString[] additions.

export class CompletionItem {
   label: string;     // leave as is... Otherwise things get complicated with the completion highlights
   detail: string | MarkedString[];
   documentation: string | MarkedString[];
   /// ...
}
export class ParameterInformation {
   label: string;  // no change ?
   documentation: string | MarkedString[];
}
export class SignatureInformation {
   label: string; // no change ?
   documentation: string | MarkedString[];
}

The following additions are optional, but IMO nice for consistency. For the hover constructor I'd suggest to break the behaviour and release-note that, or and add a new one like shown below.

export class Hover {
   contents: string | MarkedString[];   // adding string for plain text

   /** deprecated: Use constructor(range, string | MarkedString[]) instead.*/
   constructor(contents: MarkedString | MarkedString[], range?: Range);  // no change. 
   constructor(range: Range, contents: string | MarkedString[]);  // order changed, range can be null or undefined
}

For DecorationOptions, we can leave it as is or I suggest to do the following change which fix another API issue with the decoration API (which is not urgent, but just came up recently)

export interface DecorationOptions {
   /** deprecated, use textHoverContents or gutterHoverContents instead */
   hoverMessage?: MarkedString | MarkedString[];

   textHoverContents?: string | MarkedString[];
   gutterHoverContents?: string | MarkedString[];
}

[mjbvz]

With @ramya-rao-a's work on the completion view, the lack of syntax coloring / markdown in completion item documentation is much more noticeable. Can we revisit this?

Since #19779 wasn't considered the right approach, what are thoughts on alternatives? @joaomoreno mentioned a CompletionItem2 as one possibility. Another thought would be to add optional rich text fields to CompletionItem that take precedence over the current plain text ones:

export class CompletionItem {
   label: string;

   detail?: string;
   richDetail?: MarkedString[]; // If present, would be used in place of `detail`. Would need a better name

   documentation?: string;
   richDocumentation?: MarkedString[]
   
   ...
}

The would keep the API backwards compatible but it's still ugly. Other thoughts?

[jrieken]

Idea is to use a new type that subsumes MarkedString but also allows for other things like HtmlString (think of javadoc). Ideas are early, we don't ugly and something that lasts for a little longer. It should also remove the ambiguity the marked string has today (when to escape and when not)

[aeschli]

Note that any change also needs to go into the language server protocol and it would be nice if we keep the APIs as similar as possible (not a must, but it's a better story). FYI @dbaeumer

The feedback we got from the snippet work was that we should not change the shape of property types (e.g. from string to string | MarkedString[]) as this breaks old language client implementations. For the snippetText we went with an additional 'format' field where you specify what the string format is.

In this case it would be new optional fields 'detailFormat' and 'documentationFormat` on the completion item. Values are of a number enum: 'PlainText' or 'Markdown'. The default would be 'PlainText'.

[jrieken]

This will be enabled with the work we are doing for #29076

[mjbvz]

@jrieken Are you already looking into updating Suggest and/or Parameter hint to use MarkedString, or should I take a stab at it?

[jrieken]

This is the issue to do that and I have scheduled it for September.

[jrieken]

The API is there, the UI is adopted, it is now up to the languages to return completion items and signature help that uses it. fyi @mjbvz