Add minimal documentation to the num class.

Add minimal documentation to the num class.

I have kept the documentation to a minimum and only added a few
details. We can beef this up later if desirable.

R=lrn@google.com
BUG=

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

[Lasse Reichstein Nielsen, 2012-09-20 12:49:38]

LGTM

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart
File lib/core/num.dart (right):

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart#newcode8
lib/core/num.dart:8: /// Addition operator.
Why the /// comments now? We don't do that anywhere else.
I prefer /** ... */ for one-liners, and find /// to blend in too well with code.

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart#newcode9
lib/core/num.dart:9: num operator +(num other);
empty line after declarations (except the last in the block).

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart#newcode23
lib/core/num.dart:23: /// Unary minus operator.
That's the negate operator.

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart#newcode38
lib/core/num.dart:38: /// isNan predicate.
I'd rather be without this comment. It says nothing that the name of the
function don't, so we are no closer to having documented the function - but it
might seem so, which is worse than doing nothing.

Ditto for the following two.

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart#newcode65
lib/core/num.dart:65: /// Return this [num] as a [double].
///
/// If the number is not representable as a [double], an approximation
// is returned. For numberically large integers, the approximation may be
infinite.

[Mads Ager (google), 2012-09-20 13:36:08]

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart
File lib/core/num.dart (right):

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart#newcode8
lib/core/num.dart:8: /// Addition operator.
On 2012/09/20 12:49:38, Lasse Reichstein Nielsen wrote:
> Why the /// comments now? We don't do that anywhere else.
> I prefer /** ... */ for one-liners, and find /// to blend in too well with
code.

No particular reason. I think the comment style is pretty mixed already. I
usually do /** */ too, so I'll switch to that.

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart#newcode9
lib/core/num.dart:9: num operator +(num other);
On 2012/09/20 12:49:38, Lasse Reichstein Nielsen wrote:
> empty line after declarations (except the last in the block).

Done.

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart#newcode23
lib/core/num.dart:23: /// Unary minus operator.
On 2012/09/20 12:49:38, Lasse Reichstein Nielsen wrote:
> That's the negate operator.

Done.

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart#newcode38
lib/core/num.dart:38: /// isNan predicate.
On 2012/09/20 12:49:38, Lasse Reichstein Nielsen wrote:
> I'd rather be without this comment. It says nothing that the name of the
> function don't, so we are no closer to having documented the function - but it
> might seem so, which is worse than doing nothing.
> 
> Ditto for the following two.

I have removed these comments. However, this poses the question: should I remove
most of the operator comments as well? They do not add anything either.

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart#newcode65
lib/core/num.dart:65: /// Return this [num] as a [double].
On 2012/09/20 12:49:38, Lasse Reichstein Nielsen wrote:
> ///
> /// If the number is not representable as a [double], an approximation
> // is returned. For numberically large integers, the approximation may be
> infinite.

Done, thanks.

[Lasse Reichstein Nielsen, 2012-09-20 19:45:13]

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart
File lib/core/num.dart (right):

https://codereview.chromium.org/10961013/diff/4001/lib/core/num.dart#newcode38
lib/core/num.dart:38: /// isNan predicate.
They increase the information (not by a lot, but still) by giving names to the
operators. Saying "addition" is more meaningful than "plus" - the former is an
arithmetic operation, the latter is just the symbol.
So keep them.