Explain better than the en_US locale is always available, fix other doc glitches.

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
  * manner.
  * It allows the user to choose from a set of standard date time formats as well
  * as specify a customized pattern under certain locales. Date elements that
  * vary across locales include month name, week name, field order, etc.
  * We also allow the user to use any customized pattern to parse or format
  * date-time strings under certain locales. Date elements that vary across
  * locales include month name, weekname, field, order, etc.
  *
- * The actual date for the locales must be obtained. This can currently be done
- * in one of three ways, determined by which library you import. If you only
- * want to use en_US formatting you can use it directly, as a copy of that
- * locale is hard-coded into the formatter. In all other cases,
- * the [initializeDateFormatting] method must be called and will return a future
+ * Formatting dates in the default "en_US" format does not require any
+ * initialization. e.g.
+ *       print(new DateFormat.yMMMd().format(new Date.now()));
+ *
+ * But for other locales, the formatting data for the locale must be
+ * obtained. This can currently be done
+ * in one of three ways, determined by which library you import. In all cases,
+ * the "initializeDateFormatting" method must be called and will return a future
  * that is complete once the locale data is available. The result of the future
  * isn't important, but the data for that locale is available to the date
  * formatting and parsing once it completes.
  *
  * The easiest option is that the data may be available locally, imported in a
  * library that contains data for all the locales.
  *       import 'package:intl/date_symbol_data_local.dart';
- *       initializeDateFormatting("en_US", null).then((_) => runMyCode());
+ *       initializeDateFormatting("fr_FR", null).then((_) => runMyCode());
  *
  * If we are running outside of a browser, we may want to read the data
  * from files in the file system.
  *       import 'package:intl/date_symbol_data_file.dart';
  *       initializeDateFormatting("de_DE", null).then((_) => runMyCode());
  *
  * If we are running in a browser, we may want to read the data from the
  * server using the XmlHttpRequest mechanism.
  *       import 'package:intl/date_symbol_data_http_request.dart';
  *       initializeDateFormatting("pt_BR", null).then((_) => runMyCode());
@@ skipping 424 matching lines @@
    */
   _useDefaultPattern() {
     add_yMMMMd();
     add_jms();
   }
 
   /**
    * A series of regular expressions used to parse a format string into its
    * component fields.
    */
-  static List<Pattern> _matchers = [
+  static List<RegExp> _matchers = [
       // Quoted String - anything between single quotes, with escaping
       //   of single quotes by doubling them.
       // e.g. in the pattern "hh 'o''clock'" will match 'o''clock'
       new RegExp("^\'(?:[^\']|\'\')*\'"),
       // Fields - any sequence of 1 or more of the same field characters.
       // e.g. in "hh:mm:ss" will match hh, mm, and ss. But in "hms" would
       // match each letter individually.
       new RegExp(
         "^(?:G+|y+|M+|k+|S+|E+|a+|h+|K+|H+|c+|L+|Q+|d+|m+|s+|v+|z+|Z+)"),
       // Everything else - A sequence that is not quotes or field characters.
@@ skipping 91 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);
       }
     }
   }
 }