Document the exception on DateFormat.parse

pkg/intl/lib/date_format.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 intl;
 
 // TODO(efortuna): Customized pattern system -- suggested by i18n needs
 // feedback on appropriateness.
 /**
  * DateFormat is for formatting and parsing dates in a locale-sensitive
@@ skipping 234 matching lines @@
    * Formats a string indicating how long ago (negative [duration]) or how far
    * in the future (positive [duration]) some time is with respect to a
    * reference [date].
    */
   String formatDurationFrom(Duration duration, DateTime date) {
     return '';
   }
 
   /**
    * Given user input, attempt to parse the [inputString] into the anticipated
-   * format, treating it as being in the local timezone.
+   * format, treating it as being in the local timezone. If [inputString] does
+   * not match our format, throws a [FormatException].
    */
   DateTime parse(String inputString, [utc = false]) {
     // TODO(alanknight): The Closure code refers to special parsing of numeric
     // values with no delimiters, which we currently don't do. Should we?
     var dateFields = new _DateBuilder();
     if (utc) dateFields.utc=true;
     var stream = new _Stream(inputString);
     _formatFields.forEach(
         (each) => each.parse(stream, dateFields));
     return dateFields.asDate();
@@ skipping 324 matching lines @@
   _DateFormatField _match(String pattern) {
     for (var i = 0; i < _matchers.length; i++) {
       var regex = _matchers[i];
       var match = regex.firstMatch(pattern);
       if (match != null) {
         return _fieldConstructors[i](match.group(0), this);
       }
     }
   }
 }