Add documentation to dart:math pow function.

sdk/lib/math/math.dart

Index: sdk/lib/math/math.dart
diff --git a/sdk/lib/math/math.dart b/sdk/lib/math/math.dart
index 0c1f67fa0d00a86c6a811cd4db927aa595d6697a..a6ef72e46c31e3e1ee333d7a81beb8c7b9ba3782 100644
--- a/sdk/lib/math/math.dart
+++ b/sdk/lib/math/math.dart
@@ -137,7 +137,28 @@ 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` handles edge cases as follows:
+ *
+ * - `pow(x, ±0.0)` is 1, no matter what `x` is.
+ * - `pow(1, y)` is 1, no matter what `y` is.
+ * - `pow(−1, ±∞)` is always 1.
+ * - `pow(±0, y)` is infinite if y is negative. If the first argument

[floitsch, 2013/08/19 14:47:31]

there are two items +-0, y.
The next list-item seems more plausible too.

+ *   is negative zero and `y` is a negative integer, then the result is
+ *   negative infinity, otherwise it is positive infinity.
+ * - `pow(±0, y)` is zero if y is non-negative. If the first argument is
+ *   negative zero and y is an odd integer, then the results is -0.0, otherwise
+ *   is is 0.0.
+ * - `pow(±0, −∞)` is positive infinity.

[floitsch, 2013/08/19 14:47:31]

put the special cases first. Otherwise the generic "y" would already trigger.

+ * - `pow(±0, ∞)` is 0.0.
+ * - `pow(x, y)` is `NaN` if x is negative and y is a finite non-integer.
+ *
+ * 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].