MessageFormat fixup

lib/i18n/date_format.dart

 /**
  * Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file

[Bob Nystrom, 2012/06/06 22:22:48]

The copyright block should just be line comments and not part of the dartdoc
comment. We don't want it in our generated docs. :)

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

  * 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, weekname, field, order, etc.

[Bob Nystrom, 2012/06/06 22:22:48]

"weekname" -> "week name"
"field, order" -> "field order"

[Emily Fortuna, 2012/06/06 22:51:43]

These were copied from the Closure docs. :-P Fixed!

  * //TODO(efortuna): Customized pattern system -- suggested by i18n needs

[Bob Nystrom, 2012/06/06 22:22:48]

Just so you know, this TODO will get included in the docs. You could make it an
HTML comment, or move it outside the doc comment.

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

  * // 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 as described
  * below.
  *
  * Time Format Syntax: To specify the time format use a time pattern string.
  * In this pattern, following letters are reserved as pattern letters, which
@@ skipping 17 matching lines @@
  *     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
  *     '        escape for text        (Delimiter)         'Date='
  *     ''       single quote           (Literal)           'o''clock'
  *
  * Items marked with '#' work differently than in Java.
  *
  * The count of pattern letters determine the format.
  * (Text): 4 or more pattern letters--use full form,

[Bob Nystrom, 2012/06/06 22:22:48]

You could use a markdown bullet list here, with emphasis for the first word:

* **Text** 4 or more patter...
    less than...
    In parsing...

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

  *         less than 4--use short or abbreviated form if one exists.
  *         In parsing, we will always try long format, then short.
  *         (e.g., "EEEE" produces "Monday", "EEE" produces "Mon")
  *
  * (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.
  *
@@ skipping 42 matching lines @@
  * the run, then the leftmost field is shortened by one character, and the
  * entire run is parsed again. This is repeated until either the parse succeeds
  * or the leftmost field is one character in length. If the parse still fails at
  * that point, the parse of the run fails.
  */
 
 #library('DateFormat');
 
 class DateFormat {
 
   /** Definition of this object formats dates. */

[Bob Nystrom, 2012/06/06 22:22:48]

"formats" -> "format's"?

[Emily Fortuna, 2012/06/06 22:51:43]

(added "how") done.

   var formatDefinition;

[Bob Nystrom, 2012/06/06 22:22:48]

Can this be typed? Should it be public and mutable?

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

 
   /**
    * String indicating the locale code with which the message is to be

[Bob Nystrom, 2012/06/06 22:22:48]

Remove "String indicating".

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

    * formatted (such as en-CA).
    */
   String _locale;
 
   /** 
    * Date/Time format "skeleton" patterns. Also specifiable by String, but
    * written this way so that they can be discoverable via autocomplete. These

[Bob Nystrom, 2012/06/06 22:22:48]

Yay autocomplete!

    * follow the ICU syntax described at the top of the file. These skeletons can
    * be combined and we will attempt to find the best format for each locale
    * given the pattern.
    * // TODO(efortuna): Hear back from i18n about Time Zones and the "core set"
    * // of skeleton patterns.
    */
                                           // Example of how this looks in the US
                                           // locale.
   static final String Hm = 'Hm';          // HH:mm
   static final String Hms = 'Hms';        // HH:mm:ss 
@@ skipping 72 matching lines @@
   DateFormat.mediumDateTime([this._locale]) : formatDefinition = mediumDateTime;
   DateFormat.shortDateTime([this._locale]) : formatDefinition = shortDateTime;
   
   /**
    * Constructor accepts a [formatDefinition], which can be a String, one of the
    * predefined static forms, or a custom date format using the syntax described
    * above. An optional [_locale] can be provided for specifics of the language
    * locale to be used, otherwise, we will attempt to infer it (acceptable if
    * Dart is running on the client, we can infer from the browser).
    */
   DateFormat([this.formatDefinition = fullDate, this._locale]);

[Bob Nystrom, 2012/06/06 22:22:48]

I think we try not to use private names as named parameters.

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

 
   /**
    * Given user input, attempt to parse the [inputString] into the anticipated
    * format.
    */
   String parse(String inputString) {
     return inputString;
   }
 
  /**
   * Format the given [date] object according to preset pattern and current 
   * locale and return a formated string for the given date.
   */
   String format(Date date, [TimeZone timeZone]) {
     // TODO(efortuna): optional TimeZone argument? TimeZone is deprecated...
     return date.toString();
   }
 
   /**
    * Returns a date string indicating how long ago (3 hours, 2 minutes)
    * something has happened or how long in the future something will happen
    * given a [reference] Date relative to the current time.
    */
   String formatDuration(Date reference) {
     return '';
   }
   
   /**
    * Formats a String indicating how long ago (negative [duration]) or how far

[Bob Nystrom, 2012/06/06 22:22:48]

I would either put "String" in [] or make it lowercase. Probably the latter. 

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

    * in the future (positive [duration]) some time is with respect to a
-   * reference [date]. The [duration] is expressed in miliseconds.
+   * reference [date].
    */
-  String formatDurationFrom(num duration, Date date) {
+  String formatDurationFrom(Duration duration, Date date) {
     return '';
   }
 }