Change and documentat how completer handles futures.

tests/lib/async/future_test.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.
 
 library future_test;
 
 import 'package:async_helper/async_helper.dart';
 import "package:expect/expect.dart";
 import 'dart:async';
 
@@ skipping 549 matching lines @@
 
   asyncStart();
   future.catchError((e) {
     Expect.identical(error, e);
     asyncEnd();
   });
 
   completer.completeError(error);
 }
 
+void testCompleteWithFutureSuccess() {
+  asyncStart();
+  final completer = new Completer<int>();
+  final completer2 = new Completer<int>();
+  completer.complete(completer2.future);
+  completer.future.then((v) {
+    Expect.equals(42, v);
+    asyncEnd();
+  });
+  completer2.complete(42);
+}
+
+void testCompleteWithFutureSuccess2() {
+  asyncStart();
+  final completer = new Completer<int>();
+  Future result = new Future.value(42);
+  completer.complete(result);
+  completer.future.then((v) {
+    Expect.equals(42, v);
+    asyncEnd();
+  });
+}
+
+void testCompleteWithFutureError() {
+  asyncStart();
+  final completer = new Completer<int>();
+  final completer2 = new Completer<int>();
+  completer.complete(completer2.future);
+  completer.future.then((v) {
+    Expect.fail("Should not happen");
+    asyncEnd();
+  }, onError: (e) {
+    Expect.equals("ERROR-tcwfe", e);
+    asyncEnd();
+  });
+  completer2.completeError("ERROR-tcwfe");
+}
+
+void testCompleteWithFutureError2() {
+  asyncStart();
+  final completer = new Completer<int>();
+  Future result = new Future.error("ERROR-tcwfe2");
+  completer.complete(result);
+  completer.future.then((v) {
+    Expect.fail("Should not happen");
+    asyncEnd();
+  }, onError: (e) {
+    Expect.equals("ERROR-tcwfe2", e);
+    asyncEnd();
+  });
+}
+
+void testCompleteErrorWithFuture() {
+  final completer = new Completer<int>();
+  Expect.throws(() => completer.completeError(new Future.value(42)));
+}
+
+void testCompleteWithCustomFutureSuccess() {
+  asyncStart();
+  final completer = new Completer<int>();
+  final completer2 = new Completer<int>();
+  completer.complete(new CustomFuture(completer2.future));
+  completer.future.then((v) {
+    Expect.equals(42, v);
+    asyncEnd();
+  });
+  completer2.complete(42);
+}
+
+void testCompleteWithCustomFutureError() {
+  asyncStart();
+  final completer = new Completer<int>();
+  final completer2 = new Completer<int>();
+  completer.complete(new CustomFuture(completer2.future));
+  completer.future.then((v) {
+    Expect.fail("Should not happen");
+    asyncEnd();
+  }, onError: (e) {
+    Expect.equals("ERROR-tcwcfe", e);
+    asyncEnd();
+  });
+  completer2.completeError("ERROR-tcwcfe");
+}
+
+void testCompleteErrorWithCustomFuture() {
+  final completer = new Completer<int>();
+  var future = new CustomFuture(new Future.value(42));
+  Expect.throws(() => completer.completeError(future));
+}
+
+void testCompleteErrorWithNull() {
+  final completer = new Completer<int>();
+  Expect.throws(() => completer.completeError(null));
+}
+
 void testChainedFutureValue() {
   final completer = new Completer();
   final future = completer.future;
   asyncStart();
 
   future.then((v) => new Future.value(v * 2))
         .then((v) {
           Expect.equals(42, v);
           asyncEnd();
         });
@@ skipping 54 matching lines @@
   testValue();
   testSync();
   testNeverComplete();
 
   testComplete();
   testCompleteWithSuccessHandlerBeforeComplete();
   testCompleteWithSuccessHandlerAfterComplete();
   testCompleteManySuccessHandlers();
   testCompleteWithError();
 
+  testCompleteWithFutureSuccess();
+  testCompleteWithFutureSuccess2();
+  testCompleteWithFutureError();
+  testCompleteWithFutureError2();
+  testCompleteErrorWithFuture();
+  testCompleteWithCustomFutureSuccess();
+  testCompleteWithCustomFutureError();
+  testCompleteErrorWithCustomFuture();
+  testCompleteErrorWithNull();
+
   testException();
   testExceptionHandler();
   testExceptionHandlerReturnsTrue();
   testExceptionHandlerReturnsTrue2();
   testExceptionHandlerReturnsFalse();
 
   testFutureAsStreamCompleteAfter();
   testFutureAsStreamCompleteBefore();
   testFutureAsStreamCompleteImmediate();
   testFutureAsStreamCompleteErrorAfter();
@@ skipping 13 matching lines @@
   testFutureCatchThrowsAsync();
   testFutureWhenThrowsAsync();
   testFutureCatchRethrowsAsync();
 
   testChainedFutureValue();
   testChainedFutureValueDelay();
   testChainedFutureError();
 
   testSyncFuture_i13368();
 }
+
+/// A Future that isn't recognizable as a _Future.
+class CustomFuture<T> implements Future<T> {
+  Future _realFuture;
+  CustomFuture(this._realFuture);
+  Future then(action(result), {Function onError}) =>
+      _realFuture.then(action, onError: onError);
+  Future catchError(Function onError, {bool test(e)}) =>
+      _realFuture.catchError(onError, test: test);
+  Future whenComplete(action()) => _realFuture.whenComplete(action);
+  Stream asStream() => _realFuture.asStream();
+  String toString() => "CustomFuture@${_realFuture.hashCode}";
+  int get hashCode => _realFuture.hashCode;
+}