Language-server-protocol: Detailed Completion Label Support

[david-driscoll]

I'm looking at the new detailed completion label support, and would it be possible to make it a new property instead of a new union type? Or perhaps a new type entirely?

Every union type causes a binary breaking change for some compiled languages, like C# (and Java I think as well). This forces a breaking on our consumers, and all downstream code. A new property would make it much easier to gracefully support this feature, and avoid adoption delays.

cc @ntaylormullen @ryanbrandenburg @TylerLeonhardt

Proposed changes:

/**
 * A more detailed label for a completion item.
 *
 * @since 3.17.0 - proposed state
 */
export interface CompletionItemLabel {
    /**
     * The name of a function or variable.
     */
    name: string;

    /**
     * The parameters without the return type.
     */
    parameters?: string;

    /**
     * The fully qualified name, like package name or file path.
     */
    qualifier?: string;

    /**
     * The return-type of a function or type of a property/variable.
     */
    type?: string;
}

export interface CompletionItem {

    /**
     * The label of this completion item.
     *
     * If the label is of type `string` it is also by
     * default the text that is inserted when selecting
     * this completion.
     */
    label: string;

       /**
     * @since 3.17.0 - proposed state -  support for CompletionItemLabel. See
     *  also the client and server capability
     * `completionItem.detailedLabelSupport`
     *
     * If the detailedLabel is of provided the `name` property
     * is also by default the text that is inserted when selecting
     * this completion.
     */ 
        detailedLabel?: CompletionItemLabel;

        // ...
}

[KamasamaK]

As one of the maintainers for LSP4J (Java LSP SDK), I can confirm that these kinds of changes are breaking changes for us as well.

[dbaeumer]

The problem with that approach is that a user now has to fill in a label and a detailedLabel and that the value of label is basically never used.

I better approach would be:

/**
 * Additional label details (observe no name property
 *
 * @since 3.17.0 - proposed state
 */
export interface CompletionItemLabelDetails {
    /**
     * The parameters without the return type.
     */
    parameters?: string;

    /**
     * The fully qualified name, like package name or file path.
     */
    qualifier?: string;

    /**
     * The return-type of a function or type of a property/variable.
     */
    type?: string;
}

export interface CompletionItem {

    /**
     * The label of this completion item.
     *
     * If the label is of type `string` it is also by
     * default the text that is inserted when selecting
     * this completion.
     */
    label: string;

       /**
     * @since 3.17.0 - proposed state -  support for CompletionItemLabel. See
     *  also the client and server capability
     * `completionItem.detailedLabelSupport`
     */ 
        labelDetails?: CompletionItemLabelDetails;

        // ...
}

Would that work for you?

[david-driscoll]

Thanks @dbaeumer

[dbaeumer]

Done. Let me know if this now works for you.

[rwols]

So is the label now the unqualified name? (while the labelDetails.qualifier is the FQN?)

Does this mean the label is a substring of labelDetails.qualifier? Are there any "is substring of" relations?

[dbaeumer]

I think that depends. Without labelDetails it is the old behavior whatever servers filled in in the past. Wil a label details it should be the unqualified name.

[kjeremy]

@dbaeumer Should parameters be a string[]? How do we specify multiple parameters for eg a function?

[dbaeumer]

Making it a string allows server to format the string according to the language. If we get a string[] we can't simply concatenate the pieces using ,. There are other languages that are not separating params with ,

[rwols]

How about using one large string, while having a list of (beginOffsetUtf16, endOffsetUtf16) that denote the parameter starts/ends like in signatureHelp?

[kjeremy]

Aahhh so the format is (param1, param2) for a function with 2 parameters?
If there are no params it should be () and for non-functions it should be
null?

On Wed, Feb 17, 2021, 6:07 AM Raoul Wols [e-mail] wrote:

How about using one large string, while having a list of
(beginOffsetUtf16, endOffsetUtf16) that denote the parameter starts/ends
like in signatureHelp?

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/microsoft/language-server-protocol/issues/1193#issuecomment-780481729,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/ABBACRFUA3VINLRNNFRA223S7OPPTANCNFSM4XDNHQKQ
.

[dbaeumer]

In SignatureHelp this is mostly used for highlighting since the label must be a subpart of the out label. With completion items we want to allow clients to render a more detailed label if wanted and it felt easier to send the parts.