diff --git a/lib/core/annotation_src.dart b/lib/core/annotation_src.dart index 643339ca9..98664729a 100644 --- a/lib/core/annotation_src.dart +++ b/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: * diff --git a/lib/formatter/currency.dart b/lib/formatter/currency.dart index b96124b4e..a5829b304 100644 --- a/lib/formatter/currency.dart +++ b/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(); /** - * [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); diff --git a/lib/formatter/date.dart b/lib/formatter/date.dart index 0268b468d..372217f04 100644 --- a/lib/formatter/date.dart +++ b/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>(); /** - * [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']) { diff --git a/lib/formatter/filter.dart b/lib/formatter/filter.dart index cf565da7b..e34798c4c 100644 --- a/lib/formatter/filter.dart +++ b/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) + *
* - *
+ * 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`. * - *
* - * # 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. * - *
* * # Example ([view in plunker](http://plnkr.co/edit/6Mxz6r?p=info)): * diff --git a/lib/formatter/module.dart b/lib/formatter/module.dart index ea84d0231..478c7844d 100644 --- a/lib/formatter/module.dart +++ b/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.