add a note about completer to future

corelib/src/future.dart

 // Copyright (c) 2011, 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.
 
 // Dart core library.
 
 
 /**
  * A [Future] is used to obtain a value sometime in the future.  Receivers of a
  * [Future] can obtain the value by passing a callback to [then].
@@ skipping 10 matching lines @@
  *
  * When a future completes:
  *
  *   1. if the future suceeded, handlers registered with [then] are called.
  *   2. if the future failed, handlers registered with [handleException] are
  *      called in sequence, until one returns true.
  *   3. handlers registered with [onComplete] are called
  *   4. if the future failed, and at least one handler was registered with
  *      [then], and no handler registered with [handleException] returned
  *      [:true:], then the exception is thrown.
+ *
+ * Use a [Completer] to create and change the state of a [Future].
  */
 interface Future<T> default FutureImpl<T> {
 
   /** A future whose value is immediately available. */
   Future.immediate(T value);
 
   /** The value provided. Throws an exception if [hasValue] is false. */
   T get value();
 
   /**
@@ skipping 162 matching lines @@
         }
       });
       future.handleException((exception) {
         if (!result.isComplete) completer.completeException(exception);
         return true;
       });
     }
     return result;
   }
 }