Fix markdown syntax in Intl

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.
 
 /**
  * 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.
  * <!-- TODO(efortuna): Customized pattern system -- suggested by i18n needs
  * feedback on appropriateness. -->
  * 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.
  *
  * 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
- *   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
- *   ABBR_MONTH                   MMM
- *   ABBR_MONTH_DAY               MMMd
- *   ABBR_MONTH_WEEKDAY_DAY       MMMEd
- *   MONTH                        MMMM
- *   MONTH_DAY                    MMMMd
- *   MONTH_WEEKDAY_DAY            MMMMEEEEd
- *   ABBR_QUARTER                 QQQ
- *   QUARTER                      QQQQ
- *   YEAR                         y
- *   YEAR_NUM_MONTH               yM
- *   YEAR_NUM_MONTH_DAY           yMd
- *   YEAR_NUM_MONTH_WEEKDAY_DAY   yMEd
- *   YEAR_ABBR_MONTH              yMMM
- *   YEAR_ABBR_MONTH_DAY          yMMMd
- *   YEAR_ABBR_MONTH_WEEKDAY_DAY  yMMMEd
- *   YEAR_MONTH                   yMMMM
- *   YEAR_MONTH_DAY               yMMMMd
- *   YEAR_MONTH_WEEKDAY_DAY       yMMMMEEEEd
- *   YEAR_ABBR_QUARTER            yQQQ
- *   YEAR_QUARTER                 yQQQQ
- *   HOUR24                       H
- *   HOUR24_MINUTE                Hm
- *   HOUR24_MINUTE_SECOND         Hms
- *   HOUR                         j
- *   HOUR_MINUTE                  jm
- *   HOUR_MINUTE_SECOND           jms
- *   HOUR_MINUTE_GENERIC_TZ       jmv
- *   HOUR_MINUTE_TZ               jmz
- *   HOUR_GENERIC_TZ              jv
- *   HOUR_TZ                      jz
- *   MINUTE                       m
- *   MINUTE_SECOND                ms
- *   SECOND                       s
+ *      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
+ *      ABBR_MONTH                   MMM
+ *      ABBR_MONTH_DAY               MMMd
+ *      ABBR_MONTH_WEEKDAY_DAY       MMMEd
+ *      MONTH                        MMMM
+ *      MONTH_DAY                    MMMMd
+ *      MONTH_WEEKDAY_DAY            MMMMEEEEd
+ *      ABBR_QUARTER                 QQQ
+ *      QUARTER                      QQQQ
+ *      YEAR                         y
+ *      YEAR_NUM_MONTH               yM
+ *      YEAR_NUM_MONTH_DAY           yMd
+ *      YEAR_NUM_MONTH_WEEKDAY_DAY   yMEd
+ *      YEAR_ABBR_MONTH              yMMM
+ *      YEAR_ABBR_MONTH_DAY          yMMMd
+ *      YEAR_ABBR_MONTH_WEEKDAY_DAY  yMMMEd
+ *      YEAR_MONTH                   yMMMM
+ *      YEAR_MONTH_DAY               yMMMMd
+ *      YEAR_MONTH_WEEKDAY_DAY       yMMMMEEEEd
+ *      YEAR_ABBR_QUARTER            yQQQ
+ *      YEAR_QUARTER                 yQQQQ
+ *      HOUR24                       H
+ *      HOUR24_MINUTE                Hm
+ *      HOUR24_MINUTE_SECOND         Hms
+ *      HOUR                         j
+ *      HOUR_MINUTE                  jm
+ *      HOUR_MINUTE_SECOND           jms
+ *      HOUR_MINUTE_GENERIC_TZ       jmv
+ *      HOUR_MINUTE_TZ               jmz
+ *      HOUR_GENERIC_TZ              jv
+ *      HOUR_TZ                      jz
+ *      MINUTE                       m
+ *      MINUTE_SECOND                ms
+ *      SECOND                       s
  *
  * Examples Using the US Locale:
  *
  *      Pattern                           Result
  *      ----------------                  -------
  *      new DateFormat.yMd()             -> 07/10/1996
  *      new DateFormat("yMd")            -> 07/10/1996
  *      new DateFormat.yMMMMd("en_US")   -> July 10, 1996
  *      new DateFormat("Hm", "en_US")    -> 12:08 PM
  *      new DateFormat.yMd().Hm()        -> 07/10/1996 12:08 PM
@@ skipping 22 matching lines @@
  *     k        hour in day (1~24)     (Number)            24
  *     K        hour in am/pm (0~11)   (Number)            0
  *     z        time zone              (Text)              Pacific Standard Time
  *     Z        time zone (RFC 822)    (Number)            -0800
  *     v        time zone (generic)    (Text)              Pacific Time
  *     Q        quarter                (Text)              Q3
  *     '        escape for text        (Delimiter)         'Date='
  *     ''       single quote           (Literal)           'o''clock'
  *
  * The count of pattern letters determine the format.
+ *
  * **Text**:
  * * 5 pattern letters--use narrow form for standalone. Otherwise does not apply
  * * 4 or more pattern letters--use full form,
  * * 3 pattern letters--use short or abbreviated form if one exists
  * * less than 3--use numeric form if one exists
  *
  * **Number**: the minimum number of digits. Shorter numbers are zero-padded to
  * this amount (e.g. if "m" produces "6", "mm" produces "06"). Year is handled
  * specially; that is, if the count of 'y' is 2, the Year will be truncated to
  * 2 digits. (e.g., if "yyyy" produces "1997", "yy" produces "97".) Unlike other
  * fields, fractional seconds are padded on the right with zero.
  *
- * (Text & Number): 3 or over, use text, otherwise use number.
+ * **(Text & Number)**: 3 or over, use text, otherwise use number.
  *
- * Any characters that not in the pattern will be treated as quoted text. For
+ * Any characters not in the pattern will be treated as quoted text. For
  * instance, characters like ':', '.', ' ', '#' and '@' will appear in the
- * resulting time text even they are not embraced within single quotes. In our
- * current pattern usage, we didn't use up all letters. But those unused
- * letters are strongly discouraged to be used as quoted text without quote.
- * That's because we may use other letter for pattern in future.
+ * resulting text even though they are not enclosed in single quotes. In our
+ * current pattern usage, not all letters have meanings. But those unused
+ * letters are strongly discouraged to be used as quoted text without quotes,
+ * because we may use other letters as pattern characters in the future.
  *
  * Examples Using the US Locale:
  *
- *     Format Pattern                         Result
- *     --------------                         -------
- *     "yyyy.MM.dd G 'at' HH:mm:ss vvvv"->1996.07.10 AD at 15:08:56 Pacific Time
- *     "EEE, MMM d, ''yy"               ->Wed, July 10, '96
- *     "h:mm a"                         ->12:08 PM
- *     "hh 'o''clock' a, zzzz"          ->12 o'clock PM, Pacific Daylight Time
- *     "K:mm a, vvv"                    ->0:00 PM, PT
- *     "yyyyy.MMMMM.dd GGG hh:mm aaa"   ->01996.July.10 AD 12:08 PM
+ *     Format Pattern                     Result
+ *     --------------                     -------
+ *     "yyyy.MM.dd G 'at' HH:mm:ss vvvv"  1996.07.10 AD at 15:08:56 Pacific Time
+ *     "EEE, MMM d, ''yy"                 Wed, July 10, '96
+ *     "h:mm a"                           12:08 PM
+ *     "hh 'o''clock' a, zzzz"            12 o'clock PM, Pacific Daylight Time
+ *     "K:mm a, vvv"                      0:00 PM, PT
+ *     "yyyyy.MMMMM.dd GGG hh:mm aaa"     01996.July.10 AD 12:08 PM
  *
  * When parsing a date string using the abbreviated year pattern ("yy"),
  * DateFormat must interpret the abbreviated year relative to some
  * century. It does this by adjusting dates to be within 80 years before and 20
  * years after the time the parse function is called. For example, using a
  * pattern of "MM/dd/yy" and a DateTimeParse instance created on Jan 1, 1997,
  * the string "01/11/12" would be interpreted as Jan 11, 2012 while the string
  * "05/04/64" would be interpreted as May 4, 1964. During parsing, only
  * strings consisting of exactly two digits, as defined by {@link
  * java.lang.Character#isDigit(char)}, will be parsed into the default
@@ skipping 12 matching lines @@
 #import('date_symbols.dart');
 #import('src/intl_helpers.dart');
 #import('src/date_format_internal.dart');
 
 #source('src/date_format_field.dart');
 #source('src/date_format_helpers.dart');
 
 class DateFormat {
 
   /**
-   * If [newPattern] matches one of the skeleton forms, it is looked up
-   * in [locale] or in the default if none is specified, and the corresponding
-   * full format string is used. If [newPattern] does not match one
-   * of the supported skeleton forms then it is used as a format directly.
+   * 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');`
+   *     new DateFormat('EEE, M/d/y');

[Emily Fortuna, 2012/10/02 23:44:08]

I thought ` denoted code?

[Alan Knight, 2012/10/02 23:45:33]

It didn't seem to. It was coming out with literal backquotes in the output.
Indenting four spaces did produce the right output.

    * would produce the same result, a date of the form
-   *     `Wed, 6/27/2012`
-   * However, the skeleton version would also adapt to other locales.
+   *     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.
    */
   DateFormat([String newPattern, String locale]) {
     // TODO(alanknight): It should be possible to specify multiple skeletons eg
     // date, time, timezone all separately. Adding many or named parameters to
     // the constructor seems awkward, especially with the possibility of
     // confusion with the locale. A "fluent" interface with cascading on an
     // instance might work better? A list of patterns is also possible.
@@ skipping 60 matching lines @@
    */
   String get locale => _locale;
 
   /**
    * Returns a list of all locales for which we have date formatting
    * information.
    */
   static List<String> allLocalesWithSymbols() => dateTimeSymbols.getKeys();
 
   /**
-   * Constructors for a set of predefined "skeletons" for which the
-   * internationalized forms are known. These can also be chained
-   * together using the "add_" instance methods below.
+   * The named constructors for this class are all conveniences for creating
+   * instances using one of the known "skeleton" formats, and having code
+   * completion support for discovering those formats.
+   * So,
+   *     new DateFormat.yMd("en_US")
+   * is equivalent to
+   *     new DateFormat("yMd", "en_US")
+   * To create a compound format you can use these constructors in combination
+   * with the add_ methods below. e.g.
+   *     new DateFormat.yMd().add_Hms();
+   * If the optional [locale] is omitted, the format will be created using the
+   * default locale in [Intl.systemLocale].
    */
   DateFormat.d([locale]) : this("d", locale);
   DateFormat.E([locale]) : this("E", locale);
   DateFormat.EEEE([locale]) : this("EEEE", locale);
   DateFormat.LLL([locale]) : this("LLL", locale);
   DateFormat.LLLL([locale]) : this("LLLL", locale);
   DateFormat.M([locale]) : this("M", locale);
   DateFormat.Md([locale]) : this("Md", locale);
   DateFormat.MEd([locale]) : this("MEd", locale);
   DateFormat.MMM([locale]) : this("MMM", locale);
@@ skipping 24 matching lines @@
   DateFormat.jms([locale]) : this("jms", locale);
   DateFormat.jmv([locale]) : this("jmv", locale);
   DateFormat.jmz([locale]) : this("jmz", locale);
   DateFormat.jv([locale]) : this("jv", locale);
   DateFormat.jz([locale]) : this("jz", locale);
   DateFormat.m([locale]) : this("m", locale);
   DateFormat.ms([locale]) : this("ms", locale);
   DateFormat.s([locale]) : this("s", locale);
 
   /**
-   * Methods for appending a particular skeleton to the format, or setting
+   * The "add_*" methods append a particular skeleton to the format, or set
    * it as the only format if none was previously set. These are primarily
    * useful for creating compound formats. For example
-   *       new DateFormat.yMd().add_hms();
+   *       new DateFormat.yMd().add_Hms();
    * would create a date format that prints both the date and the time.
    */
   DateFormat add_d() => addPattern("d");
   DateFormat add_E() => addPattern("E");
   DateFormat add_EEEE() => addPattern("EEEE");
   DateFormat add_LLL() => addPattern("LLL");
   DateFormat add_LLLL() => addPattern("LLLL");
   DateFormat add_M() => addPattern("M");
   DateFormat add_Md() => addPattern("Md");
   DateFormat add_MEd() => addPattern("MEd");
@@ skipping 25 matching lines @@
   DateFormat add_jms() => addPattern("jms");
   DateFormat add_jmv() => addPattern("jmv");
   DateFormat add_jmz() => addPattern("jmz");
   DateFormat add_jv() => addPattern("jv");
   DateFormat add_jz() => addPattern("jz");
   DateFormat add_m() => addPattern("m");
   DateFormat add_ms() => addPattern("ms");
   DateFormat add_s() => addPattern("s");
 
   /**
-   * ICU constants for format names, resolving to the corresponding skeletons.
+   * For each of the skeleton formats we also allow the use of the corresponding
+   * ICU constant names.
    */
+  static const String ABBR_MONTH = 'MMM';
   static const String DAY = 'd';
   static const String ABBR_WEEKDAY = 'E';
   static const String WEEKDAY = 'EEEE';
   static const String ABBR_STANDALONE_MONTH = 'LLL';
   static const String STANDALONE_MONTH = 'LLLL';
   static const String NUM_MONTH = 'M';
   static const String NUM_MONTH_DAY = 'Md';
   static const String NUM_MONTH_WEEKDAY_DAY = 'MEd';
-  static const String ABBR_MONTH = 'MMM';
   static const String ABBR_MONTH_DAY = 'MMMd';
   static const String ABBR_MONTH_WEEKDAY_DAY = 'MMMEd';
   static const String MONTH = 'MMMM';
   static const String MONTH_DAY = 'MMMMd';
   static const String MONTH_WEEKDAY_DAY = 'MMMMEEEEd';
   static const String ABBR_QUARTER = 'QQQ';
   static const String QUARTER = 'QQQQ';
   static const String YEAR = 'y';
   static const String YEAR_NUM_MONTH = 'yM';
   static const String YEAR_NUM_MONTH_DAY = 'yMd';
@@ skipping 167 matching lines @@
   List _reverse(List list) {
     // TODO(alanknight): Use standardized list reverse when implemented.
     // See Issue 2804.
     var result = new List();
     for (var i = list.length-1; i >= 0; i--) {
       result.addLast(list[i]);
     }
     return result;
   }
 }