Add documentation of expected behaviour for code completion of functions (re: parameter placeholders)

Is your feature request related to a problem? Please describe.

I believe the expected behaviour for parameter completion is a bit inconsistent (presumably for good reasons), and it might be helpful to have some documentation to refer to.

To describe what I am seeing, if I make a class with two functions that have optional parameters (one named the other positional) and a pair of classes with constructors in the same pattern:

For the function with optional positional parameters, the autocomplete gives one relevant option which adds placeholders for the parameters:

For the function with named positional parameters, the autocomplete gives one relevant option which does not add placeholders for the parameters:

In the case of constructor functions, two relevant options appear - with and without (...):

Selecting the (...) option gives, in the case of optional named parameters, no placeholders:

Whereas if I select the option without (...) I get just the class name:

And if I then open the bracket, ie. hit '(' I get prompts for the parameters and a super helpful popover:

The constructor function for optional positional parameters follows the same pattern:

Describe the solution you'd like

The main thing that gets me is that I forget what to expect, eg. I select the (...) option in a constructor expecting placeholders because of the ... but get no placeholders and can't use Cmd . to get them and then can't remember if that's expected behaviour and have to go looking (which is all OK imo, but I figured it would be helpful if there were a reasonably obvious docs page that describes what to expect).

Describe alternatives you've considered

Additional context

I'm updating the descriptions for completeFunctionCalls to include:

Whether to insert parentheses and parameter placeholders for positional and required arguments during code completions when using LSP

I think some of the terminology in the example above is slightly misleading which may have added to the confusion. The functions called "OptionalPositional" are not really optional, they are nullable. They are still required, but the value can be null. The completion will only insert arguments for values that are required regardless of nullability.

A clearer example would be this:

class Awesome {
  bool get isAwesome => true;

  // Required, but nullable
  void allRequiredPositional(String? a, String? b, String? c) {}
  // Optional, and nullable
  void allOptionalPositional([String? a, String? b, String? c]) {}
  // Optional, named
  void allOptionalNamed({String? a, String? b, String? c}) {}
  // Required, named
  void allRequiredNamed(
      {required String? a, required String? b, required String? c}) {}
}

foo() {
  var a = Awesome();
  a.allRequiredPositional(a, b, c);
  a.allOptionalPositional();
  a.allOptionalNamed();
  a.allRequiredNamed(a: a, b: b, c: c);
}

Here it's clearer that the placeholders are consistently included for arguments that are required (irrespective of whether they are nullable or not) because it is an error to not provide them. Arguments that are not required to be supplied and never inserted (since you may need to delete them if you don't want to pass them).

FWIW, when you're inside the parens for a function, you can use Cmd+Shift+Space (or equiv on non-Macs) that invoke the Trigger Parameter Hints command to show the signature of the current method:

Update docs for completeFunctionCalls

Sorry for mistake, I am aware that nullable positional parameters are required, I guess my brain got a bit scrambled with copy-pasting names. I apologise for the issue, it was pretty unclear, I'm surprised sometimes at how difficult it is to get what's in your head into something intelligible.

The answer assumes I didn't know nullable positional parameters are required (very reasonable given what I wrote) and addressed that as the problem but that's not the case. My attempt to describe what was unexpected was really unclear sorry but the main thing that is surprising to me is that selecting the (...) option gives me empty brackets when there are optional named parameters. I have several times stopped, with the vague memory that there is some way of adding the params but not sure how and had to go read the docs and it takes me a little while each time so I thought if there were some docs that made it really clear, maybe that would end up being a time saver for others.

For me personally I'm pretty sure it will always stick for me now to either

choose the ClassName without the (...) and open the bracket
or
hit Cmd+Shit+Space

Thanks for reading and responding to what was in hindsight a fairly unclear issue 🙂

the main thing that is surprising to me is that selecting the (...) option gives me empty brackets when there are optional named parameters

Ah, gotcha. The ... is intended to just show that there are some parameters, but not necessarily that they are required. It could be changed to just show () but I think that would be a little more misleading, making it seem like the function has no arguments at all.

We don't automatically include placeholders for optional parameters because a lot of the time they aren't required and would require deleting code. However, you should get completion for those arguments right after pressing (, and also if you close that and start typing an argument name:

Here, the completion pops up when I type (, then I hit escape to close it, and it shows up again when I hit a. Are you not seeing this?

Thanks Dan 🙂

I agree the (...) makes sense over () to indicate there are params and that automatically adding placeholders would be overall worse than not adding them.

I do see all the behaviour you describe.

Where I have been confused in the past is when I autocomplete the function before I get to the (. So, in your example - if I enter f then o then select the foo(...) option:

I would think "I know the plugin can give me the params..." but not remember how and have to go digging, so I wondered if it might be the same for others and if some documentation of the options and how they worked might help it stick in people's brains and end up saving some time.

I think some documentation in the form of a series of goals and how to achieve them might be helpful but it's not really clear to me what that would look like so I might have a go at making something in the form of a blog post or a video, then check in and see if you think there's anything that might be useful for the website.

Thanks for your help as always!

Ah, I see. I think the signature help is only triggering when you type the ( and not when completing. I've filed #3645 to see if we can make it appear here too.

Navigation Menu

Repository navigation

Add documentation of expected behaviour for code completion of functions (re: parameter placeholders) #3571

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add documentation of expected behaviour for code completion of functions (re: parameter placeholders) #3571

Description

Activity

DanTup commented on Oct 27, 2021

nickmeinhold commented on Oct 27, 2021

DanTup commented on Oct 28, 2021

nickmeinhold commented on Oct 29, 2021

DanTup commented on Nov 1, 2021

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions