Clarify CompletionItem.labelDetails.detail rendering

Usually, the LSP specs are written in a way to stay away from UI details, but not so for the CompletionItem.labelDetails.detail property, which explicitily demands that clients should render it less prominently and without any spacing:

  /**
   * An optional string which is rendered less prominently directly after
   * {@link CompletionItem.label label}, without any spacing. Should be
   * used for function signatures or type annotations.
   */
  detail?: string;

I think that it is a questionable design choice to allow/suggest to use this property for type annotations, because type information are also possible in the CompletionItem.detail:

  /**
   * A human-readable string with additional information
   * about this item, like type or symbol information.
   */
  detail?: string;

This has led to much confusion for clients and for servers to decide where to put what information, and various servers do use the fields in different ways now.

If clients closely follow the specs to render it without any spacing, problems like the following occur (https://github.com/sublimelsp/LSP/issues/2169):

Here is

• CompletionItem.label - NaiveDateTime
• CompletionItem.detail - struct
• CompletionItem.labelDetails.detail - struct
• CompletionItem.labelDetails.description - NaiveDateTime

Sublime Text, elixir-ls 0.13.0

You could argue that the description mentions that the labelDetails.detail should be "rendered less prominently", but I think this demand is too much based on VSCode and we can assume that a lot of editors don't have this ability.

Some servers, like the D server, might also decide to add spacing themselves: https://github.com/Pure-D/serve-d/blob/84094fade433f3d52e43c5296d20af53b102ffdd/source/served/commands/complete.d#L1073

This is not the first time where such an issue with the labelDetails came up, by the way. And if the client ignores the specs and adds additional spacing as a workaround, then this only leads to more confusion in the future, if other servers see that it will automatically rendered with spacing if they test their implementation with certain clients.

It would be nice to clarify the expectation on how the labelDetails.detail should be formatted (i.e. leading whitespace from servers or not, whether to prepend a colon like : struct in case of type annotations), or only allow it to be used for function signatures.

Here are three different suggestions with possible solutions:

1. Only allow labelDetails.detail to be used for function signatures:

     /**
      * An optional string which is rendered less prominently directly after
      * {@link CompletionItem.label label}, without any spacing. Should be
      * used only for function signatures.
      */
     detail?: string;
   

2. Allow clients to handle spacing:

     /**
      * An optional string which is rendered less prominently after
      * {@link CompletionItem.label label}. Clients are allowed to add additional
      * spacing. Should be used for function signatures or type annotations.
      */
     detail?: string;
   

3. Demand from servers to handle spacing:

     /**
      * An optional string which is rendered less prominently directly after
      * {@link CompletionItem.label label}, without any spacing. Should be
      * used for function signatures or type annotations. In case of type
      * annotations, servers should prepend a space if the type annotation
      * starts with a letter.
      */
     detail?: string;
   

Start with the linked LSP 3.17 specification section for CompletionItem.labelDetails and compare it with CompletionItem.detail. Review the linked Sublime Text issue and serve-d implementation to understand the differing formatting expectations. Done means the specification clearly defines the intended use and spacing behavior.