Fix error in example for printing dates, clarify comments in general

lib/src/intl/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.
  *
  * Formatting dates in the default "en_US" format does not require any
  * initialization. e.g.
  *       print(new DateFormat.yMMMd().format(new Date.now()));
@@ skipping 23 matching lines @@
  *
  * The code in example/basic/basic_example.dart shows a full example of
  * using this mechanism.
  *
  * Once we have the locale data, we need to specify the particular format.
  * This library uses the ICU/JDK date/time pattern specification both for
  * complete format specifications and also the abbreviated "skeleton" form
  * which can also adapt to different locales and is preferred where available.
  *
  * Skeletons: These can be specified either as the ICU constant name or as the
- * skeleton to which it resolves. The supported set of skeletons is as follows
+ * skeleton to which it resolves. The supported set of skeletons is as follows.
+ * For each skeleton there is a named constructor that can be used to create it.
+ * It's also possible to pass the skeleton as a string, but the constructor
+ * is preferred.
+ * 
  *      ICU Name                   Skeleton
  *      --------                   --------
  *      DAY                          d
  *      ABBR_WEEKDAY                 E
  *      WEEKDAY                      EEEE
  *      ABBR_STANDALONE_MONTH        LLL
  *      STANDALONE_MONTH             LLLL
  *      NUM_MONTH                    M
  *      NUM_MONTH_DAY                Md
  *      NUM_MONTH_WEEKDAY_DAY        MEd
@@ skipping 31 matching lines @@
  *      MINUTE_SECOND                ms
  *      SECOND                       s
  *
  * Examples Using the US Locale:
  *
  *      Pattern                           Result
  *      ----------------                  -------
  *      new DateFormat.yMd()             -> 7/10/1996
  *      new DateFormat("yMd")            -> 7/10/1996
  *      new DateFormat.yMMMMd("en_US")   -> July 10, 1996
- *      new DateFormat("Hm", "en_US")    -> 12:08 PM
- *      new DateFormat.yMd().add_Hm()    -> 7/10/1996 12:08 PM
+ *      new DateFormat.jm()              -> 5:08 PM
+ *      new DateFormat.yMd().add_jm()    -> 7/10/1996 5:08 PM
+ *      new DateFormat.Hm()              -> 17:08 // force 24 hour time
  *
  * Explicit Pattern Syntax: Formats can also be specified with a pattern string.
- * The skeleton forms will resolve to explicit patterns of this form, but will
- * also adapt to different patterns in different locales.
- * The following characters are reserved:
+ * This can be used for formats that don't have a skeleton available, but these
+ * will not adapt to different locales. For example, in an explicit pattern the 
+ * letters "H" and "h" are available for 24 hour and 12 hour time formats 
+ * respectively. But there isn't a way in an explicit pattern to get the
+ * behaviour of the "j" skeleton, which prints 24 hour or 12 hour time according
+ * to the conventions of the locale, and also includes am/pm markers where 
+ * appropriate. So it is preferable to use the skeletons.
+ *
+ * The following characters are available in explicit patterns:
  *
  *     Symbol   Meaning                Presentation        Example
  *     ------   -------                ------------        -------
  *     G        era designator         (Text)              AD
  *     y        year                   (Number)            1996
  *     M        month in year          (Text & Number)     July & 07
  *     L        standalone month       (Text & Number)     July & 07
  *     d        day in month           (Number)            10
  *     c        standalone day         (Number)            10
  *     h        hour in am/pm (1~12)   (Number)            12
@@ skipping 69 matching lines @@
   /**
    * Creates a new DateFormat, using the format specified by [newPattern]. For
    * forms that match one of our predefined skeletons, we look up the
    * corresponding pattern in [locale] (or in the default locale if none is
    * specified) and use the resulting full format string. This is the
    * preferred usage, but if [newPattern] does not match one of the skeletons,
    * then it is used as a format directly, but will not be adapted to suit
    * the locale.
    *
    * For example, in an en_US locale, specifying the skeleton
-   *     new DateFormat('yMEd');
+   *     new DateFormat.yMEd();
    * or the explicit
    *     new DateFormat('EEE, M/d/y');
    * would produce the same result, a date of the form
    *     Wed, 6/27/2012
    * The first version would produce a different format string if used in
    * another locale, but the second format would always be the same.
    *
    * If [locale] does not exist in our set of supported locales then an
    * [ArgumentError] is thrown.
    */
@@ skipping 61 matching lines @@
    * [parse] does. It also does not allow leading whitespace on delimiters,
    * and does not allow alternative names for months or weekdays other than
    * those the format knows about. The restrictions are quite arbitrary and
    * it's not known how well they'll work for locales that aren't English-like.
    *
    * If [inputString] does not parse, this throws a
    * [FormatException].
    *
    * For example, this will accept
    *
-   *       new DateTimeFormat.yMMMd("en_US").parseLoose("SEp   3 2014");
-   *       new DateTimeFormat.yMd("en_US").parseLoose("09    03/2014");
+   *       new DateFormat.yMMMd("en_US").parseLoose("SEp   3 2014");
+   *       new DateFormat.yMd("en_US").parseLoose("09    03/2014");
    *
    * It will NOT accept
    *
    *      // "Sept" is not a valid month name.
-   *      new DateTimeFormat.yMMMd("en_US").parseLoose("Sept 3, 2014");
+   *      new DateFormat.yMMMd("en_US").parseLoose("Sept 3, 2014");
    *      // Delimiters can't have leading whitespace.
-   *      new DateTimeFormat.yMd("en_US").parseLoose("09 / 03 / 2014");
+   *      new DateFormat.yMd("en_US").parseLoose("09 / 03 / 2014");
    */
   DateTime parseLoose(String inputString, [utc = false]) {
     try {
       return _parse(inputString, utc: utc, strict: true);
     } on FormatException {
       return _parseLoose(inputString.toLowerCase(), utc);
     }
   }
 
   _parseLoose(String inputString, bool utc) {
@@ skipping 369 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);
       }
     }
   }
 }