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

sdk/lib/async/future.dart

 // Copyright (c) 2012, 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.
 
 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:
  *
@@ skipping 84 matching lines @@
                     {bool test(Object error)});
 
   /**
    * Register a function to be called when this future completes.
    *
    * The [action] function is called when this future completes, whether it
    * does so with a value or with an error.
    *
    * 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 call to [action]
+   * does not return a future, its return value is ignored.
    *
-   * 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
+   * [:f:] is delayed until [:f2:] completes. If [:f2:] completes with
+   * an error, that will be the result of [:f:] too.
    */
-  Future<T> whenComplete(void action());
+  Future<T> whenComplete(action());
 
   /**
    * Creates a [Stream] that sends [this]' completion value, data or error, to
    * its subscribers. The stream closes after the completion value.
    */
   Stream<T> asStream();
 }
 
 /**
  * A [Completer] is used to produce [Future]s and supply their value when it
@@ skipping 63 matching lines @@
    */
   static Future forEach(Iterable input, Future f(element)) {
     var iterator = input.iterator;
     Future nextElement(_) {
       if (!iterator.moveNext()) return new Future.immediate(null);
       return f(iterator.current).then(nextElement);
     }
     return nextElement(null);
   }
 }