From 9e4cea80b45cbf2d911a1ca96d5df77827e81f5d Mon Sep 17 00:00:00 2001 From: James Lin Date: Thu, 3 Sep 2020 14:35:01 -0700 Subject: [PATCH 1/3] Try to clarify optional parameter restrictions The Language Tour currently states: > Optional parameters can be either named or positional, but not > both. That statement can be interpreted to mean that any individual parameter cannot be both named and positional. However, the actual restriction is stronger: a function cannot have both optional named and optional positional parameters (see https://github.com/dart-lang/language/issues/1076). --- src/_guides/language/language-tour.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/_guides/language/language-tour.md b/src/_guides/language/language-tour.md index 74470024b7..4eaa351a18 100644 --- a/src/_guides/language/language-tour.md +++ b/src/_guides/language/language-tour.md @@ -1129,7 +1129,7 @@ is sometimes referred to as _arrow_ syntax. 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_. +Optional parameters can be either _named_ or _positional_. {{site.alert.note}} Some APIs — notably [Flutter][] widget constructors — use only named @@ -1139,7 +1139,8 @@ Optional parameters can be _named_ or _positional_. ### Optional parameters -Optional parameters can be either named or positional, but not both. +A function can have optional positional parameters or optional named parameters, +but not both. #### Named parameters From c949eb3ac80642967039fd17f6ac05bd29d55450 Mon Sep 17 00:00:00 2001 From: James Lin Date: Tue, 8 Sep 2020 19:20:01 -0700 Subject: [PATCH 2/3] Update with review feedback from lrhn Adjust wording to require fewer changes when Null Safety becomes enabled by default. --- src/_guides/language/language-tour.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/src/_guides/language/language-tour.md b/src/_guides/language/language-tour.md index 4eaa351a18..cec436631d 100644 --- a/src/_guides/language/language-tour.md +++ b/src/_guides/language/language-tour.md @@ -1127,9 +1127,17 @@ 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 either _named_ or _positional_. +### Parameters + +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. +{% comment %} +NULLSAFE: Replace "optional named" above with just "named" and add: + +A named parameter can be either optional or `required`. +{% endcomment %} {{site.alert.note}} Some APIs — notably [Flutter][] widget constructors — use only named @@ -1137,11 +1145,6 @@ Optional parameters can be either _named_ or _positional_. details. {{site.alert.end}} -### Optional parameters - -A function can have optional positional parameters or optional named parameters, -but not both. - #### Named parameters When calling a function, you can specify named parameters using @@ -1180,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: From b760195ce4c13254d611980b4fcaeb77246af690 Mon Sep 17 00:00:00 2001 From: James Lin Date: Mon, 14 Sep 2020 14:47:05 -0700 Subject: [PATCH 3/3] Update with review feedback from kwalrath --- src/_guides/language/language-tour.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/src/_guides/language/language-tour.md b/src/_guides/language/language-tour.md index cec436631d..c4cff86c22 100644 --- a/src/_guides/language/language-tour.md +++ b/src/_guides/language/language-tour.md @@ -1129,15 +1129,9 @@ is sometimes referred to as _arrow_ syntax. ### Parameters -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. -{% comment %} -NULLSAFE: Replace "optional named" above with just "named" and add: - -A named parameter can be either optional or `required`. -{% endcomment %} +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). {{site.alert.note}} Some APIs — notably [Flutter][] widget constructors — use only named @@ -1147,6 +1141,8 @@ A named parameter can be either optional or `required`. #### Named parameters +Named parameters are optional unless they're specifically marked as required. + When calling a function, you can specify named parameters using paramName: value. For example: