add generic method comments to a few SDK methods

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 represent a potential value, or error,
@@ skipping 236 matching lines @@
    * 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.
    *
    * The call to `cleanUp` should not throw. If it does, the error will be an
    * uncaught asynchronous error.
    */
-  static Future<List> wait(Iterable<Future> futures,
+  static Future<List/*<T>*/> wait/*<T>*/(Iterable<Future/*<T>*/> futures,
                            {bool eagerError: false,
-                            void cleanUp(successValue)}) {
+                            void cleanUp(/*=T*/ successValue)}) {

[Lasse Reichstein Nielsen, 2015/11/19 06:58:32]

The "=" is untraditional, but the rest is how we have commented things ourselves
before, so it is actually helpful (until we get generic methods). 

What does the =T mean? Is it just to distinguish it from normal /* someword */
comments? Could you derive that from the location and introduced type parameters
at that point?

[Jennifer Messerly, 2015/11/20 17:41:18]

Yeah, exactly, it's a lexical pattern to make it easier to search for these. The
/*<T>*/ is nice & easy to find, so the idea behind /*=T*/ was to create another
pattern.

Not sure if there's a better syntax we could use, or if we should try and parse
the freestanding /*T*/ instead. I'm open to ideas there.

     final _Future<List> result = new _Future<List>();
     List values;  // Collects the values. Set to null on error.
     int remaining = 0;  // How many futures are we waiting for.
     var error;   // The first error from a future.
     StackTrace stackTrace;  // The stackTrace that came with the error.
 
     // Handle an error from any of the futures.
     void handleError(theError, theStackTrace) {
       remaining--;
       if (values != null) {
@@ skipping 130 matching lines @@
    * the future returned by `then` will be completed with
    * the same result as the future returned by the callback.
    *
    * If [onError] is not given, and this future completes with an error,
    * the error is forwarded directly to the returned future.
    *
    * In most cases, it is more readable to use [catchError] separately, possibly
    * with a `test` parameter, instead of handling both value and error in a
    * single [then] call.
    */
-  Future then(onValue(T value), { Function onError });
+  Future/*<S>*/ then/*<S>*/(/*=S*/ onValue(T value), { Function onError });
 
   /**
    * Handles errors emitted by this [Future].
    *
    * This is the asynchronous equivalent of a "catch" block.
    *
    * Returns a new [Future] that will be completed with either the result of
    * this future or the result of calling the `onError` callback.
    *
    * If this future completes with a value,
@@ skipping 299 matching lines @@
   if (replacement != null) {
     error = _nonNullError(replacement.error);
     stackTrace = replacement.stackTrace;
   }
   result._completeError(error, stackTrace);
 }
 
 /** Helper function that converts `null` to a [NullThrownError]. */
 Object _nonNullError(Object error) =>
   (error != null) ? error : new NullThrownError();