Update `num.compareTo` documentation.

sdk/lib/core/num.dart

Index: sdk/lib/core/num.dart
diff --git a/sdk/lib/core/num.dart b/sdk/lib/core/num.dart
index 21f23eef18321ab7fc4b59aa397cdbb7ead0b0d6..50fcb2e8be6288db8c5192fdc4c7e7fb39dc9362 100644
--- a/sdk/lib/core/num.dart
+++ b/sdk/lib/core/num.dart
@@ -66,16 +66,40 @@ abstract class num implements Comparable<num> {
    * but integers are equal to doubles if they have the same numerical
    * value.
    *
-   * For ordering, the double NaN value is considered equal to itself, and
-   * greater than any numeric value (unlike its behavior in `operator==`).
+   * For doubles, the `compareTo` operation is different from the partial
+   * ordering given by [operator==], [operator<] and [operator>]. For example,
+   * IEEE doubles impose that `0.0 == -0.0` and all comparison operations on
+   * NaN return false.
    *
-   * The double value -0.0 is considered less than 0.0 (and the integer 0), but
-   * greater than any non-zero negative value.
+   * This function imposes a complete ordering for doubles. When using
+   * `compareTo` the following properties hold:
    *
-   * Positive infinity is greater than any finite value (any value apart from
-   * itself and NaN), and negative infinity is less than any other value.
+   * - NaN is equal to itself, and greater than any numeric value.

[Lasse Reichstein Nielsen, 2016/11/29 15:59:21]

- All NaN values are considered equal, and greater ...

NaN is not one value, it's 2^53 different and distinguishable values
(distinguishable simply by `identical` on the VM). Yey!

[floitsch, 2016/12/02 01:26:56]

Done.

+   * - -0.0 is less than 0.0 (and the integer 0), but greater than any non-zero
+   *    negative value.
+   * - Positive infinity is greater than any finite value (any value apart from

[Lasse Reichstein Nielsen, 2016/11/29 15:59:21]

any negative value and any finite positive value

... or start with negative infinity:

Negative infinity is less than all other values and positive infinity is greater
than all non-NaN values.

[floitsch, 2016/12/02 01:26:56]

Done.

+   *   itself and NaN), and negative infinity is less than any other value.
+   * - All other values are compared using their numeric value.
    *
-   * All other values are compared using their numeric value.
+   * Examples:
+   * ```
+   * print(1.compareTo(2)); // => -1
+   * print(2.compareTo(1)); // => 1
+   * print(1.compareTo(1)); // => 0
+   *
+   * // The following operations yield different results than their

[Lasse Reichstein Nielsen, 2016/11/29 15:59:21]

operations -> comparisons (it's unclear what the "operation" is).
their -> the 

[floitsch, 2016/12/02 01:26:56]

Done.

+   * // corresponding comparison operators.
+   * print((-0.0).compareTo(0.0));  // => -1
+   * print(double.NAN.compareTo(double.NAN));  // => 0
+   * print(double.INFINITY.compareTo(double.NAN)); // => -1
+   *
+   * // -0.0, and NaN comparison operators have rules imposed by the IEEE
+   * // standard.
+   * print(-0.0 == 0.0); // => true
+   * print(double.NAN == double.NAN);  // => false
+   * print(double.INFINITY < double.NAN);  // => false
+   * print(double.NAN < double.INFINITY);  // => false
+   * print(double.NAN == double.INFINITY);  // => false
    */
   int compareTo(num other);