Try to clarify optional parameter restrictions

[jamesderlin]

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
dart-lang/language#1076).

[kwalrath]

The writing LGTM, but I'll defer to Lasse as to correctness.

[lrhn]

This is basically all wrong for Null Safety. We can have required named parameters placed after optional named parameters.

How about:

A function can have any number of required positional parameters.
These may be followed either by optional positional parameters,
or by named parameters.
A named parameter can be either optional or required.

If this is describing pre-Null Safety behavior, then I'd say:

A function can have any number of required parameters.
These may be followed either by optional positional parameters,
or by optional named parameters.

[lrhn]

For null safety, we'll need to remove the "optional" before "named".

[kwalrath]

Thanks, Lasse.

[kwalrath]

We should have a standard string to mark where we know things have to change for null safety. Maybe just NULLSAFE. Something like this:

{% comment %}
NULLSAFE: Remove the "optional" before "named".
{% endcomment %}

[jamesderlin]

I've made adjustments to try to be friendlier for Null Safety when it becomes enabled by default. Notably I've removed the "Optional parameters" subheading since optional/required and positional/named will be independent axes. I've instead added a more general "Parameters" heading and merged part of the "Functions" section into it.

[kwalrath]

I'm wondering if we can simplify this a bit and also make some of the future changes now.

[kwalrath]

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

[kwalrath]

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).

[jamesderlin]

Done.

[kwalrath]

How about we add this now? Something like this.

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

[jamesderlin]

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