Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Try to clarify optional parameter restrictions #2621

Merged
merged 3 commits into from
Sep 14, 2020
Merged

Try to clarify optional parameter restrictions #2621

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9e4cea8
Try to clarify optional parameter restrictions
jamesderlin Sep 3, 2020
c949eb3
Update with review feedback from lrhn
jamesderlin Sep 9, 2020
b760195
Update with review feedback from kwalrath
jamesderlin Sep 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions src/_guides/language/language-tour.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1127,20 +1127,24 @@ is sometimes referred to as _arrow_ syntax.
there, but you can use a [conditional expression](#conditional-expressions).
{{site.alert.end}}

A function can have two types of parameters: _required_ and _optional_.
The required parameters are listed first, followed by any optional parameters.
Optional parameters can be _named_ or _positional_.
### Parameters
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for adding this section head! I don't know why we didn't have it before.


A function can have any number of *required positional* parameters. These may be
followed either by *optional positional* parameters or by *optional named*
parameters. A function can have optional positional parameters or optional
named parameters, but not both.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this can be a little shorter (and also we avoid may). Also, we should switch the order to match the section names... and maybe it isn't necessary to say "optional" before named — especially since we don't use "Optional" in the section name?

Suggested change
A function can have any number of *required positional* parameters. These may be
followed either by *optional positional* parameters or by *optional named*
parameters. A function can have optional positional parameters or optional
named parameters, but not both.
A function can have any number of *required positional* parameters. These can be
followed either by *named* parameters or by *optional positional* parameters
(but not both).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

{% comment %}
NULLSAFE: Replace "optional named" above with just "named" and add:

A named parameter can be either optional or `required`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about we add this now? Something like this.

Named parameters are optional unless they're specifically marked as required.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good. I added that to the "Named parameters" section.

{% endcomment %}

{{site.alert.note}}
Some APIs — notably [Flutter][] widget constructors — use only named
parameters, even for parameters that are mandatory. See the next section for
details.
{{site.alert.end}}

### Optional parameters

Optional parameters can be either named or positional, but not both.

#### Named parameters

When calling a function, you can specify named parameters using
Expand Down Expand Up @@ -1179,7 +1183,11 @@ then the analyzer reports an issue.
To use the [@required][] annotation,
depend on the [meta][] package and import `package:meta/meta.dart`.

#### Positional parameters
{% comment %}
NULLSAFE: Rewrite this section.
{% endcomment %}

#### Optional positional parameters

Wrapping a set of function parameters in `[]` marks them as optional
positional parameters:
Expand Down