More tests and doc for futures (followup to http://codereview.chromium.org/10517006/)

corelib/src/future.dart

 // Copyright (c) 2011, 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.
 
 // Dart core library.
 
 
 /**
  * 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 may complete by *succeeding* (producing a value) or *failing*
  * (producing an exception, which may be handled with [handleException]).
  * Callbacks passed to [onComplete] will be invoked in either case.
  *
- * When a future completes:
+ * 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 [handleException] are
  *      called in sequence, until one returns true.
  *   3. handlers registered with [onComplete] are called
  *   4. if the future failed, and at least one handler was registered with
  *      [then], and no handler registered with [handleException] returned
  *      [:true:], then the exception is thrown.
  *
  * Use a [Completer] to create and change the state of a [Future].
@@ skipping 29 matching lines @@
    * When this future is complete (either with a value or with an exception),
    * then [complete] is called with the future.
    * If [complete] throws an exception, it is ignored.
    */
   void onComplete(void complete(Future<T> future));
 
   /**
    * If this future is complete and has a value, then [onValue] is called
    * with the value.
    */
-  void then(void onValue(T value));
+  void then(void onSuccess(T value));
 
   /**
    * If this future is complete and has an exception, then call [onException].
    *
    * If [onException] returns true, then the exception is considered handled.
    *
    * If [onException] does not return true (or [handleException] was never
    * called), then the exception is not considered handled. In that case, if
    * there were any calls to [then], then the exception will be thrown when the
    * value is set.
@@ skipping 122 matching lines @@
         }
       });
       future.handleException((exception) {
         if (!result.isComplete) completer.completeException(exception);
         return true;
       });
     }
     return result;
   }
 }