Fixing various num docs regarding NAN, parse, and toString

BUG= https://code.google.com/p/dart/issues/detail?id=19284
R=lrn@google.com

Review URL: https://codereview.chromium.org//499993002

git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@39540 260f80e4-7a28-3924-810f-c04153c831b5

sdk/lib/core/double.dart

@@ -162,7 +162,8 @@ abstract class double extends num {
    * Returns "-0.0" for negative zero.
    *
    * For all doubles, `d`, converting to a string and parsing the string back
-   * gives the same value again: `d == double.parse(d.toString())`.
+   * gives the same value again: `d == double.parse(d.toString())` (except when
+   * `d` is NaN).
    */
   String toString();
 

sdk/lib/core/int.dart

@@ -262,7 +262,7 @@ abstract class int extends num {
    * optionally prefixed with a minus or plus sign ('-' or '+').
    *
    * It must always be the case for an int [:n:] and radix [:r:] that
-   * [:n == parseRadix(n.toRadixString(r), r):].
+   * [:n == int.parse(n.toRadixString(r), radix: r):].
    *
    * If the [source] is not a valid integer literal, optionally prefixed by a
    * sign, the [onError] is called with the [source] as argument, and its return

sdk/lib/core/num.dart

@@ -424,13 +424,15 @@ abstract class num implements Comparable<num> {
    * [int.parse] without a radix).
    * If that fails, it tries to parse the [input] as a double (similar to
    * [double.parse]).
-   * If that fails, too, it invokes [onError] with [input].
+   * If that fails, too, it invokes [onError] with [input], and the result
+   * of that invocation becomes the result of calling `parse`.
    *
    * If no [onError] is supplied, it defaults to a function that throws a
    * [FormatException].
    *
    * For any number `n`, this function satisfies
-   * `identical(n, num.parse(n.toString()))`.
+   * `identical(n, num.parse(n.toString()))` (except when `n` is a NaN `double`
+   * with a payload).
    */
   static num parse(String input, [num onError(String input)]) {
     String source = input.trim();