Allow CompletionItem.detail to show syntax coloring

[mjbvz]

Feature request

Provide an api for syntax coloring the .detail section in a CompletionItem. For example, in:

The function alert(message?: any): void text would be colorized as typescript code.

Two possible ideas on how this could be implemented:

Proposal 1

Allow detail to be a MarkdownString

export class CompletionItem {
     ...
    detail?: string | MarkdownString;
    ...
}

Pros

• Support other text markup such as bolding text

Cons

• Perhaps too flexible since the detail text should always be a single line and should not contain things like images or bullet points

Proposal 2

Add a new language field for the detail string:

export class CompletionItem {
    ...
    detail?: string;
    detailLanguage?: string;
    ...
}

Pros

• Standardized API that makes it very clear what the intended use case is

Cons

• Less flexibility

I'm more in favor of something along the lines of the second proposal

[mjbvz]

@jrieken Can you please take a look at these proposals and let me know if you have any feedback or another idea of how this could be implemented

[KamasamaK]

I'm not sure if this should be a separate issue, but what about applying the same solution to SignatureInformation.label?

[jrieken]

@KamasamaK The UI that shows labels is really minimal and the idea of the label is to be not much more than a single word. What is your use-case?

[KamasamaK]

@jrieken Are you referring to the UI for CompletionItem.label? It appears to me like the UI for SignatureInformation.label is largely the same as CompletionItem.detail and would be as long as the full signature which can be many words. Perhaps this is just an issue of inconsistent naming.

Here are examples from VS Code's TypeScript extension:

Completion

Signature

[mjbvz]

Moving out of October as this needs some more thought.

@jrieken brought up some concerns:

• Additional colors could be overwhelming. Current detail coloring is intentionally subdued

• The code returned by extensions for the details is not always valid. TypeScript for example returns strings like:

  interface Foo
  var Foo: Foo

  I've opened Discussion: Syntax highlighting for CompletionEntryDetails displayParts TypeScript#19052 on the TS side to discuss how we could address this

[jrieken]

(from #106862 (comment))

I actually don't think that we want this. Today, details show inline with the item label or atop the documentation. We cannot render markdown as inline label which would mean no-details for markdown-style-details which then would make then just like documentation. So, the low hanging thing is to use the documentation property which does support markdown and then either leave out details or have some plain text in there.

Also, we have plans for richer labels that allow to show things like label, signature, qualifier, and type (#39441). With that details would only be shown in the details panels and when omitted it isn't shown.

[kjeremy]

@jrieken Is that actually planned out for a release?

[jrieken]

@kjeremy Do you mean #39441? The work is kinda done tbh. There is some API finalisation mostly around the question if we should name those label parts with "programming terms" like signature, qualifier, and type or if we should use generic terms like description, detail etc. What has hold us back is TS being unable to implement this and therefore us being unable to selfhost/verify this