Add documentation to dart:math pow function.

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 "random.dart";
@@ skipping 119 matching lines @@
  * the direction of the vector along the x-axis.
  *
  * Returns NaN if either argument is NaN.
  */
 external double atan2(num a, num b);
 
 /**
  * Returns [x] to the power of [exponent].
  *
  * If [x] is an [int] and [exponent] is a non-negative [int], the result is
- * an [int], otherwise the result it is a [double].
+ * an [int], otherwise both arguments are converted to doubles first, and the
+ * result is a [double].
+ *
+ * For integers, the power is always equal to the mathematical result of `x` to
+ * the power `exponent`, only limited by the available memory.
+ *
+ * For doubles, `pow(x, y)` handles edge cases as follows:
+ *
+ * - if `y` is zero (0.0 or -0.0), the result is always 1.0.
+ * - if `x` is 1.0, the result is always 1.0.
+ * - otherwise, if either `x` or `y` is NaN then the result is NaN.
+ * - if `x` is negative (but not -0.0) and `y` is a finite non-integer, the
+ *   result is NaN.
+ * - if `x` is Infinity and `y` is negative, the result is 0.0.
+ * - if `x` is Infinity and `y` is positive, the result is Infinity.
+ * - if `x` is 0.0 and `y` is negative, the result is Infinity.
+ * - if `x` is 0.0 and `y` is positive, the result is 0.0.
+ * - if `x` is -Infinity or -0.0 and `y` is an odd integer, then the result is
+ *   `-pow(-x ,y)`.
+ * - if `x` is -Infinity or -0.0 and `y` is not an odd integer, then the result
+ *   is the same as `pow(-x , y)`.
+ * - if `y` is Infinity and the absolute value of `x` is less than 1, the
+ *   result is 0.0.
+ * - if `y` is Infinity and `x` is -1, the result is 1.0.
+ * - if `y` is Infinity and the absolute value of `x` is greater than 1,
+ *   the result is Infinity.
+ * - if `y` is -Infinity, the result is `1/pow(x, Infinity)`.
+ *
+ * This corresponds to the `pow` function defined in the IEEE Standard 754-2008.
  *
  * Notice that an [int] result cannot overflow, but a [double] result might
  * be [double.INFINITY].
  */
 external num pow(num x, num exponent);
 
 /**
  * Converts [x] to a double and returns the sine of the value.
  *
  * If [x] is not a finite number, the result is NaN.
@@ skipping 50 matching lines @@
  * Returns NaN if [x] is NaN.
  */
 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);