Improve documentation for `Future.wait`.

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 5240bf8d5d707207210f6f980946e7e6b3459d93..20032d8c8a5309ff3fc9624e34f786ab9fb51b70 100644
--- a/sdk/lib/async/future.dart
+++ b/sdk/lib/async/future.dart
@@ -290,19 +290,24 @@ abstract class Future<T> {
    * 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.