Adds a callback to Future that is invoked upon completion, whether success or failure.

corelib/src/future.dart

Index: corelib/src/future.dart
===================================================================
--- corelib/src/future.dart	(revision 8248)
+++ corelib/src/future.dart	(working copy)
@@ -42,13 +42,20 @@
   bool get hasValue();
 
   /**
-   * When this future is complete and has a value, then [onComplete] is called
+   * When this future is complete (either with a value or with an exception),

[Jennifer Messerly, 2012/06/04 20:11:17]

It'd be good to comment on the order that onComplete, then, and handleException
are called

[sam.mccall, 2012/06/04 21:35:57]

Agreed, I'll add this to the class doc.

+   * then [complete] is called with the future.
+   * If [complete] throws an exception, it is ignored.
+   */
+  void onComplete(void complete(Future<T> future));

[Bob Nystrom, 2012/06/04 20:20:40]

How about "always"?

[sam.mccall, 2012/06/04 21:35:57]

My objection to 'always' is that it mostly makes sense as a contrast with
then/handleException (like try/finally).
Without the contrast, it sounds to me like some sort of repetition or looping
construct, e.g I don't find this obvious:

    file.readText().always((f) {
      print(f.hasValue ? f.value : "Error");
    });

[Jennifer Messerly, 2012/06/04 22:12:49]

yeah. FWIW, I liked the name onComplete

+
+  /**
+   * If this future is complete and has a value, then [onValue] is called
    * with the value.
    */
-  void then(void onComplete(T value));
+  void then(void onValue(T value));
 
   /**
-   * If this future gets an exception, then call [onException].
+   * If this future is complete and has an exception, then call [onException].
    *
    * If [onException] returns true, then the exception is considered handled.
    *
@@ -73,9 +80,6 @@
    *
    * If an exception occurs (received by this future, or thrown by
    * [transformation]) then the returned future will receive the exception.
-   *
-   * You must not add exception handlers to [this] future prior to calling
-   * transform, and any you add afterwards will not be invoked.
    */
   Future transform(transformation(T value));
 
@@ -90,9 +94,6 @@
     * If an exception occurs (received by this future, thrown by
     * [transformation], or received by the future returned by [transformation])
     * then the returned future will receive the exception.
-    *
-    * You must not add exception handlers to [this] future prior to calling
-    * chain, and any you add afterwards will not be invoked.
     */
    Future chain(Future transformation(T value));
 }