docs(formatter): edit and update formatter docs

lib/core/annotation_src.dart

@@ -547,10 +547,16 @@ 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 identify a class as a formatter.
  *
- * Usage:
+ * 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.
+ *
+ * A formatter class must have a call method with at least one parameter, which specifies the value to format. Any
+ * additional parameters are treated as arguments of the formatter.
+ *
+ * **Usage**
  *
  *     // Declaration
  *     @Formatter(name:'myFormatter')

lib/formatter/arrayify.dart

@@ -1,9 +1,9 @@
 part of angular.formatter_internal;
 
 /**
- * Given a Map, returns a list of items which have `key` and `value` property.
+ * Transforms a Map into an array so that the map can be used with `ng-repeat`.
  *
- * Usage:
+ * Example:
  *
  *     <div ng-repeat="item in {'key1': 'value1', 'key2':'value2'} | arrayify">
  *       {{item.key}}: {{item.value}}

lib/formatter/currency.dart

@@ -7,10 +7,17 @@ part of angular.formatter_internal;
  * see the [angular:formatter](#angular-formatter) library.
  *
  *
- * Usage:
+ * # Usage
  *
  *     {{ numeric_expression | currency[:symbol[:leading]] }}
  *
+ * # Example
+ *
+ *     {{ 1234 | currency }}                 // output is $1,234.00
+ *     {{ 1234 | currency:'CAD' }}           // output is CAD1,234.00
+ *     {{ 1234 | currency:'CAD':false }}    // output is  1,234.00CAD
+ *
+ *
  */
 @Formatter(name:'currency')
 class Currency implements Function {
@@ -22,7 +29,8 @@ class Currency implements Function {
    *
    *  - `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.
+   *  - `leading`: false places the symbol after the number instead of before
+   *     it. (By default, leading is true.)
    */
   call(value, [symbol = r'$', leading = true]) {
     if (value is String) value = double.parse(value);

lib/formatter/date.dart

@@ -5,7 +5,7 @@ part of angular.formatter_internal;
  *
  * Usage:
  *
- *     {{ date_expression | date[:format] }}
+ *     date_expression | date[:format]
  *
  * Here `format` may be specified explicitly, or by using one of the following predefined
  * localizable names:
@@ -23,7 +23,7 @@ part of angular.formatter_internal;
  *
  *
  * 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).
+ * [DartFormat class](https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/intl/intl.DateFormat).
  *
  */
 @Formatter(name:'date')

lib/formatter/filter.dart

@@ -8,15 +8,14 @@ typedef bool _Equals(a, b);
  * Selects a subset of items from the provided [List] and returns it as a new
  * [List].
  *
- * Usage:
+ * # Usage
  *
- *      <div ng-repeat="item in items | filter:_expression_[:_comparator_]">
+ *      filter: expression[:comparator]
  *
- * 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. 
+ * 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 of the following types:
+ * The expression can be of the following types:
  *
  * - [String], [bool] and [num]:  Only items in the list that directly
  *   match this expression, items that are Maps with any value matching this
@@ -36,7 +35,7 @@ typedef bool _Equals(a, b);
  *   `true`.
  *
  *
- * `comparator` is optional and can be one of the following:
+ * The 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

lib/formatter/json.dart

@@ -1,12 +1,18 @@
 part of angular.formatter_internal;
 
 /**
- * Allows you to convert a JavaScript object into JSON string. This formatter is
- * mostly useful for debugging.
+ * Converts an object into a JSON string.
  *
- * Usage:
+ * This formatter is mostly useful for debugging.
  *
- *     {{ json_expression | json }}
+ * Note that the object to convert must be directly encodable to JSON, that is, a
+ * number, boolean, string, null, list or a map with string keys).  To convert other objects, the
+ * [toEncodable](http://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart-convert
+ * .JsonCodec#id_encode) function must be used first.
+ *
+ * # Usage
+ *
+ *     json_expression | json
  */
 @Formatter(name:'json')
 class Json implements Function {

lib/formatter/limit_to.dart

@@ -2,34 +2,37 @@ part of angular.formatter_internal;
 
 /**
  * Creates a new List or String containing only a prefix/suffix of the
- * elements as specified by the `limit` parameter.
+ * elements.
  *
- * When operating on a List, the returned list is always a copy even when all
- * the elements are being returned.
+ * The number of elements to return is specified by the `limitTo` parameter.
+ *
+ * # Usage
+ *
+ *     expression | limitTo:number
  *
- * When the `limit` expression evaluates to a positive integer, `limit` items
- * from the beginning of the List/String are returned.  When `limit` evaluates
- * to a negative integer, `|limit|` items from the end of the List/String are
- * returned.  If `|limit|` is larger than the size of the List/String, then the
- * entire List/String is returned.  In the case of a List, a copy of the list is
- * returned.
+ * Where the input expression is a [List] or [String], and `limitTo` is:
  *
- * If the `limit` expression evaluates to a null or non-integer, then an empty
- * list is returned.  If the input is a null List/String, a null is returned.
+ * - **a positive integer**: return _number_ items from the beginning of the list or string
+ * expression.
+ * - **a negative integer**: return _number_ items from the end of the list or string expression.
+ * - **`|limitTo|` greater than the size of the expression**: return the entire expression.
+ * - **null** or all other cases: return an empty list or string.
+ *
+ * When operating on a [List], the returned list is always a copy even when all
+ * the elements are being returned.
  *
- * Example:
+ * # Examples
  *
- * - `{{ 'abcdefghij' | limitTo: 4 }}` → `'abcd'`
- * - `{{ 'abcdefghij' | limitTo: -4 }}` → `'ghij'`
- * - `{{ 'abcdefghij' | limitTo: -100 }}` → `'abcdefghij'`
+ *     {{ 'abcdefghij' | limitTo: 4 }}       // output is 'abcd'
+ *     {{ 'abcdefghij' | limitTo: -4 }}      // output is 'ghij'
+ *     {{ 'abcdefghij' | limitTo: -100 }}    // output is 'abcdefghij'
  *
- * <br>
  *
- * This [ng-repeat] directive:
+ * This `ng-repeat` directive:
  *
  *     <li ng-repeat="i in 'abcdefghij' | limitTo:-2">{{i}}</li>
  *
- * results in
+ * produces the following:
  *
  *     <li>i</li>
  *     <li>j</li>

lib/formatter/lowercase.dart

@@ -1,11 +1,11 @@
 part of angular.formatter_internal;
 
 /**
- * Converts string to lowercase.
+ * Converts a string to lowercase.
  *
- * Usage:
+ * # Usage
  *
- *     {{ lowercase_expression | lowercase }}
+ *     expression | lowercase
  */
 @Formatter(name:'lowercase')
 class Lowercase implements Function {

lib/formatter/module.dart

@@ -1,5 +1,4 @@
 /**
- *
  * Formatters for [angular.dart](#angular/angular), a web framework for Dart. A formatter is a
  * pure function that performs a transformation on input data from an expression.
  *
@@ -13,17 +12,16 @@
  *
  * For example:
  *
- *      {{ _some_expression_ | json }}
+ *     {{ expression | json }}
  *
  * or, in a repeater:
  *
- *      <div ng-repeat="item in items | filter:_predicate_">
- *
- *
+ *      <div ng-repeat="item in items | limitTo:2">
  */
 library angular.formatter;
 
 export "package:angular/formatter/module_internal.dart" show
+    FormatterModule,
     Currency,
     Date,
     Filter,

lib/formatter/module_internal.dart

@@ -19,6 +19,12 @@ part 'order_by.dart';
 part 'uppercase.dart';
 part 'stringify.dart';
 
+/**
+ * This module registers all the Angular formatters.
+ *
+ * When instantiating an Angular application through applicationFactory,
+ * FormatterModule is automatically included.
+ */
 class FormatterModule extends Module {
   FormatterModule() {
     bind(Arrayify);

lib/formatter/number.dart

@@ -3,12 +3,12 @@ part of angular.formatter_internal;
 /**
  * Formats a number as text.
  *
- * If the input is not a number an empty string is returned.
+ * If the input is not a number, an empty string is returned.
  *
  *
- * Usage:
+ * # Usage
  *
- *     {{ number_expression | number[:fractionSize] }}
+ *     number_expression | number[:fractionSize]
  *
  */
 @Formatter(name:'number')
@@ -17,12 +17,14 @@ class Number {
   var _nfs = new Map<String, Map<num, NumberFormat>>();
 
   /**
-   *  [value]: the value to format
+   * Format a number as text.
+   *
+   * - `value`: the value to format
+   * - `fractionSize`: Number of decimal places to round the number to.
+   *
+   * When `fractionSize` is not provided, fraction size is computed from the current locale's number
+   * formatting pattern. In the case of the default locale, it will be 3.
    *
-   *  [fractionSize]: Number of decimal places to round the number to. If this
-   *    is not provided then the fraction size is computed from the current
-   *    locale's number formatting pattern. In the case of the default locale,
-   *    it will be 3.
    */
   call(value, [fractionSize = null]) {
     if (value is String) value = double.parse(value);

lib/formatter/order_by.dart

@@ -3,7 +3,30 @@ part of angular.formatter_internal;
 typedef dynamic _Mapper(dynamic e);
 
 /**
- * Orders the provided [Iterable] by the `expression` predicate.
+ * Orders the the elements of a list using a predicate.
+ *
+ * # Usage
+ *
+ *      expression | orderBy: predicate[:true]
+ *
+ * The input to orderBy must be an [Iterable] object. The predicate may be specified as:
+ *
+ * - **a string**: a string containing an expression, such as "user.lastName", used to order the list. The string
+ *   expression can be prefixed to indicate sort order:
+ *    - `+`: sort the elements in asending order. This is the default.
+ *    - `-`: sort the elements in descending order.
+ * - **a custom callable expression**: an expression that will be called to transform the element
+ *   before a sort.
+ * - **a list**: the list may consist of either strings or callable expressions.  A list expression
+ *   indicates a list of fallback expressions to use when a comparision results in the items
+ *   being equal.
+ *
+ * If the expression is explicitly empty(`orderBy:''`), the elements are sorted in
+ * ascending order, using the default comparator, `+`.
+ *
+ * Last, by appending `true`, you can set "descending order" to true, which has the same effect as the `-` comparator.
+ *
+ * # Examples
  *
  * Example 1: Simple array and single/empty expression.
  *
@@ -24,7 +47,7 @@ typedef dynamic _Mapper(dynamic e);
  *     <ul>
  *
  * The empty string expression, `''`, here signifies sorting in ascending order
- * using the default comparator.  Using `'+'` would also work as the `+` prefix
+ * using the default comparator.  Using `'+'` would also work, as the `+` prefix
  * is implied.
  *
  * To sort in descending order, you would use the `'-'` prefix.
@@ -44,7 +67,7 @@ typedef dynamic _Mapper(dynamic e);
  *
  * Example 2: Complex objects, single expression.
  *
- * You may provide a more complex expression to sort non-primitives values or
+ * You may provide a more complex expression to sort non-primitive values or
  * if you want to sort on a decorated/transformed value.
  *
  * e.g. Support you have a list `users` that looks like this:
@@ -60,7 +83,7 @@ typedef dynamic _Mapper(dynamic e);
  * If you want to list the authors sorted by `lastName`, you would use
  *
  *     <li ng-repeat="author in authors | orderBy:'lastName'">
- *       {{author.lastName}}, {{author.firstName
+ *       {{author.lastName}}, {{author.firstName}}
  *     </li>
  *
  * The string expression, `'lastName'`, indicates that the sort should be on the
@@ -135,7 +158,10 @@ class OrderBy implements Function {
   }
 
   /**
-   * expression: String/Function or Array of String/Function.
+   * Order a list by expression.
+   *
+   * - `expression`: String/Function or Array of String/Function.
+   * - `descending`: When specified, use descending order. (The default is ascending order.)
    */
   List call(List items, var expression, [bool descending=false]) {
     if (items == null) {

lib/formatter/stringify.dart

@@ -1,14 +1,14 @@
 part of angular.formatter_internal;
 
 /**
- * Allows you to convert an object to a string.
+ * Converts an object to a string.
  *
- * Null object are converted to an empty string.
+ * Null objects are converted to an empty string.
  *
  *
- * Usage:
+ * # Usage:
  *
- *     {{ expression | stringify }}
+ *     expression | stringify
  */
 @Formatter(name:'stringify')
 class Stringify implements Function {

lib/formatter/uppercase.dart

@@ -1,11 +1,11 @@
 part of angular.formatter_internal;
 
 /**
- * Converts string to uppercase.
+ * Converts a string to uppercase.
  *
- * Usage:
+ * # Usage:
  *
- *     {{ uppercase_expression | uppercase }}
+ *     expression | uppercase
  */
 @Formatter(name:'uppercase')
 class Uppercase implements Function {