Change and documentat how completer handles futures.

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;
 
 /**
  * An object representing a delayed computation.
  *
  * A [Future] is used to obtain a not yet
@@ skipping 469 matching lines @@
    *     });
    */
   factory Completer.sync() => new _SyncCompleter<T>();
 
   /** The future that will contain the result provided to this completer. */
   Future get future;
 
   /**
    * Completes [future] with the supplied values.
    *
+   * If the value is itself a future, the completer will wait for that future
+   * to complete, and complete with the same result, whether it is a success
+   * or an error.
+   *
+   * Calling `complete` or [completeError] must not be done more than once.
+   *
    * All listeners on the future are informed about the value.
    */
-  void complete([T value]);
+  void complete([value]);
 
   /**
    * Complete [future] with an error.
    *
+   * Calling [complete] or `completeError` must not be done more than once.
+   *
    * Completing a future with an error indicates that an exception was thrown
    * while trying to produce a value.
    *
-   * The argument [error] must not be `null`.
+   * The argument [error] must not be `null`, and it must not be a future.

[floitsch, 2013/10/29 18:13:35]

Why this restriction?

I'm ok with it being a future. We are just not going to wait for it.

[Lasse Reichstein Nielsen, 2013/10/30 09:22:17]

If the result of a future cannot be a future, I assumed that the error result
couldn't either. In that case, we don't have a value to use here.
Since you say that we won't wait for it, I assume you mean that the future will
be the error value. 
I'm not sure I like the difference, *but* we do allow futures elsewhere if we
throw them, e.g.,  
  new Future(() { throw new Future.value(42); }).catchError((Future f) =>
f).then(print);  // Prints 42

I'll change it back to allowing futures, and document it as such.
Why not null, btw?

[floitsch, 2013/10/30 18:50:53]

Error handlers are frequently piped (like for example in streams: listen(...,
onDone: completer.complete(), onError: completer.completeError).
It would be annoying if they needed to look out for futures.
That said: it is clearly a really bad idea to make a future an error (especially
if the future completes with an error)

I'm not sure why we disallow null. I would be ok with allowing it as well.

    */
   void completeError(Object error, [StackTrace stackTrace]);
 
   /**
    * Whether the future has been completed.
    */
   bool get isCompleted;
 }