Added informal generic method syntax and generic function type specs.

docs/language/informal/generic-method-syntax.md

+# Feature: Generic Method Syntax
+
+**This document** is an informal specification of the support for generic
+methods and functions which has been implemented in `dart2js` with option
+`--generic-method-syntax`, starting with commit
+[acc5f59](https://github.com/dart-lang/sdk/commit/acc5f59a99d5d8747459c935e6360ac325606cc6).
+In SDK 1.21 this feature is available by default (i.e., also without the
+option) in the virtual machine and the analyzer, as well as in `dart2js`.
+
+The **motivation for** having this **feature** is that it enables partial
+support for generic methods and functions, thus providing a bridge between
+not having generic methods and having full support for generic methods. In
+particular, code declaring and using generic methods may be type checked and
+compiled in strong mode, and the same code will now be acceptable in
+standard (non-strong) mode as well. The semantics is different in certain
+cases, but standard mode analysis will emit diagnostic messages (e.g.,
+errors) for that.
+
+In this document, the word **routine** will be used when referring to
+something which can be a method, a top level function, a local function, or
+a function literal expression.
+
+With **this feature** it is possible to compile code where generic methods
+and functions are declared, implemented, and invoked. The runtime semantics
+does not include reification of type arguments. Evaluations of the runtime
+value of a routine type parameter is a runtime error or yields `dynamic`,
+depending on the context. No type checking takes place at usages of a method
+or function type parameter in the body, and no type checking regarding
+explicitly specified or omitted type arguments takes place at call sites.
+
+In short, generic methods and functions are supported syntactically, and the
+runtime semantics prevents dynamic usages of the type argument values, but
+it allows all usages where that dynamic value is not required. For instance,
+a generic routine type parameter, `T`, cannot be used in an expression like
+`x is T`, but it can be used as a type annotation. In a context where other
+tools may perform type checking, this allows for a similar level of
+expressive power as do language designs where type arguments are erased at
+compile time.
+
+The **motivation for** this **document** is that it serves as an informal
+specification for the implementation of support for the generic method
+syntax feature in all Dart tools.
+
+## Syntax
+
+The syntactic elements which are added or modified in order to support this
+feature are as follows, based on grammar rules given in the Dart Language
+Specification (Aug 19, 2015).
+
+```
+formalParameterPart:
+  typeParameters? formalParameterList
+functionSignature:
+  metadata returnType? identifier formalParameterPart
+typeParameter:
+  metadata identifier (('extends'|'super') type)?

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

Remove `super`. We are not planning on adding it right now. If this is being
treated as an *informal specification*, it should only specify the actual
features that implementations must implement.

[eernst, 2017/05/19 18:49:36]

Done.

+functionExpression:
+  formalParameterPart functionBody
+fieldFormalParameter:
+  metadata finalConstVarOrType? 'this' '.' identifier
+  formalParameterPart?
+argumentPart:
+  typeArguments? arguments
+selector:
+  assignableSelector | argumentPart
+assignableExpression:
+  primary (argumentPart* assignableSelector)+ |
+  'super' unconditionalAssignableSelector |
+  identifier
+cascadeSection:
+  '..' (cascadeSelector argumentPart*)
+  (assignableSelector argumentPart*)*
+  (assignmentOperator expressionWithoutCascade)?
+```
+
+In a [draft specification](https://codereview.chromium.org/1177073002) of
+generic methods from June 2015, the number of grammar changes is
+significantly higher, but that form can be obtained via renaming.
+
+This extension to the grammar gives rise to an **ambiguity** where the same
+tokens may be angle brackets of a type argument list as well as relational
+operators. For instance, `foo(a<b,c>(d))`[^1] may be parsed as a
+`postfixExpression` on the form `primary arguments` where the arguments are
+two relational expressions (`a<b` and `c>(d)`),  and it may also be parsed
+such that there is a single argument which is an invocation of a generic
+function (`a<b,c>(d)`).  The ambiguity is resolved in **favor** of the
+**generic function invocation** whenever the `primary` is followed by a
+balanced pair of angle brackets where the next token after the final `>` is
+a left parenthesis (in short, we are "looking at `< .. >(`").

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

Drop the "whenever". *The ambiguity* is always resolved in favor of the generic
function invocation. If there is no ambiguity, there is nothing to resolve.

[eernst, 2017/05/19 18:49:35]

That was not the approach that I specified, I took a different route because of
the performance implications. It was my impression that we agreed on that
approach. I'm now learning that the implementations haven't done that, but first
I'll explain why that approach was taken.

The point is that it may be expensive if the parser needs to perform speculative
parsing into a lookahead whose length has no finite constant bound (there's no
limit on the slowdown if we're in danger of speculatively parsing a lookahead of
arbitrary length "for nearly every token").

Presumably, expressions (including subexpressions) are common, so if we need to
check for `primary<typeList>(` all the time, it might be costly. We're doing
top-down parsing and hence, for the standard example `foo(a<b,c>(d))` with a
focus on the `argumentList`, we need to make a choice at step 3:

  argumentList -->
  expressionList -->
  expression --> ...

versus:

  argumentList -->
  expressionList -->
  expression ',' expression --> ...

in a derivation with many steps to reach "a<b, c>(d)" as two relational
expressions respectively as one function invocation. I just created a derivation
and it takes 44 resp. 47 steps, where each step derives as many non-terminals in
parallel as possible, e.g., going `shiftExpression '<' shiftExpression ',' ..`
to `additiveExpression '<' additiveExpression ',' ..`).

So, basically, we must traverse a more than 40 level deep call tree whenever we
have an expressionList in order to disprove that it matches `primary
typeParameters '('`, in order to see how long the expressionList is. Is that
really no problem?

Nevertheless, the tools may be doing just that whenever needed, which would of
course serve as an argument that it _is_ really no problem!

In that case we will just decide that the ambiguity is resolved in favor of a
generic function invocation, rather than saying that the tools can use a
well-defined O(1) shortcut to commit to a generic function invocation, even in
some cases where it would have parsed as two relational expressions but fails as
a generic function invocation (e.g., `foo(a<b,2>(d))`, where we will then get a
spurious syntax error).

However, I'm not 100% convinced that it will be trivial to detect what the
parsers are actually doing. Maybe they are using some other shortcut which may
give a different set of spurious failures? Can we live with that?

So I'd like to clarify this issue rather than just declaring that there is no
performance problem, and tools must simply decide the ambiguous cases perfectly,
and then favor the call in the ambiguous case and otherwise parse the construct
which is unambiguously there.

[Lasse Reichstein Nielsen, 2017/06/01 07:56:59]

I understand the lure of the O(1) shortcut (given that tokenization has found
the matching ">" already), but it's not something I want to enshrine into the
language specification.

First of all because it's too stict. It disallows syntax that would otherwise be
valid by choosing a disambiguation strategy early, before it has even detected
an ambiguity. We will allow more valid programs by not enforcing that choice.

Second, this it might be easily implementable in the current parsers because of
some design choices they have made, but basing the language design on a
particular implementation strategy risks locking all future implementations to
the same strategy, even if a better one is found. (See JavaScript RegExp - it's
(near-)impossible to implement the correct semantics using a state-based RegExp
engine because it really is a description of a specific implementation
algorithm).

Third, even if the implementations already contains the infrastructure for this
optimization, the specification does not. In order to *specify* this behavior,
we need to actually define the data-structure that the parsers build during
tokenization, specify how it's updated and what it's state is at any point
during parsing, and how it's used in this particular rule. That's new complexity
in the specification, and if the implementations have chosen slightly different
data structures (say, what happens for particular sequences of unmatched
braces), then we might end up enforcing one implementation's choices on another
implementation.

Finally, it's unnecessary. Since implementations have managed without this
bail-out, it doesn't seem necessary. They can still use the available look-ahead
to detect the cases where there can't possibly be an ambiguity. For the (likely
few) remaining cases, they will have to do some sort of look-ahead, but checking
for types first seems like the safest bet - type expressions are simpler than
general expressions, so it's likely to be rejected early if it isn't actually
type expressions, and if succeeds matching as type expressions up to the ">("
then it will be a valid generic invocation - if it is valid at all.

