add generic method comments to a few SDK methods

add generic method comments to a few SDK methods

R=lrn@google.com

Committed: https://github.com/dart-lang/sdk/commit/49c24b83dac970766eb959e880a12328cff4ea0f

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

lrn@google.com changed reviewers:
+ lrn@google.com

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

lgtm

https://codereview.chromium.org/1462743002/diff/1/sdk/lib/async/future.dart
File sdk/lib/async/future.dart (right):

https://codereview.chromium.org/1462743002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:259: void cleanUp(/*=T*/ successValue)}) {
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?

https://codereview.chromium.org/1462743002/diff/1/sdk/lib/math/math.dart
File sdk/lib/math/math.dart (right):

https://codereview.chromium.org/1462743002/diff/1/sdk/lib/math/math.dart#newc...
sdk/lib/math/math.dart:66: num/*=T*/ max/*<T extends num>*/(num/*=T*/ a,
num/*=T*/ b) {
Is this a way to say that max of two doubles is a double, and max of two
integers is an integer, while max of an int and a double is only known to be a
num?

If so, should you do the same to num.+ (etc)? Or is that already special cased
by the spec?

[Lasse Reichstein Nielsen, 2015-11-19 08:30:52]

@mit FYI

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

Thanks for taking a look at this!

https://codereview.chromium.org/1462743002/diff/1/sdk/lib/async/future.dart
File sdk/lib/async/future.dart (right):

https://codereview.chromium.org/1462743002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:259: void cleanUp(/*=T*/ successValue)}) {
On 2015/11/19 06:58:32, Lasse Reichstein Nielsen wrote:
> 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?

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.

https://codereview.chromium.org/1462743002/diff/1/sdk/lib/math/math.dart
File sdk/lib/math/math.dart (right):

https://codereview.chromium.org/1462743002/diff/1/sdk/lib/math/math.dart#newc...
sdk/lib/math/math.dart:66: num/*=T*/ max/*<T extends num>*/(num/*=T*/ a,
num/*=T*/ b) {
On 2015/11/19 06:58:32, Lasse Reichstein Nielsen wrote:
> Is this a way to say that max of two doubles is a double, and max of two
> integers is an integer, while max of an int and a double is only known to be a
> num?

Exactly.

> If so, should you do the same to num.+ (etc)? Or is that already special cased
> by the spec?

Yup, they're covered by "16.27 Additive Expressions" page 96 of the 3rd edition:
http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-408.pdf :

> [...]. The
> static type of an expression e1 +e2 where e1 has static type int is int if the
static
> type of e2 is int, and double if the static type of e2 is double. The static
type of
> an expression e1 − e2 where e1 has static type int is int if the static type
of e2
> is int, and double if the static type of e2 is double.

[Jennifer Messerly, 2015-11-24 17:20:53]

Committed patchset #2 (id:20001) manually as
49c24b83dac970766eb959e880a12328cff4ea0f (presubmit successful).

[Leaf, 2016-01-13 00:52:12]

leafp@google.com changed reviewers:
+ leafp@google.com

[Leaf, 2016-01-13 00:52:12]

https://codereview.chromium.org/1462743002/diff/20001/sdk/lib/async/stream.dart
File sdk/lib/async/stream.dart (right):

https://codereview.chromium.org/1462743002/diff/20001/sdk/lib/async/stream.da...
sdk/lib/async/stream.dart:482: Stream/*<S>*/ expand(Iterable/*<S>*/ convert(T
value)) {
I think this is missing the binding site.  Should be `expand/*<S>*/(` ?