angular.formatter: usage examples could be clearer

[radicaled]

The usage example for the Date formatter looks like this:

{{ date_expression | date[:format] }}

I ended up trying the following variations before I had a hunch and tried the AngularJS way of doing it:

date[medium]
date[:medium]
date['medium']
date('medium')
date(:medium)
date(medium)

To contrast, here's how AngularJS shows a usage example:

{{ date_expression | date : format}}

This is much more obvious in my opinion, leaving little room for interpretation.

[technohippy]

[..] is the standard way to show omittable options in the man command so that date[:format] means [:format] can be omitted. I prefer AngularDart style example because AngularJS style example does not tell :format is omittable.

[radicaled]

How many people are going to recognize the relation between shell syntax
and optional parameters for formatters in AngularDart, though? It seems
like an archaic prerequisite to me.

[chalin]

IMHO, what is confusing to most is the use of : to separate the formatter name from its argument. If @vicb's #772 goes through, then the : will be replaced by standard parentheses and then the bracket notation will match with Dart's optional positional argument syntax. In fact, we could then improve the documentation by writing:

{{ date_expression | date([String format="mediumDate"]) }}

[vicb]

Most formatters now have example

 * # 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