+
+This implies that an expression like `foo(a<b,2>(d))` will be rejected

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

What does "rejeceted" mean?
In any case, remove entire section. This will parse as two comparisons, and it
currently does in both the VM, dart2js and the analyzer.

[eernst, 2017/05/19 18:49:35]

It is a syntax error.
As mentioned, I'm surprised that this is the case, and I'm not 100% convinced
that they can do that in a way which is correct and still has acceptable
performance.

[Lasse Reichstein Nielsen, 2017/06/01 07:57:00]

I think it is possible - because the preferred interpretation is also the one
with the simplest grammar. Trying to parse the content between "<" and ">(" as
type expressions is unlikely to spend a lot of time before failing, so if we use
the proposed look-ahead as a hint instead of a rule, I think performance will
still be fine. Parsing isn't the most expensive part of reading in a program
anyway, I think I've heard an estimate of it being ten times faster than
tokenization.

+because it is parsed such that `foo` gets one argument which must be a
+generic function invocation, but `2` cannot parse correctly as a
+`type`. This is a breaking change, because the same expression used to parse
+correctly as an invocation of `foo` with two arguments.
+
+The **reason** why the generic function invocation is favored over the
+relational expressions is that it is considered to be a rare exception that
+this ambiguity arises: It requires a balanced set of angle brackets followed
+by a left parenthesis, which is already an unusual form. On top of that, the
+style guide recommendation to use named parameters for boolean arguments
+helps making this situation even less common.
+
+If it does occur then there is an easy **workaround**: an extra set of
+parentheses (as in `foo(a<b,(2>(d)))`) will resolve the ambiguity in the
+direction of relational expressions; or we might simply be able to remove
+the parentheses around the last expression (as in `foo(a<b,2>d)`), which
+will also eliminate the ambiguity.
+
+It should be noted that parsing techniques like recursive descent seem to
+conflict with this approach to disambiguation: Determining whether the
+remaining input starts with a balanced expression on the form `<` .. `>`
+seems to imply a need for an unbounded lookahead. However, if some type of
+"diet" parsing is used and various kinds of bracket tokens are matched up
+during the lexical analysis then it takes only a simple O(1) check in the
+parser to perform the required check.

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

