Document DateTime.parse accepted format.

sdk/lib/core/date_time.dart

Index: sdk/lib/core/date_time.dart
diff --git a/sdk/lib/core/date_time.dart b/sdk/lib/core/date_time.dart
index 7a1dbb85e8f47cf6ed765a6d4f0795fcdbe3ddf2..96460e7c58ea45f0a8e47568deabe48a5a7b557d 100644
--- a/sdk/lib/core/date_time.dart
+++ b/sdk/lib/core/date_time.dart
@@ -200,6 +200,29 @@ class DateTime implements Comparable {
    * The function parses a subset of ISO 8601
    * which includes the subset accepted by RFC 3339.
    *
+   * The accepted inputs are currently:
+   *
+   * * A date: A signed four-to-six digit year, two digit month and

[Søren Gjesse, 2014/10/06 09:29:01]

why restricted to 6?

[Lasse Reichstein Nielsen, 2014/10/06 09:47:20]

JavaScript has that limit, and we inherit the JS limit on valid days (+/-
1000000 days from epoch), so anything outside of 6 days is always too big.
ISO8601 allows more than 4 digits of year, but only if creator and receiver
pre-agrees on the number of digits. Out toString cannot create more than six
digits (because of the above limit on days), so this is kind of an agreement.

Actually, ISO8601 requires the >4 digit years to always have a sign, even if it
is '+'.
Noticing that, I'll change toIso8601String to always do four digit or
forced-signed six digit years

+   *   two digit day, optionally separated by `-` characters.
+   *   Examples: "19700101", "-0004-12-24", "81030-04-01".
+   * * An optional time part, separated from the date by either `T` or a space.
+   *   The time part is a two digit hour,
+   *   then optionally  and a two digit minutes value,

[Søren Gjesse, 2014/10/06 09:29:01]

remove 'and'

[Lasse Reichstein Nielsen, 2014/10/06 09:47:20]

Done.

+   *   then optionally a two digit seconds value, and
+   *   then optionally a '.' and a one-to-six digit second fraction.

[Søren Gjesse, 2014/10/06 09:29:01]

and -> followed by

[Lasse Reichstein Nielsen, 2014/10/06 09:47:20]

Done.

+   *   The minuts and seconds may be separated from the previous parts by a ':'.
+   *   Examples: "12", "12:30:24.124", "123010.50".
+   * * An optional time-zone offset part,
+   *   possibly separated from the previous by a space.
+   *   The time zone is either 'z' or 'Z', or it is a signed two digit hour
+   *   part and an optional two digit minute part.
+   *   The minutes may be separted from the hours by a ':'.
+   *   Examples: "Z", "-10", "01:30", "1130".
+   *
+   * This includes the output of both [toString] and [toIso8601String], which
+   * will be parsed back into a `DateTime` object with the same time as the
+   * original.
+   *
    * The result is always in either local time or UTC.
    * If a time zone offset other than UTC is specified,
    * the time is converted to the equivalent UTC time.
@@ -217,21 +240,21 @@ class DateTime implements Comparable {
    * * `"-123450101 00:00:00 Z"`: in the year -12345.
    * * `"2002-02-27T14:00:00-0500"`: Same as `"2002-02-27T19:00:00Z"`
    */
-  // TODO(floitsch): specify grammar.
   // TODO(lrn): restrict incorrect values like  2003-02-29T50:70:80.
+  // Or not, that may be a breaking change.
   static DateTime parse(String formattedString) {
     /*
      * date ::= yeardate time_opt timezone_opt
      * yeardate ::= year colon_opt month colon_opt day
-     * year ::= sign_opt digit{4,5}
+     * year ::= sign_opt digit{4,6}
      * colon_opt :: <empty> | ':'
      * sign ::= '+' | '-'
      * sign_opt ::=  <empty> | sign
      * month ::= digit{2}
      * day ::= digit{2}
      * time_opt ::= <empty> | (' ' | 'T') hour minutes_opt
-     * minutes_opt ::= <empty> | ':' digit{2} seconds_opt
-     * seconds_opt ::= <empty> | ':' digit{2} millis_opt
+     * minutes_opt ::= <empty> | colon_opt digit{2} seconds_opt
+     * seconds_opt ::= <empty> | colon_opt digit{2} millis_opt
      * millis_opt ::= <empty> | '.' digit{1,6}
      * timezone_opt ::= <empty> | space_opt timezone
      * space_opt :: ' ' | <empty>
@@ -451,6 +474,8 @@ class DateTime implements Comparable {
    * It does not support internationalized strings.
    * Use the [intl](http://pub.dartlang.org/packages/intl) package
    * at the pub shared packages repo.
+   *
+   * The resulting string can be parsed back using [parse].
    */
   String toString() {
     String y = _fourDigits(year);
@@ -470,8 +495,19 @@ class DateTime implements Comparable {
   /**
    * Returns an ISO-8601 full-precision extended format representation.
    *
-   * The format is "YYYY-MM-DDTHH:mm:ss.sssZ" for UTC time, and
-   * "YYYY-MM-DDTHH:mm:ss.sss" (no trailing "Z") for local/non-UTC time.
+   * The format is `yyyy-MM-ddTHH:mm:ss.sssZ` for UTC time, and
+   * `yyyy-MM-ddTHH:mm:ss.sss` (no trailing "Z") for local/non-UTC time,
+   * where:
+   *
+   * * `yyyy` is a four (or more) digit representation of the year,
+   * * `MM` is the month in the range 01 to 12,
+   * * `dd` is the day of the month in the range 01 to 31,
+   * * `HH` are hours in the range 00 to 23,
+   * * `mm` are minutes in the range 00 to 59,
+   * * `ss` are seconds in the range 00 to 59 (no leap seconds), and
+   * * `sss` are milliseconds in the range 000 to 999.
+   *
+   * The resulting string can be parsed back using [parse].
    */
   String toIso8601String() {
     String y = _fourDigits(year);