Add additional (or custom) InlayHintKinds

[DanTup]

In Dart, we use Decorations to show the names of constructors/methods alongside their closing parens to make it easier to match them up:

The data for these is provided using custom notifications from the language server. I was hoping with InlayHints I could move these over to something more standard (in LSP). However as I came to implement it, I found InlayHints only have specific kinds for type/parameter placeholders (see InlayHintKind).

While kind is optional, in LSP it says:

/**
	 * The kind of this hint. Can be omitted in which case the client
	 * should fall back to a reasonable default.
	 */

This "reasonable default" suggests that not providing a kind could result in the hints being styled to match types/parameter names, which might not be a great experience.

It would be nice if either there were some additional kinds that could be used for the sorts of annotations shown in the screenshot about, or a way to provide custom kinds (where it's up to the client extension to provide some theming for them).

There's a similar feature called InlineValues that I thought may also work here (specifically InlineValueText), however its description explicitly mentions being debugger related, so it's not sure if they would only appear while debugging (and if not today, whether that's guaranteed in future).

[thaliaarchi]

I also find the InlayHintKind values restrictive for my use case. I am building a language server for Whitespace that will display the opcodes inline in the invisible code, to make editing easier. These aren't type or parameter annotations, but rather display the statements in an alternate syntax.

For example, here is roughly what a program would look like with the inlay hints interspersed:

push·1   	
label·C
   	    		
dup 
 printi	
 	push·10   	 	 
printc	
  push·1   	
add	   dup 
 push·11   	 		
sub	  	jz·E
	  	   	 	
jmp·C
 
 	    		
label·E
   	   	 	
drop 

end

I've also written a little more about it in a gist, which includes this program in the standard syntax, assembly syntax, and with inlay hints.

[jrieken]

Just to clarify: this isn't blocking you from adopting inlay hints, right? You can still have them with default styles (e.g kind being undefined). Having more styles would be the cherry on top, correct?

[DanTup]

@jrieken how are they styled in VS Code if they have no kind? Can the user customise them?

My currently implementation using Decorations has a custom color (which is quite faded), and some users customise it. The default styling is less subtle and it's not clear if the user would need to modify some style that is named as if it was a type name or something (or if the styling will be forever tied to the parameter names styling if I adopt InlayHints for those in future).

[DanTup]

Something similar came up again at Dart-Code/Dart-Code#4240.

In Dart documentation comments, you can use "macros" to avoid duplicating blocks of documentation:

/// {@template example}
/// Hello world
/// {@endtemplate}
void fn() {}


/// Before
/// {@macro example}
/// After
void example() {}

If you hover over "example" here, the {@macro example} is replaced by "Hello world". The request is to do the same inline in the code. This is possible with Decorations in VS Code today (we could inject the text underneath the @macro line), but it feels better done as something that is standard LSP. If InlayHints fit, it would require custom styling because the type/parameter name styling wouldn't look good here.

If Inlay Hints is not a good fit, I wonder if it would be reasonable to support some of the Decorations API into LSP - or something more specific for this kind of use case? (@dbaeumer - your thoughts?).

[dbaeumer]

I would rather not add decorations to LSP since they are very editor / UI specific. As @jrieken said it is supported by inlayHints it is just that you can't style them right now to your likings. Right?

[DanTup]

@dbaeumer for the initial item mentioned here, yes - styling is the only issue. The later example above depends a little on whether it would be reasonable to use Inlay Hints for multiline blocks of text. If so, then it would also fit in Inlay Hints as long as custom kinds/styling was supported (this would be my preference but multiline blocks of text doesn't seem like what they were originally intended for, so I'd like some confirmation that's reasonable in case they don't display correctly now or become broken with linebreaks in future).