Drop this section, or rewrite it to suggest, as an optimization, to check at
foo< whether it's followed by a matching '>' and a '(', otherwise it cannot be a
call and disambiguation thus can be done early.

[eernst, 2017/05/19 18:49:35]

This should be commentary; changed the font to italic. It is of course just a
suggestion for a possible optimization (even though that optimization may be
crucial in practice).

+
+## Scope of the Mechanism
+
+With the syntax in place, it is obvious that certain potential extensions
+have **not** been **included**.
+
+For instance, constructors, setters, getters, and operators cannot be
+declared as generic. Actual type arguments cannot be passed at invocation
+sites for setters, getters, and operators, and for constructors there is a
+need to find a way to distinguish between type arguments for the new
+instance and type arguments for the constructor itself. It is possible that

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

The second sentence seems to assume that constructors, setters, getters and
operators could be generic, otherwise it's not interesting to say that you can't
pass the type parameters.
I'm not sure what it's trying to say - is it a reason for not having generic
constructors, etc. or is it a problem that would have to be solved if we did
have them? And why are we saying that, if we don't have them anyway?
Probably just drop the sentence.

[eernst, 2017/05/19 18:49:36]

The second sentence is intended to explain why constructors, setters, getters,
and operators cannot be generic. Changed the '.' to ':' such that it is evident
that sentence 2 gives the reason for the rule given in sentence 1.
Yes, it's a motivation for why we don't have them. You could say that we could
still have them even though "they can't be called with type arguments", because
they type arguments might be inferred. However, I think that it is a reasonably
trade-off to say that we don't want to support generic getters etc. _because_
there is no way to call them with explicit type arguments. On top of that comes
that it may be useless (I don't know any good use cases for generic getters),
but there might still be some use cases that we haven't noticed yet.
It's clearly '\rationale{}` stuff, and we are explaining why we don't support
certain things because we don't support them and someone might wonder why (which
is a quite typical role for a `\rationale{}`, I think).

Still want to delete it?

[Lasse Reichstein Nielsen, 2017/06/01 07:56:59]

The primary reason we will not have generic getters and setters is that it
breaks the getter/setter-field symmetry. I can't see any possible way to make a
generic field.

+some of these restrictions will be lifted in a full-fledged version of this
+extension.

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

Not really, no. 
Setters and getters will not be generic, and operators most likely not either.
Constructors could be, but then say that it's possible that the restriction on
constructors can be lifted at a later point.

Don't say that this isn't a fully-fledged feature. We don't want people
speculating that it might change, because most likely it won't. If we add more,
it's a different feature.

[eernst, 2017/05/19 18:49:35]

This is exactly like the spec when it says that the restrictions on mixins may
be lifted. There is no promise that it'll be right now, nor even that it will
ever happen.

But we're pretty close to a decision where named constructors can be made
generic, so it's not an outrageous thought that we can add some of these things.

Changed 'full-fledged' to 'future' in order to avoid the direct implication that
the omitted features "ought to" be there.

+
+Conversely, the inclusion of lower bounds for type parameters (using the
+keyword `super`) serves to demonstrate that lower bounds fit well into the
+syntax. There is no guarantee that a final version of generic methods will
+support lower bounds, and it is not required that an implementation must
+support them.

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

Drop mentions of lower bounds.

[eernst, 2017/05/19 18:49:36]

Done.

+
+In general, the support for generic methods offered by this feature is not
+intended to be complete, it is **intended** to allow **for** **experiments**
+such that a final version of the generic method support can be designed
+well, **and** it is intended to allow for the **subset of usages** where
+reification is not required.

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

This disagrees with the paragraph above saying that this is an informal
specification for implementors.
We are going for the final version now, the one that is actually being
implemented. It may change due to feedback, but it's not "just for experiments".
So, remove paragraph.

[eernst, 2017/05/19 18:49:36]

Done.

I inserted a shorted paragraph explaining that actual type arguments are not
reified, since that's still true for this mechanism, and mentioned that a future
extension (which is actually upcoming) may add reification.

+
+## Resolution and Type Checking
+
+In order to be useful, the support for generic methods and functions must be
+sufficiently complete and consistent to **avoid spurious** diagnostic
+**messages**. In particular, even though no regular type checks take place
+at usages of routine type parameters in the body where they are in scope,
+those type parameters should be resolved. If they had been ignored then any
+usage of a routine type parameter `X` would give rise to a `Cannot resolve
+type X` error message, or the usage might resolve to other declarations of
+`X` in enclosing scopes such as a class type parameter, both of which is
+unacceptable.
+
+In `dart2js` resolution, the desired behavior has been achieved by adding a
+new type parameter **scope** and putting the type parameters into that
+scope, giving each of them the bound `dynamic`. The type parameter scope is
+the current scope during resolution of the routine signature and the type
+parameter bounds, it encloses the formal parameter scope of the routine, and
+the formal parameter scope in turn encloses the body scope.
+
+This implies that every usage of a routine type parameter is treated during
+**type checking** as if it had been an alias for the type `dynamic`.
+
+Static checks for **invocations** of methods or functions where type
+arguments are passed are omitted entirely: The type arguments are parsed,
+but no checks are applied to certify that the given routine accepts type
+arguments, and no checks are applied for bound violations. Similarly, no
+checks are performed for invocations where no type arguments are passed,
+whether or not the given routine is statically known to accept type
+arguments.
+
+Certain usages of a routine type parameter `X` give rise to **errors**: It
+is a compile-time error if `X` is used as a type literal (e.g., `foo(X)`),
+or in an expression on the form `e is X` or `e is! X`.
+
+It could be argued that it should be a warning or an error if a routine type
+parameter `X` is used in an expression on the form `e as X`. The blind
+success of this test at runtime may introduce bugs into correct programs in
+situations where the type constraint is violated; in particular, this could
+cause "wrong" objects to propagate through local variables and parameters
+and even into data structures (say, when a `List<T>` is actually a
+`List<dynamic>`, because `T` is not present at runtime when the list is
+created). However, considering that these type constraint violations are
+expected to be rare, and considering that it is common to require that
+programs compile without warnings, we have chosen to omit this warning. A
+tool is still free to emit a hint, or in some other way indicate that there
+is an issue.
+
+## Dynamic semantics
+
+If a routine invocation specifies actual type arguments, e.g., `int` in the
+**invocation** `f<int>(42)`, those type arguments will not be evaluated at
+runtime, and they will not be passed to the routine in the
+invocation. Similarly, no type arguments are ever passed to a generic
+routine due to call-site inference. This corresponds to the fact that the
+type arguments have no runtime representation.
+
+When the body of a generic **routine** is **executed**, usages of the formal
+type parameters will either result in a run-time error, or they will yield
+the value yielded by an evaluation of `dynamic`, following the treatment of

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

if `dynamic` can be shadowed, this it's correct to talk about "an evaluation of
`dynamic`".
Also "evaluation" generally applies to expressions, not to types.
Maybe just "they will yield the dynamic type".

[eernst, 2017/05/19 18:49:35]

Incorrect?
https://github.com/dart-lang/sdk/issues/29125 and
https://github.com/dart-lang/dart-lang-evolution/issues/141 have not reached a
conclusion, so I'll try to avoid the issue and use "the type dynamic" as you
suggest (the spec uses that phrase lots of times).

(My stance at this point is that `dynamic` currently _must_ be exported from
'dart:core': being a built-in identifier it must be subject to lookups, because
otherwise it makes no sense to say that we _cannot_ declare types with that
name, because if we also cannot declare non-types then the name is actually a
reserved word; so we need to look it up somewhere, and that can't be anywhere
else than in 'dart:core'. Oh, well, whatever. ;-)
Right, I was specifically thinking about the dynamic semantics here, and in
particular routine type variables `X` used as an expression. But I can see that
it matches less perfectly with `e is X` etc. Adjusted accordingly.

[Lasse Reichstein Nielsen, 2017/06/01 07:56:59]

Yes "incorrect". Read what I mean :)

I agree that we should do something, and it's either "reserved word", "exported
by dart:core", "implicitly in the scope of every library" (which is almost the
same as "exported by dart:core" except that you can't hide it - but it's also
completely new and needs its own specification).

+malformed types in Dart. There are the following cases:
+
+When `X` is a routine type parameter, the evaluation of `e is X`, `e is! X`,
+and `X` used as a type literal proceeds as if `X` had been a malformed type,

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

a type literal -> an expression
I'm not sure exactly what a "type literal" is (the spec doesn't define it), so I
prefer to only use it for an identifier that resolves to a type declaration
(class, typedef), not a type variable.

[eernst, 2017/05/19 18:49:36]

Done.

+producing a dynamic error if the type test itself is reached; the evaluation
+of `e as X` has the same outcome as the evaluation of `e`.
+
+Note that the forms containing `is` are compile-time errors, which means
+that implementations are free to reject the program, or to compile the
+program with a different runtime semantics for these expressions. The

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

If it's specified as a compile-time error, then compilers are not free to just
implement a different runtime behavior.
I'm all for a "--run-with-errors" flag that transforms broken programs into
running ones, but it must be explicit and opt-in that you are not getting the
correct semantics.

So, no, this is incorrect as written.

[eernst, 2017/05/19 18:49:35]

If we insist that the language specification must _not_ specify a semantics for
any programs with faults (so there are no warnings, only errors, and, of course,
no specification of a semantics for programs with errors), and we insist that
compilers are _not_ allowed to implement a run-time behavior for programs with
errors, then we have actually decided that there is no conforming way for a tool
chain to support execution of any less-than-statically-perfect programs.

We hardly want that, and I certainly don't. I think we must leave one door open,
and I think it makes sense to say that the open door is the following: Compilers
_are_ allowed to compile some programs with errors (according to the analyzer,
which will declare exactly the things to be errors that the spec says). And the
spec isn't supposed to specify the semantics of faulty programs, so it can't say
more than "compilers are allowed to generate code for some faulty programs".

I don't think we have discussed `--run-with-errors` before, but it makes sense
to have that. But that would still be a tool thing, not a spec thing. In
particular, one compiler might take such an option, another one might emit
'error hints' whenever it encounters an error for which it is able to generate
some code, etc. I don't think it's a big issue to agree on something in that
area.

But do we really disagree about the fundamental choice that compilers can make
the choice to compile some faulty programs?

In the light of all this, I've adjusted the paragraph. ;)

[Lasse Reichstein Nielsen, 2017/06/01 07:56:59]

I'm not saying that compilers can't choose to implement an extension to the Dart
language that allows constructs that are not valid Dart. They can do anything,
including rejecting valid Dart programs, they're just not *Dart* compilers then
(otherwise "perl" is a really crappy Dart compiler for a very extended
very-subset of Dart :)

I'm saying that the Dart language specification shouldn't mention it because
it's, by definition, outside the scope of the Dart language. I cannot help
reading the original text as a tacit endorsement of such a specific language
extension, and that's not the job of the language specification. It should just
say that it's a compile-time error, and then its job is done. 

It's like the traffic ordinance saying that "You are not allowed to cross at a
pedestrian crossing when the light is red. Pedstrians are obviously free to do
so anyway." 
Sure they are, they're just breaking the law, but that's not impossible, just
illegal.
A Dart compiler can extend the language, it's just not a Dart compiler any more,
and if you develop your program using it, it might end up not being a Dart
program.

+rationale for `dart2js` to allow the construct and compile it to a run time
+error is that (1) this allows more programs using generic methods to be
+compiled, and (2) an `is` expression that blindly returns `true` every time
+(or `false` every time) may silently introduce a bug into an otherwise
+correct program, so the expression must fail if it is ever evaluated.
+
+When `X` is a routine type parameter which is passed as a type argument to a
+generic class instantiation `G` which is itself used in `e is G`, `e is! G`,

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

Isn't this just saying that in a generic class instantiation, a malformed type
is treated as dynamic? After that, the resulting type is unrelated to the
original type parameter.
It confuses me (a little) that the special cases are mentioned because G means
the same type in every setting, and that type doesn't depend on the type
*variable* X, only on the type it refers to.

It's like talking about a parameter and then mentioning the argument
*expression* used to pass the value - it should be irrelevant.

[eernst, 2017/05/19 18:49:35]

Right, this can be compressed. Did that.

+`e as G`, and `G` used as a type literal, evaluation again proceeds as if
+`X` were a malformed type, which in this case means that it is treated like
+`dynamic`.
+
+This may be surprising, so let us consider a couple of examples: When `X` is
+a routine type parameter, `42 is X` raises a dynamic error, `<int>[42] is
+List<X>` yields the value `true`, and `42 as X` yields `42`, no matter
+whether the syntax for the invocation of the routine included an actual type
+argument, and, if so, no matter which value the actual type argument would
+have had at the invocation.
+
+Object construction is similar: When `X` is a routine type parameter which
+is a passed as a type argument to a constructor invocation, the value passed
+to the constructor will be the value yielded by an evaluation of `dynamic`.

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

Drop "the value yielded by an evaluation of `dynamic`", just "the dynamic type".
If that's not the same, something is very, very wrong, and the latter is much
clearer.

[eernst, 2017/05/19 18:49:36]

Adjusted the sentence in approximately that manner.

+
+In **checked mode**, when `X` is a routine type parameter which is used as a
+type annotation or in a generic type `G` used as a type annotation, no
+checked mode checks will ever fail for initialization or assignment to a
+local variable or parameter whose type annotation is `X`, and if the type
+annotation is a generic type `G` that contains `X`, checked mode checks will
+succeed or fail as if `X` had been the type `dynamic`.

[Lasse Reichstein Nielsen, 2017/04/26 09:15:31]

This is different from a malformed type, which would throw if used as a type
annotation. Maybe say that.

[eernst, 2017/05/19 18:49:36]

Removed the phrase `which .. annotation`, in line 235-236: That was redundant.
Added a remark about malformed types.

+
+## Changes
+
+2017-Jan-04: Changed 'static error' to 'compile-time error', which is the
+phrase that the language specification uses.
+
+## Notes
+
+[^1]: These expressions violate the common style in Dart with respect to
+spacing and capitalization. That is because the ambiguity implies
+conflicting requirements, and we do not want to bias the appearance in
+one of the two directions.