Update `num.compareTo` documentation.

sdk/lib/core/num.dart

 // 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.
 
 part of dart.core;
 
 /**
  * An integer or floating-point number.
  *
  * It is a compile-time error for any type other than [int] or [double]
@@ skipping 48 matching lines @@
    * Compares this to `other`.
    *
    * Returns a negative number if `this` is less than `other`, zero if they are
    * equal, and a positive number if `this` is greater than `other`.
    *
    * The orderding represented by this method is a total ordering of [num]
    * values. All distinct doubles are non-equal, as are all distinct integers,
    * 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.
+   * - All NaN values are considered equal, and greater than any numeric value.
+   * - -0.0 is less than 0.0 (and the integer 0), but greater than any non-zero
+   *    negative value.
+   * - Negative infinity is less than all other values and positive infinity is
+   *   greater than all non-NaN values.
+   * - 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 comparisons yield different results than the
+   * // 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);
 
   /** Addition operator. */
   num operator +(num other);
 
   /** Subtraction operator. */
   num operator -(num other);
 
   /** Multiplication operator. */
@@ skipping 358 matching lines @@
     result = double.parse(source, _returnDoubleNull);
     if (result != null) return result;
     if (onError == null) throw new FormatException(input);
     return onError(input);
   }
 
   /** Helper functions for [parse]. */
   static int _returnIntNull(String _) => null;
   static double _returnDoubleNull(String _) => null;
 }