Feature: Inlay Hints

[kjeremy]

I would like to upstream rust-analyzer's inlay hints feature. This allows an editor to place annotations inline with text to display parameter names, type hints etc.

See: microsoft/vscode-languageserver-node#609 for the proposal.

[rcjsuen]

var someNumber = 123;

@kjeremy Given the above JavaScript code, the range in the returned InlayHint would be { start: { line: 0, position 4 }, end: { 0, position: 14 } } so that it encompasses the someNumber variable, correct?

Can you provide examples of a parameter hint and a chaining hint?

[Veetaha]

What we do in rust-analyzer is:

1. Send a request rust-analyzer/inlayHints on any source change (i.e. any character typed, any file moved/created/deleted etc.).
2. As a parameter we pass { textDocument: TextDocumentIdentifier } for the particular file we need to get inlay hints for.
3. The server responds with an array of InlayHint objects for the requested file.

Here is a simplified, stringly-typed version of it (we use a discriminated union at our repo instead):

import * as lc from "vscode-languageclient";

export interface InlayHint {
    range: lc.Range;
    label: string;
    kind: string;
}

export interface InlayHintsParams {
    textDocument: lc.TextDocumentIdentifier;
}

const inlayHints = new lc.RequestType<InlayHintsParams, InlayHint[], unknown>(
    "rust-analyzer/inlayHints"
);

The client-side implementation for this feature is very straight-forward and actually fits into < 250 lines of code. It currently uses the vscode text decorations feature (more precise inlay hints are after and before css pseudoelements), but this feature is very limited.
Current limitations:

1. It feels unnatural when the cursor goes through the inlay hint, it's hard to describe it better be seen:
   
   The cursor kinda jumps through the hint and the nearby token. IntelliJ, for example, emulates the inlay hint being a real holistic token in the editor.
2. As you can see on the .gif these after and before pseudoelements inherit the styling from the token they are attached to. This means whenever that token (e.g. the variable name, a paren, a coma etc.) changes its style (e.g. is highlighted, outlined, etc) the inlay hint changes its style along with it, which is unwanted...
3. Text decorations don't let you tweak too much of their style. For example, we cannot change their font size to make them a bit smaller and vertically center them in the middle of the line of code.

Our current implementation can be very easily generalized and integrated into LSP:

1. The inlay hint kind should not be a fixed enum (I propose to change it in this PR @kjeremy), but just some string identifier for which the user can customize display styling. This gives lsp server developers the flexibility to add new kinds of inlay hints that they can think of without changing the protocol, and the editor should be abstract and not provide any ad hoc implementation (but we might consider the protocol to specify the well-known inlay hint kinds where special support for them may be implemented (e.g. by clicking on the type hint the editor invokes goto-definition of the type, or by clicking on the parameter name hint it invokes goto-definition of the parameter on the function that is invoked, etc.)
2. The server itself should decide to which token and on which side (after/before) of the token the editor should place the inlay hint. So we might modify the InlayHint interface:

   interface InlayHint {
       range: lc.Range;
       kind: string;
       label: string;
       position: "after" | "before";
   }

3. The strategy for invalidating the inlay hints should also be tweakable. For example, the server should register the inlay hints capability with the following options for invalidation.
   Just a naive scratch of invalidation events:

   enum InlayHintsInvalidationEvents {
       TextDocumentContentChanged = 0b0001,
       WorkspaceFileRemoved = 0b0010,
       WorkspaceFileAdded = 0b0100,
       WorkspaceFileMoved = 0b1000
   }  

So this describes the pull-based implementation of inlay hints that is currently used at rust-analyzer.
We might think of a push-based implementation instead, where the server can decide whether inlay hints are invalidated or not, but I guess we cannot easily implement it via only LSP protocol right now, this might require some more changes to the protocol to let the server always know which text documents are opened in the editor at any point of time.

Maybe @matklad can elaborate on Intelij where they've natively implemented this feature and which model/API they've considered best to be used.

[Veetaha]

@rcjsuen the chaining hint is a type hint that is displayed after each chain of the multiline method call.

Example

[Trass3r]

Linking this to microsoft/vscode#16221.
Edit: Looks like it didn't work. Locking the thread even disables the 'mentioned this' links 🙄

[mickaelistria]

Isn't it a dup of #405 ?

[Trass3r]

Well they designed it to be separate from CodeLens but there is indeed an interesting overlap.
Like this proposal is lacking commands that could be useful for click actions.

ccls for example implemented a custom solution for inline CodeLens as well.
Maybe extending codelens instead with an inline parameter could do the job.

[mickaelistria]

And isn't it also a dup of #745 ?
The current proposal seems quite complex to me while the protocol seems to already have something very similar that can be enriched.

[matklad]

Yup, seems like there are at least four threads of discussion about LSP:

• Feature: Inlay Hints #956 (this)
• Feature request : textDocument/inlinedAnnotation #745
• support for inline codelens #405
• Feature Proposal: Inlay Hints vscode-languageserver-node#609

• Parameter Hints shown inline all the time (like IntelliJ) vscode#16221 (vscode support)

It makes sense to do some issue garbage collection at least :-)