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

sdk/lib/async/future.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.async;
 
 /// A type representing values that are either `Future<T>` or `T`.
 ///
 /// This class declaration is a public stand-in for an internal
 /// future-or-value generic type. References to this class are resolved to the
@@ skipping 482 matching lines @@
    * If the callback returns a [Future],
    * the future returned by `then` will be completed with
    * the same result as the future returned by the callback.
    *
    * If [onError] is not given, and this future completes with an error,
    * the error is forwarded directly to the returned future.
    *
    * 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});
 
   /**
    * Handles errors emitted by this [Future].
    *
    * This is the asynchronous equivalent of a "catch" block.
    *
    * Returns a new [Future] that will be completed with either the result of
    * this future or the result of calling the `onError` callback.
@@ skipping 10 matching lines @@
    *
    * If `test` returns `true`,
    * [onError] is called with the error and possibly stack trace,
    * and the returned future is completed with the result of this call
    * in exactly the same way as for [then]'s `onError`.
    *
    * If `test` is omitted, it defaults to a function that always returns true.
    * 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
    *       .catchError(..., test: (e) => e is ArgumentError)
    *       .catchError(..., test: (e) => e is NoSuchMethodError)
    *       .then((v) { ... });
    *
    * This method is equivalent to:
    *
    *     Future catchError(onError(error),
@@ skipping 276 matching lines @@
   AsyncError replacement = Zone.current.errorCallback(error, stackTrace);
   if (replacement != null) {
     error = _nonNullError(replacement.error);
     stackTrace = replacement.stackTrace;
   }
   result._completeError(error, stackTrace);
 }
 
 /** Helper function that converts `null` to a [NullThrownError]. */
 Object _nonNullError(Object error) => error ?? new NullThrownError();