Vscode: Explore improving UX for IntelliSense

[misolori]

This exploration will aim to unify the IntelliSense features (hovers, completions/suggest, parameter hints) in style and content. Additionally, we will explore to address the positioning of parameter hints (currently shown above the cursor).

Related Issues

• Shorten method signatures https://github.com/Microsoft/TypeScript/issues/14662
• Better structure for IntelliSense #50813
• Add opacity setting for IntelliSense #22439
• Better positioning of popup #60534
• Add syntax highlighting to suggest widget #60651

Current Design

Explorations

Exploration A

• Moves parameter hints below cursor
• Combines parameter + suggest widget
• Reduces opacity of entire widget to 95%

Exploration B

• Same as Exploration A
• Increases width of widget to show single line
• Aligns widgets based on cursor

Exploration C

• Same as Exploration A
• Aligns widgets based on cursor
• Adds parameter hints inline as shadow completions

GIF Example

[beastdestroyer]

I'm all for C, only problem I see is if you don't fill in all parameters, say only 3 out of the ones in grey text, it could perhaps auto adjust to the ones filled in?

I also feel that the code shown in the beginning is all a scramble, as the case has been for a while, I and many others could. benefit from a more prettier layout (as in the hint code)

[eamodio]

I definitely like Exploration C the best -- the alignment seems better ( but would love to try it to get a better feel for it), and I really like the parameter hints. Although I can see overloads being a challenge there.

I also have to say I really don't like the opacity exploration -- unless the opacity became full as soon as you navigated the list (otherwise I feel like it make it harder to parse, since you get competing text below it). Although a blurring effect could help with that, but then I don't see how that would improve over a full opacity.

At the same time, I do like what VS does -- have a hotkey (they use Ctrl) to make the popup very transparent (so that you can see underneath it) on demand.

[misolori]

...say only 3 out of the ones in grey text, it could perhaps auto adjust to the ones filled in?

@beastdestroyer can you expand on this?

@eamodio thanks for the feedback, we really do appreciate it! For the opacity change, there were two ideas that we discussed:

1. Create a setting that would allow a user to configure how much opacity they'd want to set the entire widget to (not everyone will want this feature)

2. Auto-dimming the widget on a key command (just like you mention in VS) where the opacity goes down low (~10%).

[benfrain]

C. As an aside is it worth considering performance at this point? I’d imagine opacity is going to have some cost over fully opaque. I’m not suggesting ruling it out prematurely on that basis but perhaps something to keep in mind

[eamodio]

@misolori no problem! Those options sound good (especially since they are opt-in/out) -- although I still do think opacity without some blurring just ultimately hurts the readability.

[Da13Harris]

All the options appear to be an improvement IMO. As long as the pop-up widget is generally positioned below the cursor, I'll be pleased. As it currently stands, it often covers code above the cursor that I'm trying to reference.

FWIW, I really like option C. It saves visual real-estate and reduces complexity of parameters that are already complete. I could, however, imagine some issues when re-visiting a method with parameters that have already been completed. Maybe it could include a "subtle" UI toggle feature to show/hide the method signature?

[beastdestroyer]

@misolori For example, say you filled in fileBackup, then matchingString but skipped all the way to maximumBytesToRead. I'm sure there would have to be a way to detect which values are for which parameters

EDIT: By prettier layout, instead of readToMatchingString(file: string, matchingString: string, chunkBytes: number, maximumBytesToRead: number): Promise<string>

It becomes
typescript readToMatchingString( file: string, matchingString: string, chunkBytes: number, maximumBytesToRead: number ): Promise<string>

Or any other clean vertical format, since people prefer vertical reading than reading horizontally; and it'd look nice. This would look nice on A

[mxplusb]

Honestly, I like B more since it leaves more room for more functions with more parameters.

[peterfraedrich]

I would love to see the parameter hints popup have the ability to be docked as either a new tab in the bottom tray [green] (with the terminal, debugger, etc.) or on the left sidebar as a pane [red] (with outline, file tree, etc.).

At the very least let us add custom CSS to move it where we want.

[fantacytyx]

I like C. bug where to show the method description?

[misolori]

@beastdestroyer do you have an example where parameters can be skipped in the middle? As far as I know, optional parameters are at the end. See TypeScript's Optional and Default Parameters doc as an example. Or do you mean to have a way to set a parameter as "undefined" or "null" so that it "skips" it?

In terms of the layout of the completions, I could see us providing an option to show the parameters inline or in a "Prettier" format:

But then that would introduce issues with the positioning of the suggest widget since it would be covering the rest of the parameters below. This is where the user could hold a key command to dim the suggest widget to see the content behind it:

[misolori]

@fantacytyx we currently show method descriptions in the suggest widget when there are no items selected:

So I would try to use the same concept and also pass in the parameter description:

[beastdestroyer]

@misolori Oops, I didn't necessarily mean it. in the actual editor, but rather in the widget, but perhaps that option could be configurable via an API for extensions such as Prettier and Beautify. Maybe it could also auto-scroll to the next line in that case. I do also like that opacity solution, maybe it could be more opaque, since. I can just about see it, maybe roughly 5 - 15% opaque.

Also, I didn't know that it was at the end, I haven't looked at this type of stuff in-depth, I'm not exactly sure how to explain it, but something similar. Like if you wanted to skip chunkBytes and go to maximumBytesToRead, but they're both numbers, how would that work for example, without setting undefined or null. Or perhaps in generic parameters in JavaScript or other languages, and you don't use every parameter, how would it know? Or is it just there to show and leave it up to the user (which would make sense)

[misolori]

@beastdestroyer if the parameters were inline we'd definitely auto-scroll to the next line after hitting enter. For the opacity, it's hard to balance making the text behind it readable and also know that the widget it dimmed. So in the gif I made it 5% so the text behind it is readable.

[patrys]

@misolori Python has named params so for a function with a signature of:

def foo(bar, baz=None, xyz=None):
    ...

It's entirely valid to call it as:

foo(xyz=1, bar=5)

Notice that it not only skips the middle param, it also provides the other params in a different order.

[lppedd]

@misolori what about merging data types with the parameters' names? So no additional little popup on the right would be needed.

[misolori]

Here's an example for parameter descriptions where we can show the description of each param inline (like we do today when the description is closed):

And when you expand the description it'll show to the right:

As you fill in the params, we can show both the suggest & param descriptions together.

[lppedd]

@misolori I like this actually! Could you maybe display all the data types/return types next to the symbol names? Like

|readToMatchingString           void|
|ready                       boolean|
|require                        void|

[misolori]

Given the feedback here (and internally) Exploration C will be the concept that we will further explore.

[misolori]

Closing issue as explorations are completed, will refer to this issue when the change is made.

[usernamehw]

@misolori What about this comment https://github.com/Microsoft/vscode/issues/63144#issuecomment-439273105 about placing parameter-hints somewhere that it won't obscure context around the cursor?

Nvm. There's actually an open issue about that #51253

[bmewburn]

For exploration C will the parameter/signature description and completion description be styled so that they are obviously distinct from one another? It's hard to tell which description refers to which element in the gif. Which description gets priority? If a completion description and signature/param description are both lengthy which gets shown?

[octref]

I unlocked and is adding more related issues:

EDIT (10/25/2019): More Related Issues

• Parameter Hints shown inline all the time (like IntelliJ) #16221
• Create an option to position the intellisense parameter info top or bottom. #33752
• option to display parameter info tooltip in a separate pannel #51253
• Tooltips gets in the way of general operations in the editor #15667

Overall I think this design should also come from a functional POV: widget on top of cursor block important information useful for continue writing code.