add generic method comments to a few SDK methods

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 30016f7acc8eabf180d49f0ba49f0f103a000be8..bcc20192b1471ae59e7604f04965b760dcdbbea6 100644
--- a/sdk/lib/async/future.dart
+++ b/sdk/lib/async/future.dart
@@ -254,9 +254,9 @@ abstract class Future<T> {
    * 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.
@@ -407,7 +407,7 @@ abstract class Future<T> {
    * 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].