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..ed0f1b74abaf315dd3c335efc1831531eab1e2e7 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 delay reporting of errors until listeners are
+   * added. If the first `then` or `catchError` call happens after this future
+   * has completed with an error then the error is reported as unhandled error.
+   * 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 delay reporting of errors until listeners are
+   * added. If the first `catchError` (or `then`) call happens after this future
+   * has completed with an error then the error is reported as unhandled error.
+   * See the description on [Future].
+   *
    * Example:
    *
    *     foo