Improve documentation for `Future.wait`.

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 type representing values that are either `Future<T>` or `T`.
 ///
 /// This class declaration is a public stand-in for an internal
 /// future-or-value generic type. References to this class are resolved to the
@@ skipping 272 matching lines @@
         _completeWithErrorCallback(result, e, s);
       }
     });
     return result;
   }
 
   /**
    * Wait for all the given futures to complete and collect their values.
    *
    * Returns a future which will complete once all the futures in a list are
-   * complete. If any of the futures in the list completes with an error,
-   * the resulting future also completes with an error. Otherwise the value
-   * of the returned future will be a list of all the values that were
-   * produced.
+   * complete.

[Lasse Reichstein Nielsen, 2017/04/26 08:28:46]

Maybe: are complete -> have completed
(I think we generally uses "complete" as an action of a Future, not a state)

[floitsch, 2017/04/26 15:33:49]

Done.

+   *
+   * The value of the returned future will be a list of all the values that
+   * were produced.
+   *
+   * If any of given futures completes with an error, then the returned future
+   * completes with the first seen error instead.

[Lasse Reichstein Nielsen, 2017/04/26 08:28:46]

first seen error -> first error seen
(I think)

[floitsch, 2017/04/26 15:33:49]

Reworded with the help of Seth.

    *
    * If `eagerError` is true, the future completes with an error immediately on
    * the first error from one of the futures. Otherwise all futures must
    * complete before the returned future is completed (still with the first
    * error to occur, the remaining errors are silently dropped).
    *
-   * If [cleanUp] is provided, in the case of an error, any non-null result of
-   * a successful future is passed to `cleanUp`, which can then release any
-   * resources that the successful operation allocated.
+   * In the case of an error, [cleanUp] (if provided), is invoked on any
+   * non-null result of successful futures.
+   * This makes it posible to `cleanUp` resources that would otherwise be
+   * lost (since the returned future does not provide access to these values).
+   * The [cleanup] function is unused if there is no error.
    *
    * The call to `cleanUp` should not throw. If it does, the error will be an
    * uncaught asynchronous error.
    */
   static Future<List<T>> wait<T>(Iterable<Future<T>> futures,
       {bool eagerError: false, void cleanUp(T successValue)}) {
     final _Future<List<T>> result = new _Future<List<T>>();
     List<T> values; // Collects the values. Set to null on error.
     int remaining = 0; // How many futures are we waiting for.
     var error; // The first error from a future.
@@ skipping 525 matching lines @@
   AsyncError replacement = Zone.current.errorCallback(error, stackTrace);
   if (replacement != null) {
     error = _nonNullError(replacement.error);
     stackTrace = replacement.stackTrace;
   }
   result._completeError(error, stackTrace);
 }
 
 /** Helper function that converts `null` to a [NullThrownError]. */
 Object _nonNullError(Object error) => error ?? new NullThrownError();