anchor.diff:  part of dart.async;
   
   /**
  - * A [Future] is used to obtain a value sometime in the future.  Receivers of a
  - * [Future] can obtain the value by passing a callback to [then]. For example:
  - *
  - *     Future<int> future = getFutureFromSomewhere();
  - *     future.then((value) {
  - *       print("I received the number $value");
  + * A [Future] represents a delayed computation. It is used to obtain a not-yet
  + * available value, or error, sometime in the future.  Receivers of a
  + * [Future] can register callbacks that handle the value or error once it is
  + * available. For example:
  + *
  + *     Future<int> future = getFuture();
  + *     future.then((value) => handleValue(value))
  + *           .catchError((error) => handleError(error));
  + *
  + * A [Future] can be completed in two ways: with a value ("the future succeeds")
  + * or with an error ("the future fails"). Users can install callbacks for each
  + * case. The result of registering a pair of callbacks is a new Future (the
  + * "successor") which in turn is completed with the result of invoking the
  + * corresponding callback. The successor is completed with an error if the
  + * invoked callback throws. For example:
  + *
  + *     Future<int> successor = future.then((int value) {
  + *         // Invoked when the future is completed with a value.
  + *         return 42;  // The successor is completed with the value 42.
  + *       },
  + *       onError: (AsyncError e) {
  + *         // Invoked when the future is completed with an error.
  + *         if (canHandle(e)) {
  + *           return 499;  // The successor is completed with the value 499.
  + *         } else {
  + *           throw e;  // The successor is completed with the error e.
  + *         }
  + *       });
  + *
  + * If a future does not have a successor but is completed with an error, it
  + * forwards the error message to the global error-handler. This special casing
  + * makes sure that no error is silently dropped. However, it also means that
  + * error handlers should be installed early, so that they are present as soon
  + * as a future is completed with an error. The following example demonstrates
  + * this potential bug:
  + *
  + *     var future = getFuture();
  + *     new Timer(5, (_) {
  + *       // The error-handler is only attached 5ms after the future has been
  + *       // received. If the future fails in the mean-time it will forward the
  + *       // error to the global error-handler, even though there is code (just
  + *       // below) to handle the error.
  + *       future.then((value) { useValue(value); },
  + *                   onError: (e) { handleError(e); });
    *     });
    *
  - * A future may complete by *succeeding* (producing a value) or *failing*
  - * (producing an error, which may be handled with [catchError]).
  - *
  - * When a future completes, the following actions happen in order:
  - *
  - *   1. if the future suceeded, handlers registered with [then] are called.
  - *   2. if the future failed, handlers registered with [catchError] are
  - *      tested in sequence. Each test returning true is, have its handler
  - *      called.
  - *   4. if the future failed, and no handler registered with [catchError] it
  - *      is accepting the error, an error is sent to the global error handler.
  - *
  - * [Future]s are usually not created directly, but with [Completer]s.
  + * In general we discourage registering the two callbacks at the same time, but
  + * prefer to use [then] with one argument (the value handler), and to use
  + * [catchError] for handling errors. The missing callbacks (the error-handler
  + * for [then], and the value-handler for [catchError]), are automatically
  + * configured to "forward" the value/error. Separating value and error-handling
  + * into separate registration calls usually leads to code that is easier to
  + * reason about. In fact it makes asynchronous code very similar to synchronous
  + * code:
  + *
  + *     // Synchronous code.
  + *     try {
  + *       int value = foo();
  + *       return bar(value);
  + *     } catch (e) {
  + *       return 499;
  + *     }
  + *
  + *  Equivalent asynchronous code, based on futures:
  + *
  + *     Future<int> future = foo();  // foo now returns a future.
  + *     future.then((int value) => bar(value))
  + *           .catchError((e) => 499);
  + *
  + * Similar to the synchronous code, the error handler (registered with
  + * [catchError]) is handling the errors for exceptions coming from calls to
  + * 'foo', as well as 'bar'. This would not be the case if the error-handler was
  + * registered at the same time as the value-handler.
  + *
  + * Futures can have more than one callback-pairs registered. Each successor is
  + * treated independently and is handled as if it was the only successor.
    */
  +// TODO(floitsch): document chaining.
   abstract class Future<T> {
  -  /** A future whose value is immediately available. */
  +  /**
  +   * A future whose value is available in the next event-loop iteration.
  +   *
  +   * See [Completer]s, for futures with values that are computed asynchronously.
  +   */
     factory Future.immediate(T value) => new _FutureImpl<T>.immediate(value);
   
  -  /** A future that completes with an error. */
  +  /**
  +   * A future that completes with an error in the next event-loop iteration.
  +   *
  +   * See [Completer]s, for futures with values that are computed asynchronously.
  +   */
     factory Future.immediateError(var error, [Object stackTrace]) {
       return new _FutureImpl<T>.immediateError(error, stackTrace);
     }
  
positive.code:   /**
     * Handles errors emitted by this [Future].
     *
     * When this future completes with an error, first [test] is called with the
     * error's value.
     *
     * If [test] returns [true], [onError] is called with the error
     * wrapped in an [AsyncError]. The result of [onError] is handled exactly as
     * [then]'s [onValue].
     *
     * If [test] returns false, the exception is not handled by [onError], but is
     * emitted by the returned Future unmodified.
     *
     * If [test] is omitted, it defaults to a function that always returns true.
     *
     * Example:
     * foo
     *   .catchError(..., test: (e) => e is ArgumentError)
     *   .catchError(..., test: (e) => e is NoSuchMethodError)
     *   .then((v) { ... });
     */
    Future catchError(onError(AsyncError asyncError),
                      {bool test(Object error)});
  
negative.code:    * Creates a future that completes after a delay.
     *
     * The future will be completed after [milliseconds] have passed with
     * the result of calling [value]. If [milliseconds] is 0, it completes at the
     * earliest in the next event-loop iteration.
     *
     * If calling [value] throws, the created future will complete with the
     * error.
     *
     * See [Completer]s, for futures with values that are computed asynchronously.
     */
    factory Future.delayed(int milliseconds, T value()) {
      _FutureImpl<T> future = new _ThenFuture<dynamic, T>((_) => value());
  