Add documentation to the trigonometric functions in the math library.

lib/math/base.dart

Index: lib/math/base.dart
diff --git a/lib/math/base.dart b/lib/math/base.dart
index 926c17a5ef5a039a5ed7aec917fd40ebfcfe50eb..6911b487de01bcf34fbde21f397bc170bc3a3158 100644
--- a/lib/math/base.dart
+++ b/lib/math/base.dart
@@ -6,6 +6,8 @@
 
 /**
  * Base of the natural logarithms.
+ *
+ * Typically written as "e".
  */
 final double E = 2.718281828459045;
 
@@ -20,12 +22,12 @@ final double LN10 =  2.302585092994046;
 final double LN2 =  0.6931471805599453;
 
 /**
- * Base-2 logarithm of E.
+ * Base-2 logarithm of [E].
  */
 final double LOG2E = 1.4426950408889634;
 
 /**
- * Base-10 logarithm of E.
+ * Base-10 logarithm of [E].
  */
 final double LOG10E = 0.4342944819032518;
 
@@ -45,22 +47,27 @@ final double SQRT1_2 = 0.7071067811865476;
 final double SQRT2 = 1.4142135623730951;
 
 /**
- * Parses a [String] representation of an [int], and returns an [int]. Throws a
- * [FormatException] if [str] cannot be parsed as an [int].
+ * Parses a [String] representation of an [int], and returns an [int].
+ *
+ * Throws a [FormatException] if [str] cannot be parsed as an [int].
  */
 external int parseInt(String str);
 
 /**
  * Parses a [String] representation of a [double], and returns a [double].
+ *
  * Throws a [FormatException] if [str] cannot be parsed as a [double].
  */
 external double parseDouble(String str);
 
 /**
-  * Returns the minimum of two numbers. If either argument is NaN returns NaN.
-  * The minimum of [:-0.0:] and [:0.0:] is [:-0.0:]. If both arguments are
-  * equal (int and doubles with the same mathematical value are equal) then
-  * it is unspecified which of the two arguments is returned.
+  * 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) {
   if (a is num) {
@@ -92,10 +99,12 @@ num min(num a, num b) {
 }
 
 /**
-  * Returns the maximum of two numbers. If either argument is NaN returns NaN.
-  * The maximum of [:-0.0:] and [:0.0:] is [:0.0:]. If both arguments are
-  * equal (int and doubles with the same mathematical value are equal) then
-  * it is unspecified which of the two arguments is returned.
+  * 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) {
   if (a is num) {
@@ -129,23 +138,98 @@ num max(num a, num b) {
 }
 
 /**
- * Returns the arc tangent of [a]/[b] with sign according to quadrant.
+ * A variant of [atan].
+ *
+ * Converts both arguments to doubles.
+ *
+ * Returns the angle between the positive x-axis and the vector ([b],[a]).
+ * The result, in radians, is in the range -PI..PI.
+ *
+ * If [b] is positive, this is the same as [:atan(b/a):].
+ *
+ * The result is negative when [a] is negative (including when [a] is the
+ * double -0.0).
+ *
+ * If [a] is equal to zero, the vector ([b],[a]) is considered parallel to
+ * the x-axis, even if [b] is also equal to zero. The sign of [b] determines
+ * the direction of the vector along the x-axis.
+ *
+ * Returns NaN if either argument is NaN.
  */
 external double atan2(num a, num b);
 
 /**
- * If the [exponent] is an integer the result is of the same type as [x].
- * Otherwise it is a [double].
+ * 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].
+ *
+ * Notice that an [int] result cannot overflow, but a [double] result might
+ * be [double.INFINITY].
  */
 external num pow(num x, num exponent);
 
-// TODO(4512): Add documentation.
+/**
+ * Converts [x] to a double and returns the sine of the value.
+ *
+ * If [x] is not a finite number, the result is NaN.
+ */
 external double sin(num x);
+
+/**
+ * Converts [x] to a double and returns the cosine of the value.
+ *
+ * If [x] is not a finite number, the result is NaN.
+ */
 external double cos(num x);
+
+/**
+ * Converts [x] to a double and returns the tangent of the value.
+ *
+ * The tangent function is equivalent to [:sin(x)/cos(x):] and may be
+ * infinite (positive or negative) when [:cos(x):] is equal to zero.
+ * If [x] is not a finite number, the result is NaN.
+ */
 external double tan(num x);
+
+/**
+ * Converts [x] to a double and returns the arc cosine of the value.
+ *
+ * Returns a value in the range -PI..PI, or NaN if [x] is outside
+ * the range -1..1.
+ */
 external double acos(num x);
+
+/**
+ * Converts [x] to a double and returns the arc sine of the value.
+ * Returns a value in the range -PI..PI, or  NaN if [x] is outside
+ * the range -1..1.
+ */
 external double asin(num x);
+
+/**
+ * Converts [x] to a dobule and returns the arc tangent of the vlaue.
+ * Returns a value in the range -PI/2..PI/2, or NaN if [x] is NaN.
+ */
 external double atan(num x);
+
+/**
+ * Converts [x] to a double and returns the positive square root of the value.
+ *
+ * Returns -0.0 if [x] is -0.0, and NaN if [x] is otherwise negative or NaN.
+ */
 external double sqrt(num x);
+
+/**
+ * Converts [x] to a double and returns the natural exponent, [E],
+ * to the power [x].
+ * 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);