Specify FutureOr.

docs/language/dartLangSpec.tex

Index: docs/language/dartLangSpec.tex
diff --git a/docs/language/dartLangSpec.tex b/docs/language/dartLangSpec.tex
index 158a10f177ce7bf2b8baa9cd3241ba394372cecb..252e070957479024c9b743ebeff8caecfd4bb18b 100644
--- a/docs/language/dartLangSpec.tex
+++ b/docs/language/dartLangSpec.tex
@@ -27,6 +27,7 @@
 % - An await-for loop only pauses the subscription if it does something async.
 % - Assert statements may now also include a "message" operand.
 % - The Null type is now considered a subtype of all types in most cases.
+% - Specified the FutureOf type.

[eernst, 2017/02/01 16:54:30]

`FutureOr`. Also, it seems to be the standard style to use double quotes around
literal source code, which makes it `"FutureOr"`.

 %
 % 1.14
 % - The call "C()" where "C" is a class name, is a now compile-time error.
@@ -7226,11 +7227,11 @@ Static type annotations are used in variable declarations (\ref{variables}) (inc
     .
 
 {\bf typeArguments:}
-      '<' typeList '>'
+      `<' typeList `>'
     .
 
 {\bf typeList:}
-      type (',' type)*
+      type (`,' type)*
     .
  \end{grammar}
 
@@ -7651,6 +7652,28 @@ What of static checking? Surely we would want to flag (2) when users have explic
 \LMHash{}
 The name \DYNAMIC{} denotes a \cd{Type} object even though \DYNAMIC{} is not a class.
 
+\LMHash{}
+The built-in type declaration \code{FutureOr},
+which is declared in the library \code{dart:async},
+defines a generic type with one type parameter (\ref{generics}).
+If the \code{FutureOr} type, optionally followed by type arguments,
+is used as a type, it denotes the \DYNAMIC{} type.
+As such, the \code{FutureOr} type cannot be used where \DYNAMIC{} cannot be
+used as a type.
+If the type arguments applied to \code{FutureOr} would issue static warnings
+if applied to a normal generic class with one type parameter,
+the same warnings are issued for \code{FutureOr},
+even though the type arguments are otherwise ignored.
+The name \code{FutureOr} denotes the same \cd{Type} object as \DYNAMIC{}.

[eernst, 2017/02/01 16:54:30]

This raises the question: So what's the semantics of applying `\code{FutureOr}`
to a list of type arguments? I'd say that we always do this (either the
arguments are provide explicitly, or the compiler adds them), and the type
arguments are ignored (it's like the constant type level function (x) =>
dynamic). With that, `\code{FutureOr<T>}` evaluated as an expression denotes the
same type object as `\DYNAMIC{}` for all `T`.

Or do we want to make it a semantic primitive that a generic class can be
evaluated to a type "when needed", without passing any arguments? I think that
would be more confusing and more complex to handle.

[Lasse Reichstein Nielsen, 2017/02/02 06:45:47]

I'm not sure what this is suggesting.
You can't evaluate `FutureOr<T>` as an expression, type literals don't take type
parameters at all.

+
+\rationale{
+The \code{FutureOr} type is reserved for future use,
+for cases where a value can be either an instance of the type \metavar{type}
+or the type \code{Future<\metavar{type}>}. Such cases occur naturally
+in asynchronous code.
+Using \code{FutureOr} instead of \DYNAMIC{} will allow some tools
+to provide a more precise type analysis.
+}
 %\rationale {
 %Type objects reify the runtime types of instances. No instance ever has type \DYNAMIC{}.
 %}