Add more documentation to `Future.then` and `Future.catchError`.

sdk/lib/async/future.dart

Index: sdk/lib/async/future.dart
diff --git a/sdk/lib/async/future.dart b/sdk/lib/async/future.dart
index 2decb7242a462e7f3a17d3d050749168c3b2e55f..c421e32834f8834a9ef750c03e9ab8bd7cbe9f3c 100644
--- a/sdk/lib/async/future.dart
+++ b/sdk/lib/async/future.dart
@@ -500,6 +500,11 @@ abstract class Future<T> {
    * In most cases, it is more readable to use [catchError] separately, possibly
    * with a `test` parameter, instead of handling both value and error in a
    * single [then] call.
+   *
+   * Note that futures don't wait for listeners to handle errors. If the

[Lasse Reichstein Nielsen, 2017/03/22 18:36:48]

First sentence is a little unclear to me.
How about:

Note that a futures won't delay reporting of errors until a listener is added.

[floitsch, 2017/03/22 19:09:58]

Done.

+   * `then` call happens after this future has completed with an error then

[Lasse Reichstein Nielsen, 2017/03/22 18:36:48]

If the *first* `then` call happens ...

(and drop the "unless there was another listener").

Ditto below.

[floitsch, 2017/03/22 19:09:58]

Done.

+   * the error is reported as unhandled error (unless there was another
+   * listener). See the description on [Future].
    */
   Future<S> then<S>(FutureOr<S> onValue(T value), {Function onError});
 
@@ -530,6 +535,11 @@ abstract class Future<T> {
    * The `test` function should not throw, but if it does, it is handled as
    * if the `onError` function had thrown.
    *
+   * Note that futures don't wait for listeners to handle errors. If the
+   * `catchError` call happens after this future has completed with an error
+   * then the error is reported as unhandled error (unless there was another
+   * listener). See the description on [Future].
+   *
    * Example:
    *
    *     foo