docs: edit formatter docs

Author: naomiblack

lib/formatter/json.dart

@@ -1,8 +1,9 @@
 part of angular.formatter_internal;
 
 /**
- * Allows you to convert a JavaScript object into JSON string. This formatter is
- * mostly useful for debugging.
+ * Converts a JavaScript object into a JSON string.
+ *
+ * This formatter is mostly useful for debugging.
  *
  * Usage:
  *

lib/formatter/limit_to.dart

@@ -2,20 +2,28 @@ 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.
+ *
+ * The number of elements to return is specified by the `limitTo` parameter.
+ *
+ * Usage:
+ *
+ *     {{ expression | limitTo:_value_ }}
  *
- * When operating on a List, the returned list is always a copy even when all
- * the elements are being returned.
  *
- * 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.
+ *     <div ng-repeat="item in expression | limitTo:_value_">{{item}}</div>
  *
- * 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.
+ *
+ * Where the input expression is a [List] or [String], and `limitTo` evaluates to:
+ *
+ * - **a positive integer**: return _value_ items from the beginning of the list or string
+ * expression.
+ * - **a negative integer**: return _value_ items from the end of the list or string expression.
+ * - **null or non-integer**: return an empty list or string.
+ * - **`|limitTo|` greater than the size of the expression**: return the entire expression.
+ *
+ * When operating on a [List], the returned list is always a copy even when all
+ * the elements are being returned.
  *
  * Example:
  *
@@ -29,7 +37,7 @@ part of angular.formatter_internal;
  *
  *     <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,7 +1,7 @@
 part of angular.formatter_internal;
 
 /**
- * Converts string to lowercase.
+ * Converts a string to lowercase.
  *
  * Usage:
  *

lib/formatter/number.dart

@@ -3,7 +3,7 @@ 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:
@@ -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,32 @@ part of angular.formatter_internal;
 typedef dynamic _Mapper(dynamic e);
 
 /**
- * Orders the provided [Iterable] by the `expression` predicate.
+ * Orders the the elements of an object by a predicate expression.
+ *
+ * Usage:
+ *
+ *      <div ng-repeat="item in items | orderBy: [+/-]_expression_[:true]">
+ *
+ *
+ * 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 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.
+ *
+ * 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 +49,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 +69,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:
@@ -135,7 +160,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,9 +1,9 @@
 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:

lib/formatter/uppercase.dart

@@ -1,7 +1,7 @@
 part of angular.formatter_internal;
 
 /**
- * Converts string to uppercase.
+ * Converts a string to uppercase.
  *
  * Usage:
  *