Add documentation of double and int.

lib/core/double.dart

-// Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
+// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-// Dart core library.
-
 // TODO: Convert this abstract class into a concrete class double
 // that uses the patch class functionality to account for the
 // different platform implementations.
 
+/**
+ * Representation of Dart doubles containing double specific constants
+ * and operations and specializations of operations inherited from
+ * [num].
+ *
+ * The [double] type is contagious. Operations on [double]s return
+ * [double] results.
+ */
 abstract class double extends num {
   static const double NAN = 0.0 / 0.0;
   static const double INFINITY = 1.0 / 0.0;
   static const double NEGATIVE_INFINITY = -INFINITY;
 
-  // Specialization of super-interface. Double is contagious. We can therefore
-  // specialize more methods than in other num sub-interfaces.
+  /** Return the remainder from dividing this [double] by [other]. */
   abstract double remainder(num other);
+
+  /** Addition operator. */
   abstract double operator +(num other);
+
+  /** Subtraction operator. */
   abstract double operator -(num other);
+
+  /** Multiplication operator. */
   abstract double operator *(num other);
+
+  /** Euclidean modulo operator. */
   abstract double operator %(num other);
+
+  /** Division operator. */
   abstract double operator /(num other);
+
+  /**
+   * Truncating division operator.
+   *
+   * The result of the truncating division [:a ~/ b:] is equivalent to
+   * [:(a / b).truncate():].
+   */
   abstract double operator ~/(num other);
+
+  /** Negate operator. */
   abstract double operator -();
+
+  /** Returns the absolute value of this [double]. */
   abstract double abs();
+
+  /**
+   * Returns the integer value closest to this [double].
+   *
+   * Rounds away from zero when there is no closest integer:
+   *  [:(3.5).round() == 4:] and [:(-3.5).round() == -4:].

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

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.

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

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]

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.

+   */
   abstract double round();
+
+  /** Returns the greatest integer value no greater than this [double]. */
   abstract double floor();
+
+  /** Returns the least integer value that is no smaller than this [double]. */

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

ditto.

   abstract double ceil();
+
+  /**
+   * Returns the integer value obtained by discarding any fractional
+   * digits from this [double].
+   */
   abstract double truncate();
 
   /**
    * Provide a representation of this [double] value.
    *
    * The representation is a number literal such that the closest double value
    * to the representation's mathematical value is this [double].
    *
    * Returns "NaN" for the Not-a-Number value.
    * Returns "Infinity" and "-Infinity" for positive and negative Infinity.
    * Returns "-0.0" for negative zero.
    *
    * It should always be the case that if [:d:] is a [double], then
    * [:d == double.parse(d.toString()):].

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

except for NaN. But I agree that we can leave it this way.

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

Including NaN, actually, since double.parse("NaN") is NaN.

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

but we don't have NaN == NaN.

    */
   abstract String toString();
 
   /**
    * Parse [source] as an double literal and return its value.
    *
    * Accepts the same format as double literals:
    *   [: ['+'|'-'] [digit* '.'] digit+ [('e'|'E') ['+'|'-'] digit+] :]
    *
-   * Also recognizes "NaN", "Infinity" and "-Infinity" as inputs and returns the
-   * corresponding double value.
+   * Also recognizes "NaN", "Infinity" and "-Infinity" as inputs and
+   * returns the corresponding double value.
+   *
    * Throws a [FormatException] if [source] is not a valid double literal.
    */
   external static double parse(String source);
 }