docs(formatter): improvements to currency, date, filter, and formatter library

Closes dart-archive#1008

Author: naomiblack

lib/core/annotation_src.dart

@@ -547,8 +547,11 @@ abstract class DetachAware {
 }
 
 /**
- * Use @[Formatter] annotation to register a new formatter. A formatter is a class
- * with a [call] method (a callable function).
+ * Use the @[Formatter] class annotation to register a new formatter.
+ *
+ * A formatter is a pure function that performs a transformation on input data from an expression.
+ * For more on formatters in Angular, see the documentation for the
+ * [angular:formatter](#angular-formatter) library.
  *
  * Usage:
  *

lib/formatter/currency.dart

@@ -1,8 +1,10 @@
 part of angular.formatter_internal;
 
 /**
- * Formats a number as a currency (ie $1,234.56). When no currency symbol is
- * provided, '$' used.
+ * Formats a number as a currency (for example $1,234.56).
+ *
+ * When no currency symbol is provided, '$' is used. For more on formatters,
+ * see the [angular:formatter](#angular-formatter) library.
  *
  *
  * Usage:
@@ -16,11 +18,11 @@ class Currency implements Function {
   var _nfs = new Map<String, NumberFormat>();
 
   /**
-   *  [value]: the value to format
-   *
-   *  [symbol]: Symbol to use.
+   *  Format a number as a currency.
    *
-   *  [leading]: Symbol should be placed in front of the number
+   *  - `value`: the value to format as currency.
+   *  - `symbol`: the currency symbol to use. If no symbol is specified, `$` is used.
+   *  - `leading`: places the symbol in front of the number instead of following it.
    */
   call(value, [symbol = r'$', leading = true]) {
     if (value is String) value = double.parse(value);

lib/formatter/date.dart

@@ -1,24 +1,30 @@
 part of angular.formatter_internal;
 
 /**
- * Formats date to a string based on the requested format.
- * See Dart http://api.dartlang.org/docs/releases/latest/intl/DateFormat.html
- * for full formating options.
- *
- * - `medium`: equivalent to `MMM d, y h:mm:ss a` for en_US locale (e.g. Sep 3, 2010 12:05:08 pm)
- * - `short`: equivalent to `M/d/yy h:mm a` for en_US locale (e.g. 9/3/10 12:05 pm)
- * - `fullDate`: equivalent to `EEEE, MMMM d, y` for en_US locale (e.g. Friday, September 3, 2010)
- * - `longDate`: equivalent to `MMMM d, y` for en_US locale (e.g. September 3, 2010)
- * - `mediumDate`: equivalent to `MMM d, y` for en_US locale (e.g. Sep 3, 2010)
- * - `shortDate`: equivalent to `M/d/yy` for en_US locale (e.g. 9/3/10)
- * - `mediumTime`: equivalent to `h:mm:ss a` for en_US locale (e.g. 12:05:08 pm)
- * - `shortTime`: equivalent to `h:mm a` for en_US locale (e.g. 12:05 pm)
- *
+ * Formats a date value to a string based on the requested format.
  *
  * Usage:
  *
  *     {{ date_expression | date[:format] }}
  *
+ * Here `format` may be specified explicitly, or by using one of the following predefined
+ * localizable names:
+ *
+ *      FORMAT NAME     AS DEFINED FOR en_US             OUTPUT
+ *     -------------   ----------------------   ---------------------------
+ *      medium          MMM d, y h:mm:ss a       Sep 3, 2010 12:05:08 pm
+ *      short           M/d/yy h:mm a            9/3/10 12:05 pm
+ *      fullDate        EEEE, MMMM d, y          Friday, September 3, 2010
+ *      longDate        MMMM d, y                September 3, 2010
+ *      mediumDate      MMM d, y                 Sep 3, 2010
+ *      shortDate       M/d/yy                   9/3/10
+ *      mediumTime      h:mm:ss a                12:05:08 pm
+ *      shortTime       h:mm a                   12:05 pm
+ *
+ *
+ * For more on explicit formatting of dates and date syntax, see the documentation for the
+ * [DartFormat class](http://api.dartlang.org/docs/releases/latest/intl/DateFormat.html).
+ *
  */
 @Formatter(name:'date')
 class Date implements Function {
@@ -36,15 +42,12 @@ class Date implements Function {
   var _dfs = new Map<String, Map<String, DateFormat>>();
 
   /**
-   *  [date]: Date to format either as Date object, milliseconds
-   *    ([string] or [num]) or various ISO 8601 datetime string formats
-   *    (e.g. `yyyy-MM-ddTHH:mm:ss.SSSZ` and its shorter versions like
-   *    `yyyy-MM-ddTHH:mmZ`, `yyyy-MM-dd` or `yyyyMMddTHHmmssZ`). If no
-   *    timezone is specified in the string input, the time is considered to
-   *    be in the local timezone.
+   * Format a value as a date.
    *
-   *  [format]: Formatting rules (see Description). If not specified,
-   *    mediumDate is used
+   *  - `date`:   value to format as a date. If no timezone is specified in the string input,
+   *     the time is considered to be in the local timezone.
+   *  - `format`: Either a named format, or an explicit format specification.  If no format is
+   *     specified, mediumDate is used.
    *
    */
   dynamic call(Object date, [String format = 'mediumDate']) {

lib/formatter/filter.dart

@@ -8,40 +8,35 @@ typedef bool _Equals(a, b);
  * Selects a subset of items from the provided [List] and returns it as a new
  * [List].
  *
- * In addition to the input list (implicit in an Angular expression syntax),
- * this formatter takes 1 required and 1 optional parameter.  They are:
+ * Usage:
  *
- * - `expression` (required) - one of [Map], [Function], [String], [bool], [num]
- * - `comparator` (optional)
+ *      <div ng-repeat="item in items | filter:_expression_[:_comparator_]">
  *
- * <br>
+ * In addition to the `expression`, which is used to select a subset from the list,
+ * you can also specify a `comparator` to specify how the operation is performed. 
  *
- * # expression
  *
- * can be one of:
+ * `expression` can be of the following types:
  *
- * - [String], [bool] and [num]:  Only items in the List that directly
+ * - [String], [bool] and [num]:  Only items in the list that directly
  *   match this expression, items that are Maps with any value matching this
- *   item and items that are Lists containing a matching items are returned.
+ *   item, and items that are lists containing a matching items are returned.
  *
  * - [Map]:  This defines a pattern map.  Filters specific properties on objects
- *   contained in the input List.  For example `{name:"M", phone:"1"}` predicate
+ *   contained in the input list.  For example `{name:"M", phone:"1"}` predicate
  *   will return a list of items which have property `name` containing "M" and
  *   property `phone` containing "1".  A special property name, `$`, can be used
  *   (as in `{$: "text"}`) to accept a match against any property of the object.
  *   That's equivalent to the simple substring match with a `String` as
  *   described above.
  *
- * - [Function]:  This allows you to supply a custom function to formatter the
+ * - [Function]:  This allows you to supply a custom function to filter the
  *   List.  The function is called for each element of the List.  The returned
  *   List contains exactly those elements for which this function returned
  *   `true`.
  *
- * <br>
  *
- * # comparator
- *
- * can be one of:
+ * `comparator` is optional and can be one of the following:
  *
  * - `bool comparator(expected, actual)`:  The function will be called with the
  *   object value and the predicate value to compare and should return true if
@@ -55,7 +50,6 @@ typedef bool _Equals(a, b);
  *
  * - `false|null`:  Specifies case insensitive substring matching.
  *
- * <br>
  *
  * # Example ([view in plunker](http://plnkr.co/edit/6Mxz6r?p=info)):
  *

lib/formatter/module.dart

@@ -5,7 +5,8 @@
  *
  * This library is included as part of [angular.dart](#angular/angular). It provides all of
  * the core formatters available in Angular. You can extend Angular by writing your own formatters
- * and providing them as part of a custom library.
+ * and providing them as part of a custom library. See the @[Formatter](#angular-core-annotation
+ * .Formatter) class annotation for more detail.
  *
  * Formatters are typically used within `{{ }}` to
  * convert data to human-readable form. They may also be used inside repeaters to transform arrays.