Change and documentat how completer handles futures.

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 335714be7f7b720a6d0b7b49b533e9c9dc010942..f33028be95b85ee7d7fc49e30d4febbb4dc1f6e8 100644
--- a/sdk/lib/async/future.dart
+++ b/sdk/lib/async/future.dart
@@ -487,17 +487,25 @@ abstract class Completer<T> {
   /**
    * 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]);