Merge ec355f1 into 58ad941

Author: hoylen

sdk/lib/core/date_time.dart

@@ -259,8 +259,16 @@ class DateTime implements Comparable<DateTime> {
   /// * `"2012-02-27T14+00:00"`
   /// * `"-123450101 00:00:00 Z"`: in the year -12345.
   /// * `"2002-02-27T14:00:00-0500"`: Same as `"2002-02-27T19:00:00Z"`
-  // TODO(lrn): restrict incorrect values like  2003-02-29T50:70:80.
-  // Or not, that may be a breaking change.
+  ///
+  /// This method accepts out-of-range component values and interprets
+  /// them as overflows into the next larger component.
+  /// For example, "2020-01-42" will be parsed as 2020-02-11, because
+  /// the last valid date in that month is 2020-01-31, so 42 days is
+  /// interprted as 31 days of that month plus 11 days into the next month.
+  ///
+  /// To detect and reject invalid component values, use
+  /// [DateFormat.parseStrict](https://pub.dev/documentation/intl/latest/intl/DateFormat/parseStrict.html)
+  /// from the [intl](https://pub.dev/packages/intl) package.
   static DateTime parse(String formattedString) {
     var re = _parseFormat;
     Match? match = re.firstMatch(formattedString);