Add documentation of double and int.

Add documentation of double and int.

There is a bit of comment duplication in here, but I think it is worth
it to have all the methods documented on api.dartlang.org for all the
types.

R=lrn@google.com
BUG=dartbug.com/4668

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

[Lasse Reichstein Nielsen, 2012-09-24 11:54:12]

LGTM!

https://codereview.chromium.org/10959067/diff/1/lib/core/double.dart
File lib/core/double.dart (right):

https://codereview.chromium.org/10959067/diff/1/lib/core/double.dart#newcode58
lib/core/double.dart:58: *  [:(3.5).round() == 4:] and [:(-3.5).round() == -4:].
Unrelated question: Do you have any idea why we picked this rounding?

https://codereview.chromium.org/10959067/diff/1/lib/core/double.dart#newcode69
lib/core/double.dart:69: * Returns the integer value obtained by discarding any
fractional
A little too long for a first sentence.
How about:
/**
 * Round towards zero to an integer.
 *
 * <your text>
 */

It's still a little hard to read :(

https://codereview.chromium.org/10959067/diff/1/lib/core/int.dart
File lib/core/int.dart (right):

https://codereview.chromium.org/10959067/diff/1/lib/core/int.dart#newcode9
lib/core/int.dart:9: * Integers are arbitrarily large in Dart.
are -> can be

https://codereview.chromium.org/10959067/diff/1/lib/core/int.dart#newcode13
lib/core/int.dart:13: * integers are therefore restricted to 53 bits because all
JavaScript
53 bits -> 53 significant bits

https://codereview.chromium.org/10959067/diff/1/lib/core/int.dart#newcode58
lib/core/int.dart:58: /** For integers the ceil method is the identify function.
*/
ceil -> truncate.

[Mads Ager (google), 2012-09-24 12:26:27]

https://codereview.chromium.org/10959067/diff/1/lib/core/double.dart
File lib/core/double.dart (right):

https://codereview.chromium.org/10959067/diff/1/lib/core/double.dart#newcode58
lib/core/double.dart:58: *  [:(3.5).round() == 4:] and [:(-3.5).round() == -4:].
On 2012/09/24 11:54:12, Lasse Reichstein Nielsen wrote:
> Unrelated question: Do you have any idea why we picked this rounding?

I don't, no. I'm just documenting what we are currently doing.

https://codereview.chromium.org/10959067/diff/1/lib/core/double.dart#newcode69
lib/core/double.dart:69: * Returns the integer value obtained by discarding any
fractional
On 2012/09/24 11:54:12, Lasse Reichstein Nielsen wrote:
> A little too long for a first sentence.
> How about:
> /**
>  * Round towards zero to an integer.
>  *
>  * <your text>
>  */
> 
> It's still a little hard to read :(

I would prefer to keep the comment as is. It is fairly short and explains
exactly what is going on.

https://codereview.chromium.org/10959067/diff/1/lib/core/int.dart
File lib/core/int.dart (right):

https://codereview.chromium.org/10959067/diff/1/lib/core/int.dart#newcode9
lib/core/int.dart:9: * Integers are arbitrarily large in Dart.
On 2012/09/24 11:54:12, Lasse Reichstein Nielsen wrote:
> are -> can be

Done.

https://codereview.chromium.org/10959067/diff/1/lib/core/int.dart#newcode13
lib/core/int.dart:13: * integers are therefore restricted to 53 bits because all
JavaScript
On 2012/09/24 11:54:12, Lasse Reichstein Nielsen wrote:
> 53 bits -> 53 significant bits

Done.

https://codereview.chromium.org/10959067/diff/1/lib/core/int.dart#newcode58
lib/core/int.dart:58: /** For integers the ceil method is the identify function.
*/
On 2012/09/24 11:54:12, Lasse Reichstein Nielsen wrote:
> ceil -> truncate.

Good catch. Thanks!

[floitsch, 2012-09-24 15:56:14]

LGTM.

https://codereview.chromium.org/10959067/diff/5001/lib/core/double.dart
File lib/core/double.dart (right):

https://codereview.chromium.org/10959067/diff/5001/lib/core/double.dart#newco...
lib/core/double.dart:58: *  [:(3.5).round() == 4:] and [:(-3.5).round() == -4:].
You should also note what happens for the range ]-0.5, 0.0[.
for example: (-0.3).round() => -0.0 or 0.0

I think we currently return -0.0, but I would like to change this to 0.0.

https://codereview.chromium.org/10959067/diff/5001/lib/core/double.dart#newco...
lib/core/double.dart:65: /** Returns the least integer value that is no smaller
than this [double]. */
ditto.

https://codereview.chromium.org/10959067/diff/5001/lib/core/double.dart#newco...
lib/core/double.dart:85: * [:d == double.parse(d.toString()):].
except for NaN. But I agree that we can leave it this way.

[Lasse Reichstein Nielsen, 2012-09-24 17:52:46]

https://codereview.chromium.org/10959067/diff/5001/lib/core/double.dart
File lib/core/double.dart (right):

https://codereview.chromium.org/10959067/diff/5001/lib/core/double.dart#newco...
lib/core/double.dart:85: * [:d == double.parse(d.toString()):].
Including NaN, actually, since double.parse("NaN") is NaN.

[Lasse Reichstein Nielsen, 2012-09-24 17:56:42]

https://codereview.chromium.org/10959067/diff/5001/lib/core/double.dart
File lib/core/double.dart (right):

https://codereview.chromium.org/10959067/diff/5001/lib/core/double.dart#newco...
lib/core/double.dart:58: *  [:(3.5).round() == 4:] and [:(-3.5).round() == -4:].
If the return type is double, I think -0.0 is the correct result.
Now, should the result type actually be double?

[floitsch, 2012-09-24 20:17:27]

https://codereview.chromium.org/10959067/diff/5001/lib/core/double.dart
File lib/core/double.dart (right):

https://codereview.chromium.org/10959067/diff/5001/lib/core/double.dart#newco...
lib/core/double.dart:58: *  [:(3.5).round() == 4:] and [:(-3.5).round() == -4:].
On 2012/09/24 17:56:42, Lasse Reichstein Nielsen wrote:
> If the return type is double, I think -0.0 is the correct result.
> Now, should the result type actually be double?
good point. I had thought a lot about this, and iirc my feeling was, that
round/floor/ceil is almost always used as integer. So I agree with you: it
should return an integer.
Ideally the VM should optimize x.ceil().toDouble() to make sure that the user
pays a big perf-penalty.

https://codereview.chromium.org/10959067/diff/5001/lib/core/double.dart#newco...
lib/core/double.dart:85: * [:d == double.parse(d.toString()):].
On 2012/09/24 17:52:46, Lasse Reichstein Nielsen wrote:
> Including NaN, actually, since double.parse("NaN") is NaN.
but we don't have NaN == NaN.