Upstream inlay hints

[kjeremy]

Should we upstream this as a proposed api?

[kjeremy]

We should look into this after #3394 is resolved. It may be a stepping stone to push microsoft/vscode#16221.

[matklad]

I don't necessary think we should wait for VS Code to provide API here. I think it might make sens to prep a proposed API before that, it can be implemented, albeit in a hacky way, in today's Emacs and VS Code. Might make sense to create an issue on the LSP repo and ask if they have capacity to review protocol changes.

[kjeremy]

Yep! I think the LSP side is the first step.

[kjeremy]

@Veetaha @matklad

You may want to jump in on the issue I created in the vscode-languageclient repo.

[SomeoneToIgnore]

We've got a great upstream proposal 🎉
Here's the comment with it: #5123 (comment)

==============================
@jrieken , let's continue the upstream discussion here: an open issue seems to be the more appropriate place for this.

I have a few bullets with the proposals and questions, in no spefic order of importance.
I've tried to elaborate every one of them, sorry for the wall of text.
If you want to, we can discuss every one of them separately here or in Zuilp if that's simpler for you.

• first, a very small nit comment: current tsdocs are a bit confusing in https://github.com/microsoft/vscode/blob/971190e4d0ff4878f1bf5e09501bb7dcf1c55afc/src/vs/vscode.proposed.d.ts#L1948-L2023

The range of the hint

(the tsdoc on the field and the constructor)

If I've understood the fooLang example right, it's not really a range of the hint itself, but rather the range of the element this hint applies to.
If I'm wrong, then it's a bit strange (also cumbersome and error-prone) that I have to specify both the hint start, end and the label: feels like the end can be derived automatically then.

The range for which line hints should be computed.

Not sure what a line hint is, guess that have to be inline.
Also, looking at the search results, "inlay hints" are way more popular than "inline hints", so it might slightly less confusing to use the former naming.

• do we define how the editor behaves during selection and navigation around the hints?

This is one of the biggest sources of confusion for people using RA, I'd like to talk it through explicitly. Currently, our decorator-based approach makes the caret "jump" near the end of the element with the hint: #2888
Something similar happens with the hint that is located before the element, not after.

It would be great to explicity define how the caret should behave in such cases, including the modifier keys (alt + arrow that forces the caret to skip the whole word is a great case).

• whitespaceBefore / whitespaceAfter are rather odd in my opinion

I can hardly imagine why would we need to add those and when: if we'd want to add a whitespace, we'll add it on the server side, we are already adding things like : for the type hints.
We use different style customizations, I'll describe them in the next bullet, might be good to merge them together if you think they are useful still.

• no way to customize the hints' style

We use a number of style options on our hints, some of them can be customized by the users: color, backgroundColor, fontStyle, fontWeight, textDecoration.

https://github.com/rust-analyzer/rust-analyzer/blob/77ffe137f2691164b199abfbadd14f73abede48d/editors/code/src/inlay_hints.ts#L60-L64

It does not have to be configured the same way and can be moved into a theme settings, for instance, but still nice to have and have the docs for that.

• no way to specify the position of the hint in relation to the element it hints

We use both "before element" (for parameter name hints) and "after element" decoration (for type hints and chaining hints), but I don't see any parameters related to that in the proposal.

• description, especially the markdown form of it also seems to be more of a special case, see the next bullet for the more generalised proposal.

Frankly, I have no idea why would I want to show another hover pop-up, the variable hover covers the majority of the use cases for me. Maybe I'm just missing a good usecase example here.

• add ways to interact with the hints

intellij-rust allows ctrl/cmd + clicking on the hints to navigate into the definition (and it respects generics and other complex types' parts!), highlights different parts of the type on hover and unfolds shortened hints on a regualr click: intellij-rust/intellij-rust#4217

It would be great to provide some kind of a callback (done lazily in another request maybe?) that allows the server to return whatever it wants to do on hover (markdown, text, just highlight the hint, etc.) and on click, potentially with the modifier keys (unfold the hint, navigate into the type, etc.).

For that, some additional data might be needed, see the next bullet.

• no way to pass additional data in the hints' objects

Since the hints display logic ideally needs to follow the resolve pattern and be stateless, it's way simpler to pass around some additional data storage between requests, similar way VSCode has CompletionItem.data field that helps during the resolve stage.

For example, we have different kinds of hints (parameter, type, chaining) and that requires different handling, especially if we want to add actions or any other complex things in our logic.

• add caret position (line, selection, etc.) to the provideInlineHints method.

Despite all our efforts to shorten the hints, there are plenty of cases where the code gets bloated with them.
One of the ways to handle that is to provide the way to turn the hints on and off and we do this already.
A better way seems to display the hints for the line with the caret only (or, reversed, hide the hints for the line with the caret).

[kjeremy]

@DanTup you may be interested in this as well. I know that flutter provides hints at the end of lines when building widgets.

[DanTup]

@kjeremy ooh interesting, yes I am interested! I'll have a proper read through soon and post any feedback on the VS Code issue. Thanks!

[jrieken]

whitespaceBefore / whitespaceAfter are rather odd in my opinion

With server-whitespaces you cannot escape the bounding box, e.g the whitespace-characters will inherit the background color and whitespace[Before|After] should be seen as margin around the hint.

If I've understood the fooLang example right, it's not really a range of the hint itself, but rather the range of the element this hint applies to.

Hints having a range is for an emepheral mode where hints would actually overlay source text. VS supports this mode, e.g while you hold Alt+F1 hints are rendered on top, not in between. This comment contains a good sample: microsoft/vscode#113285 (comment). We haven't actually implemented this yet and it's not P1 right now.

do we define how the editor behaves during selection and navigation around the hints?

Agreed. But it is hard to come up with good rules. Also, we do use the same approach for color-decorations in CSS files and haven't gotten too much negative feedback. Maybe it is something you need to get used to and something that shouldn't be controlled by extensions but by user-settings. Tho, it is likely that we are taking this as an opportunity to revisit the underlying implementation in the editor. I will update you as I know more.

add ways to interact with the hints

That's an interesting one. I will need to see how to best fit that into our API. One thing that comes to my mind is a subset of markdown (no tables, lists, etc) which allows for some styling and links. Links in return can be command-links or "normal" resource/file links. With that we might also address the styling concerns - tho, I am also unsure if that's an extension or user setting... We generally try to avoid the "looks like a christmas tree" problem by keeping control with users. The current implementation does define theme colours (for background and foreground) which users or theme can tweak.

add caret position (line, selection, etc.) to the provideInlineHints method.

Unsure about that. We try to design our language API editor-agnostic, and we would need to find a nice way abstract that away. E.g. keep the LiveShare scenario in mind: there might be another user using the API without "your" renderer having an editor open for that document.

If you want to, we can discuss every one of them separately here or in Zuilp if that's simpler for you.

Despite having an API proposal and implementation we are still in early phases. I would really value if we can meet (Teams what not) so that I can pick your brain live and so that you can demo to me what you currently have

[flodiebold]

I am not a fan of hiding or showing inline hints based on cursor position, personally. I think it will lead to a lot of things switching around while moving through code. (And if something like that is implemented, it would probably make sense to do it on editor level, not in the providers.)