add generic method comments to a few SDK methods

sdk/lib/math/math.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.
 
 /**
  * Mathematical constants and functions, plus a random number generator.
  */
 library dart.math;
 
 part "jenkins_smi_hash.dart";
@@ skipping 45 matching lines @@
 
 /**
   * Returns the lesser of two numbers.
   *
   * Returns NaN if either argument is NaN.
   * The lesser of [:-0.0:] and [:0.0:] is [:-0.0:].
   * If the arguments are otherwise equal (including int and doubles with the
   * same mathematical value) then it is unspecified which of the two arguments
   * is returned.
   */
-num min(num a, num b) {
+num/*=T*/ max/*<T extends num>*/(num/*=T*/ a, num/*=T*/ b) {

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

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?

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

Exactly.
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 :

   // These partially redundant type checks improve code quality for dart2js.
   // Most of the improvement is at call sites from the inferred non-null num
   // return type.
   if (a is! num) throw new ArgumentError(a);
   if (b is! num) throw new ArgumentError(b);
 
   if (a > b) return b;
   if (a < b) return a;
   if (b is double) {
     // Special case for NaN and -0.0. If one argument is NaN return NaN.
@@ skipping 14 matching lines @@
 }
 
 /**
   * Returns the larger of two numbers.
   *
   * Returns NaN if either argument is NaN.
   * The larger of [:-0.0:] and [:0.0:] is [:0.0:]. If the arguments are
   * otherwise equal (including int and doubles with the same mathematical value)
   * then it is unspecified which of the two arguments is returned.
   */
-num max(num a, num b) {
+num/*=T*/ max/*<T extends num>*/(num/*=T*/ a, num/*=T*/ b) {
   // These partially redundant type checks improve code quality for dart2js.
   // Most of the improvement is at call sites from the inferred non-null num
   // return type.
   if (a is! num) throw new ArgumentError(a);
   if (b is! num) throw new ArgumentError(b);
 
   if (a > b) return a;
   if (a < b) return b;
   if (b is double) {
     // Special case for NaN and -0.0. If one argument is NaN return NaN.
@@ skipping 136 matching lines @@
  */
 external double exp(num x);
 
 /**
  * Converts [x] to a double and returns the natural logarithm of the value.
  * 
  * Returns negative infinity if [x] is equal to zero.
  * Returns NaN if [x] is NaN or less than zero.
  */
 external double log(num x);