Add documentation to the trigonometric functions in the math library.

Add documentation to the trigonometric functions in the math library.

BUG=4512
R=ahe@google.com

Committed: https://code.google.com/p/dart/source/detail?r=11315

[Lasse Reichstein Nielsen, 2012-08-23 10:06:15]

PTAL

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

I'm not sure I'm qualified to review this.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart
File lib/math/base.dart (right):

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:8: * Base of the natural logarithms.
How about adding something like: Also known as "e".

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:96: * The maximum of [:-0.0:] and [:0.0:] is [:0.0:]. If the
arguments are
maximum -> larger.

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

LGTM!

Thank you for sitting down with me and go through this. Now I look I'm clever
;-)

Cheers,
Peter

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart
File lib/math/base.dart (right):

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:60: * Returns the lesser of two numbers. Returns NaN if
either argument is NaN.
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 ;-)

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:132: * Returns the angle between the positive x-axis and the
vector ([b],[a]).
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.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:133: * The result, in radians, is in the range -PI..PI. If
[a] is positive, this
How about one paragraph per case?

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:144: * Returns [x] to the power of [exponent].
Add newline.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:145: * If the [exponent] is an integer the result is of the
same type as [x].
integer -> is of type int (and positive).

2.0 is an integer, but not an int.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:146: * Otherwise it is a [double].
Perhaps add a note that int doesn't overflow, but double might.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:173: * the range -1..1.
Check this.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:180: * the range -1..1.
Check this.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:186: * Returns a value in the range -PI..PI, or [:NaN:] if
[x] is [:NaN:].
Check this.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:192: * Returns [:NaN:] if x is negative or [:NaN:].
What about -0.0?

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

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart
File lib/math/base.dart (right):

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:8: * Base of the natural logarithms.
On 2012/08/23 10:11:56, ahe wrote:
> How about adding something like: Also known as "e".

Done.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:60: * Returns the lesser of two numbers. Returns NaN if
either argument is NaN.
On 2012/08/23 10:44:36, ahe wrote:
> 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 ;-)

Done.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:96: * The maximum of [:-0.0:] and [:0.0:] is [:0.0:]. If the
arguments are
On 2012/08/23 10:11:56, ahe wrote:
> maximum -> larger.

Done.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:132: * Returns the angle between the positive x-axis and the
vector ([b],[a]).
On 2012/08/23 10:44:36, ahe wrote:
> 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.

Done.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:133: * The result, in radians, is in the range -PI..PI. If
[a] is positive, this
On 2012/08/23 10:44:36, ahe wrote:
> How about one paragraph per case?

Done.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:144: * Returns [x] to the power of [exponent].
On 2012/08/23 10:44:36, ahe wrote:
> Add newline.

Done.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:145: * If the [exponent] is an integer the result is of the
same type as [x].
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.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:146: * Otherwise it is a [double].
On 2012/08/23 10:44:36, ahe wrote:
> Perhaps add a note that int doesn't overflow, but double might.

Done.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:173: * the range -1..1.
On 2012/08/23 10:44:36, ahe wrote:
> Check this.

Done.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:180: * the range -1..1.
On 2012/08/23 10:44:36, ahe wrote:
> Check this.

Done.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:186: * Returns a value in the range -PI..PI, or [:NaN:] if
[x] is [:NaN:].
Changed to -PI/2..PI/2.

https://chromiumcodereview.appspot.com/10879032/diff/1/lib/math/base.dart#new...
lib/math/base.dart:192: * Returns [:NaN:] if x is negative or [:NaN:].
That returns -0.0, by IEEE-754 decree. Now documented.