docs(formatter): fix and edit per comments on 0e0f8d6

Closes #1036

Author: naomiblack

lib/core/annotation_src.dart

@@ -547,13 +547,16 @@ abstract class DetachAware {
 }
 
 /**
- * Use the @[Formatter] class annotation to register a new formatter.
+ * Use the @[Formatter] class annotation to identify a class as a 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:
+ * 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,9 +7,16 @@ part of angular.formatter_internal;
  * see the [angular:formatter](#angular-formatter) library.
  *
  *
- * Usage:
+ * # Usage
+ *
+ *     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
  *
- *     {{ numeric_expression | currency[:symbol[:leading]] }}
  *
  */
 @Formatter(name:'currency')
@@ -22,8 +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`: when set to false, places the symbol after the number instead of before
-   *  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:

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,13 +1,18 @@
 part of angular.formatter_internal;
 
 /**
- * Converts a JavaScript object into a JSON string.
+ * Converts an object into a JSON string.
  *
  * This formatter is mostly useful for debugging.
  *
- * Usage:
+ * Note that the object to convert must be directly encodable to JSON (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.
  *
- *     {{ json_expression | json }}
+ * # Usage
+ *
+ *     json_expression | json
  */
 @Formatter(name:'json')
 class Json implements Function {

lib/formatter/limit_to.dart

@@ -6,13 +6,9 @@ part of angular.formatter_internal;
  *
  * The number of elements to return is specified by the `limitTo` parameter.
  *
- * Usage:
- *
- *     {{ expression | limitTo:_number_ }}
- *
- *
- *     <div ng-repeat="item in expression | limitTo:_number_">{{item}}</div>
+ * # Usage
  *
+ *     expression | limitTo:number
  *
  * Where the input expression is a [List] or [String], and `limitTo` is:
  *
@@ -25,15 +21,14 @@ part of angular.formatter_internal;
  * 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>
  *

lib/formatter/lowercase.dart

@@ -3,9 +3,9 @@ part of angular.formatter_internal;
 /**
  * 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

@@ -6,9 +6,9 @@ part of angular.formatter_internal;
  * If the input is not a number, an empty string is returned.
  *
  *
- * Usage:
+ * # Usage
  *
- *     {{ number_expression | number[:fractionSize] }}
+ *     expression | number[:fractionSize]
  *
  */
 @Formatter(name:'number')
@@ -22,7 +22,7 @@ class Number {
    * - `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
+   * 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.
    *
    */

lib/formatter/order_by.dart

@@ -3,30 +3,31 @@ part of angular.formatter_internal;
 typedef dynamic _Mapper(dynamic e);
 
 /**
- * Orders the the elements of an object by a predicate expression.
+ * Orders the the elements of a list using a predicate.
  *
- * Usage:
+ * # Usage
  *
- *      <div ng-repeat="item in items | orderBy: [+/-]_expression_[:true]">
+ *      expression | orderBy: predicate[:true]
  *
+ * The input to orderBy must be an [Iterable] object. The predicate may be specified as:
  *
- * The input must be an [Iterable] object. The expression may be specified as:
- *
- * - `+`: sort the elements in asending order. This is the default comparator.
- * - `-`: sort the elements in descending order.
- * - **a string expression**: sort on a decorated/transformed value, such as "lastName",
- *    or to sort non-primitives values.
+ * - **a string**: a string containing an expression, such as "user.lastName", used to order the list.
  * - **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 string or callable expressions.  A list expression
- * indicates a list of fallback expressions to use when a comparision results in the items
- * being equal.
+ *   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
+ * 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.
+ * A string expression in the predicate can be prefixed to indicate sort order:
+ *
+ * - `+`: sort the elements in asending order. This is the default.
+ * - `-`: sort the elements in descending order.
+ *
+ * Alternately, by appending `true`, you can set "descending order" to true, which has the same effect as the `-`
+ * prefix.
  *
  * # Examples
  *
@@ -85,7 +86,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

lib/formatter/stringify.dart

@@ -6,9 +6,9 @@ part of angular.formatter_internal;
  * 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

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

test/angular_spec.dart

@@ -213,6 +213,7 @@ main() {
         "angular.formatter_internal.Currency",
         "angular.formatter_internal.Date",
         "angular.formatter_internal.Filter",
+        "angular.formatter_internal.FormatterModule",
         "angular.formatter_internal.Json",
         "angular.formatter_internal.LimitTo",
         "angular.formatter_internal.Lowercase",