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..211d667f995f07cf4e58ca8c98f61d762ac07221 100644
--- a/lib/math/base.dart
+++ b/lib/math/base.dart
@@ -20,12 +20,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;
 
@@ -57,8 +57,8 @@ external int parseInt(String str);
 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
+  * Returns the lesser of two numbers. Returns NaN if either argument is NaN.

[ahe, 2012/08/23 10:44:36]

General comment. If you start a new paragraph after the first sentence, then a
documentation tool can create a better summary of this library. For example:

min: Returns the lesser of two numbers.
max: Returns the larger of two numbers.

Finding the first sentence is really hard, but finding the first paragraph is
easy.

This also known as Chuck Norris style ;-)

[Lasse Reichstein Nielsen, 2012/08/24 14:40:31]

Done.

+  * The minimum of [:-0.0:] and [:0.0:] is [:-0.0:]. If the arguments are
   * equal (int and doubles with the same mathematical value are equal) then
   * it is unspecified which of the two arguments is returned.
   */
@@ -92,8 +92,8 @@ 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
+  * Returns the larger of two numbers. Returns NaN if either argument is NaN.
+  * The maximum of [:-0.0:] and [:0.0:] is [:0.0:]. If the arguments are

[ahe, 2012/08/23 10:11:56]

maximum -> larger.

[Lasse Reichstein Nielsen, 2012/08/24 14:40:31]

Done.

   * equal (int and doubles with the same mathematical value are equal) then
   * it is unspecified which of the two arguments is returned.
   */
@@ -129,23 +129,79 @@ num max(num a, num b) {
 }
 
 /**
- * Returns the arc tangent of [a]/[b] with sign according to quadrant.
+ * Returns the angle between the positive x-axis and the vector ([b],[a]).

[ahe, 2012/08/23 10:44:36]

See if you can simplify the first sentence. For example:

"A variant of arc tangent."

The Dictionary on the Mac defines "arctan" as an abbreviation of "arc tangent",
so you can use the abbreviation if you like.

[Lasse Reichstein Nielsen, 2012/08/24 14:40:31]

Done.

+ * The result, in radians, is in the range -PI..PI. If [a] is positive, this

[ahe, 2012/08/23 10:44:36]

How about one paragraph per case?

[Lasse Reichstein Nielsen, 2012/08/24 14:40:31]

Done.

+ * is equivalent to [:atan(a/b):]. If [a] is negative, the result 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);
 
 /**
+ * Returns [x] to the power of [exponent].

[ahe, 2012/08/23 10:44:36]

Add newline.

[Lasse Reichstein Nielsen, 2012/08/24 14:40:31]

Done.

  * If the [exponent] is an integer the result is of the same type as [x].

[ahe, 2012/08/23 10:44:36]

integer -> is of type int (and positive).

2.0 is an integer, but not an int.

[Lasse Reichstein Nielsen, 2012/08/24 14:40:31]

Changed specification to return int if [x] is int and [exponent] is non-negative
int, double otherwise.
This is not the current behavior, but the current behavior is silly: x int and
exponent negative int means that the result is always truncated to zero.

  * Otherwise it is a [double].

[ahe, 2012/08/23 10:44:36]

Perhaps add a note that int doesn't overflow, but double might.

[Lasse Reichstein Nielsen, 2012/08/24 14:40:31]

Done.

  */
 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 of the value.
+ * The tangent function is equivalent to [:sin(x)/cos(x):] and may be
+ * infinite (positive or negative) when [:cos(x):] is 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.

[ahe, 2012/08/23 10:44:36]

Check this.

[Lasse Reichstein Nielsen, 2012/08/24 14:40:31]

Done.

+ */
 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.

[ahe, 2012/08/23 10:44:36]

Check this.

[Lasse Reichstein Nielsen, 2012/08/24 14:40:31]

Done.

+ */
 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..PI, or [:NaN:] if [x] is [:NaN:].

[ahe, 2012/08/23 10:44:36]

Check this.

[Lasse Reichstein Nielsen, 2012/08/24 14:40:31]

Changed to -PI/2..PI/2.

+ */
 external double atan(num x);
+
+/**
+ * Converts [x] to a double and returns the square root of the value.
+ * Returns [:NaN:] if x is negative or [:NaN:].

[ahe, 2012/08/23 10:44:36]

What about -0.0?

[Lasse Reichstein Nielsen, 2012/08/24 14:40:31]

That returns -0.0, by IEEE-754 decree. Now documented.

+ */
 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.
+ * The result is [:NaN:] if [x] is [:NaN:], zero or negative.
+ */
 external double log(num x);