Make a Future returned by the action of Future.whenCompelete delay.

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 8a1b200dd82c14d31fdea5bd7d1a80e0219c6995..d91185e47afe6504bced91be3a7550789addf10a 100644
--- a/sdk/lib/async/future.dart
+++ b/sdk/lib/async/future.dart
@@ -102,13 +102,19 @@ abstract class Future<T> {
    *
    * This is the asynchronous equivalent of a "finally" block.
    *
-   * If the call to [action] does not throw, the returned future is completed
-   * with the same result as this future.
+   * The future returned by this call, [:f:], will complete the same way
+   * as this future unless an error occurs in the [action] call, or in
+   * a [Future] returned by the [action] call. If the [action] call returns
+   * [:null:] (or any non-future value), its return value is ignored.

[floitsch, 2013/01/09 17:10:13]

If the [action] does not return a future its return value is ignored.

[Lasse Reichstein Nielsen, 2013/01/10 07:02:33]

Done.

    *
-   * If the call to [action] throws, the returned future is completed with the
+   * If the call to [action] throws, then [:f:] is completed with the
    * thrown error.
+   *
+   * If the call to [action] returns a [Future], [:f2:], then completion  of

[floitsch, 2013/01/09 17:10:13]

nit: spurious space between "completion" and "of"

[Lasse Reichstein Nielsen, 2013/01/10 07:02:33]

Done.

+   * [:f:] is delayed until [:f2:] completes. If [:f2:] completes with a

[floitsch, 2013/01/09 17:10:13]

completes with an (remove "a").

[Lasse Reichstein Nielsen, 2013/01/10 07:02:33]

Done.

+   * an error, that will be the result of [:f:] too.
    */
-  Future<T> whenComplete(void action());
+  Future<T> whenComplete(Future action());

[floitsch, 2013/01/09 17:10:13]

Don't write the return value here. The editor will infer that you should return
something and bug people when they write functions.

[Lasse Reichstein Nielsen, 2013/01/10 07:02:33]

Ack. The old "returning null implicitly isn't good enough". :(

There is no good way to say "return Future or nothing".

 
   /**
    * Creates a [Stream] that sends [this]' completion value, data or error, to