Always show return type/signature for all items in code completion

[RaviKavaiya]

Is it possible to show return type of a method in intellisense (or a complete method signature)?

Sometimes, it is much useful when we have a large number of methods available. And to pick one quickly, this will help much.

For example, in Android Studio, it shows like this:

[DanTup]

We do show the return type in the same place here:

However VS Code only shows it for the highlighted item. There's an open issue about improving this here:

microsoft/vscode#39441

If that is implemented, we should be able to improve this here too.

[DanTup]

Looks like the LSP part of this work will be in v3.17 of the spec.

microsoft/language-server-protocol#1307

[DanTup]

Looking for some opinions on including signatures more visible in code completion (today, only the item your cursor is over shows the signature, and we can't show greyed labels on the left, so the parens on each item is quite strong).

Today (without changes):

Possible changes:

1. Full signature, split between left/right
2. Full signature on left
3. Full signature on right
4. Abbreviated params (...), split between left/right
5. Abbreviated params (...) on left
6. Abbreviated params (...) on right

I think I prefer 2 or 5. 2 is a bit noisier, but seeing the parameters (when there aren't too many) is nice. It also slightly better matches the descriptions of these two labels in the LSP spec (the "detail" label which is on the left says function signatures and type annotations):

  /// An optional string which is rendered less prominently after
  /// [CompletionItem.detail]. Should be used for fully qualified names and file
  /// paths.
  final String? description;

  /// An optional string which is rendered less prominently directly after
  /// [CompletionItem.label],
  /// without any spacing. Should be used for function signatures and type
  /// annotations.
  final String? detail;

Another thing to note is that we used to show "Auto import from ..." on the right side for the selected item, but now we would either show them all the time, or only if you expand the panel to the right:

We can't mix both the new labels and have the old one show up for the "selected" item.

@bwilkerson @jacob314 @InMatrix

[bwilkerson]

Possible changes:

I can provide my opinion, but I don't have any data to back it up.

My preference would be for option 5:

• I find it harder to read when the signature is split between the left and the right, so I dislike 1 and 4.

• I more often care about the return type than the parameter types because I'm usually concerned with how to get the data I want, and will figure out later how to provide all of the arguments that are required. Including all of the parameter information sometimes causes the return type to be truncated, so I consider that to be a downside. Given that the documentation pop-up will include the full signature, I think it would be best to occlude the parameters.

• Putting the information on the left causes it to be in a larger font, so the information will more often be truncated, but even so I prefer having the member name with the signature makes it more readable.

... we used to show "Auto import from ..." on the right side for the selected item, but now we would either show them all the time, or only if you expand the panel to the right:

I have a slight preference for putting them in the panel to the right because the main presentation is less crowded that way and I rarely need that information. But the advantage of showing them always is that it's less work to get the information when it's needed, so I could see a productivity boost when the data is useful.

[DanTup]

Thanks - I think I agree. I'll wait a little longer to see if there are any other opinions but otherwise may go ahead with 5 soon (and we can always refine if we get other feedback in future).

[svipas]

I vote for 4. It is aligned with how other editors do it and VS Code as well in JS/TS env at least, but I think other languages follow the same. I just think that you should remove () and keep only (...), because () adds noise without actual value.

1 is good as well, but if params are too long we lose ability to see full return type and for some it could be too noisy. That's why I think it should be trimmed and have max length. This way we see some info about params as well as full return type.

In my opinion this could be under config with ability to change between 1 and 4. paramsWithReturnType & onlyReturnType (default).

[DanTup]

I vote for 4. It is aligned with how other editors do it and VS Code as well in JS/TS env at least,

I think TS is currently doing what Dart is doing (which not using this new functionality). It has the signature in the "detail" field (because it's the only place to put it) which is only visible for the current item (and shows on the right if you have the detail pane collapsed):

This is what Dart is doing today (in part because we can't show it on the left without it being the same style as the name). I think if TS adopts the new APIs, it would probably put the signature on the left, because the VS Code APIs describe the fields in that way (in the new API, detail is on the left and is documented as being for signatures, and description is on the right which it says is for qualifying names or file paths):

https://code.visualstudio.com/api/references/vscode-api#CompletionItemLabel

I just think that you should remove () and keep only (...), because () adds noise without actual value.

I think there's some value in () because it shows that item is callable at a glance.

[svipas]

You're actually right, it is showed for imports and snippets only. But I still like the 4, but that's probably, because I'm more familiar with it. I think () is valuable for functions, but it also shows it for classes, but since classes in Dart could be initialized without new keyword it kinda makes sense.

[bwilkerson]

I think () is valuable for functions, but it also shows it for classes, but since classes in Dart could be initialized without new keyword it kinda makes sense.

We shouldn't be displaying parens for classes, but it makes sense for them to be displayed for constructors because constructor invocations have an argument list.

[DanTup]

Yup, when you see them on a class it's really for the constructor. Class names will often appear twice in the list, once as a constructor and once as a class name. This is clearer when you have classes without accessible constructors, or constructors that take arguments:

[svipas]

Nice, thanks for info, so yeah in that case it totally makes sense to keep ().

[DanTup]

For now I'm going ahead with example 5 from above, but we can tweak if it doesn't feel right when people start using it.

One thing I changed slightly though is that we'll show the import-uri on the right side of the item is not already imported. The reason for this is that if you don't have the details panel visible, you'd often see duplicated items (where they're available from multiple libraries and none are imported) and it wouldn't be obvious why. With the old functionality it should show on the right side of the completion list only for the selected item, but in the new world we can't show things only for the selected item so they'll show all the time.

So with the panel collapsed it'll look something like this:

And with it visible like this:

Unfortunately we can't tell if the panel is open, so we can't hide the URIs from the right side of the completion list in that case, so there's a little duplication, but I feel like that's the best compromise.

I'm interested in feedback though (I'll post back after the change lands, it's not complete yet).

[DanTup]

This has landed in the latest SDK (it may take a few days to get to Flutter master). Since it ships in the SDK it'll show up in a future SDK release (not a VS Code extension release). If you have any feedback/issues about the changes, please open new issues with details - thanks!

[Number-3434]

Could there be an option to enable option 2?

I really like that you can see all the parameters there.

[DanTup]

@Number-3434 generally I think we should avoid too many options because it makes testing and maintaining more complicated, particularly where the combinations could multiply. Here we're already handling the original LSP format and this new format, so another option would double this to possible outcomes for each completion item. I think we should be sure there's sufficient demand to warrant the option (or just changing the default). I'd suggest filing an issue at https://github.com/dart-lang/sdk to collect comments and 👍 's.

That said, it's not quite the same - but in case you didn't have the extra panel expanded, the parameters are shown in the info on the right for the selected item:

And if you have signature help enabled (the default), it'll pop open if you select an item and show the parameters there too:

These might help if you already have a general idea of what you're looking for.

[Number-3434]

Okay, I'll leave it for now.

It just felt a bit weird that it shows abbreviated parameters, but doesn't currently show the full parameters anywhere.

[DanTup]

It just felt a bit weird that it shows abbreviated parameters, but doesn't currently show the full parameters anywhere.

Not sure I agree that it doesn't show them anywhere, they're shown in the places I noted above :)

Unfortunately VS Code changed how it shows the details slightly with this new work - it used to be that it showed the first line of the details on the right side of the selected item like this:

However when adopting this new UI, they removed that so that it only appears in the panel on the right (not inline when the item is selected). We're still putting the full signature into the details, but it'll only be visible in the panel on the right (whereas before it showed in two places).

[Number-3434]

Sorry, I meant specifically the inline text after the suggestion in the suggest widget.

It makes it much quicker to browse, as you can glance at the values, as opposed to having to go through every suggestion individually.

Also, personally, I really like that it shows them even if details are on.