improve jsdocs

- improve json filter example
- improve filter overview doc
- improving validator overview jsdocs
- simplify number filter examples and make them live + add specs
- various doc fixes

Author: IgorMinar

src/Angular.js

@@ -167,10 +167,22 @@ var _undefined        = undefined,
      * 
      * <doc:example>
      *   <doc:source>
-     *    Change me: &lt;input type="text" name="number" ng:validate="integer" value="123"&gt;
+     *     Change me: &lt;input type="text" name="number" ng:validate="integer" value="123"&gt;
      *   </doc:source>
+     *   <doc:scenario>
+     *     it('should validate the default number string', function() {
+     *       expect(element('input[name=number]').attr('class')).
+     *          not().toMatch(/ng-validation-error/);
+     *     });
+     *     it('should not validate "foo"', function() {
+     *       input('number').enter('foo');
+     *       expect(element('input[name=number]').attr('class')).
+     *          toMatch(/ng-validation-error/);
+     *     });
+     *   </doc:scenario>
      * </doc:example>
      * 
+     *
      * # Writing your own Validators
      * Writing your own validator is easy. To make a function available as a 
      * validator, just define the JavaScript function on the `angular.validator` 
@@ -187,13 +199,10 @@ var _undefined        = undefined,
      * In this example we have written a upsTrackingNo validator. 
      * It marks the input text "valid" only when the user enters a well-formed 
      * UPS tracking number.
-     * 
-     * <pre>
-     * angular.validator('upsTrackingNo', function(input, format) {
-     *  var regexp = new RegExp("^" + format.replace(/9/g, '\\d') + "$");
-     *  return input.match(regexp) ? "" : "The format must match " + format;
-     * });
-     * </pre>
+     *
+     * @css ng-validation-error
+     *   When validation fails, this css class is applied to the binding, making its borders red by
+     *   default.
      * 
      * @example
      * <script>
@@ -205,7 +214,19 @@ var _undefined        = undefined,
      * <input type="text" name="trackNo" size="40"
      *       ng:validate="upsTrackingNo:'1Z 999 999 99 9999 999 9'" 
      *       value="1Z 123 456 78 9012 345 6"/>
-     * 
+     *
+     * @scenario
+     * it('should validate correct UPS tracking number', function() {
+     *   expect(element('input[name=trackNo]').attr('class')).
+     *      not().toMatch(/ng-validation-error/);
+     * });
+     *
+     * it('should not validate in correct UPS tracking number', function() {
+     *   input('trackNo').enter('foo');
+     *   expect(element('input[name=trackNo]').attr('class')).
+     *      toMatch(/ng-validation-error/);
+     * });
+     *
      */
     angularValidator  = extensionMap(angular, 'validator'),
 
@@ -278,10 +299,12 @@ var _undefined        = undefined,
              return out;
            });
          </script>
-         <span ng:non-bindable="true">{{"hello"|reverse}}</span>: {{"hello"|reverse}}<br>
-         <span ng:non-bindable="true">{{"hello"|reverse:true}}</span>: {{"hello"|reverse:true}}<br>
-         <span ng:non-bindable="true">{{"hello"|reverse:true:"blue"}}</span>:
-           {{"hello"|reverse:true:"blue"}}
+
+         <input name="text" type="text" value="hello" /><br>
+         No filter: {{text}}<br>
+         Reverse: {{text|reverse}}<br>
+         Reverse + uppercase: {{text|reverse:true}}<br>
+         Reverse + uppercase + blue:  {{text|reverse:true:"blue"}}
 
      */
     angularFilter     = extensionMap(angular, 'filter'),
@@ -324,7 +347,7 @@ var _undefined        = undefined,
      * </pre>
      * 
      * @example
-     * <script>
+     * <script type="text/javascript">
      * function reverse(text) {
      *   var reversed = [];
      *   for (var i = 0; i < text.length; i++) {

src/filters.js

@@ -23,8 +23,8 @@
      it('should update', function(){
        input('amount').enter('-1234');
        expect(binding('amount | currency')).toBe('$-1,234.00');
-       // TODO: implement
-       // expect(binding('amount')).toHaveColor('red'); //what about toHaveCssClass instead?
+       expect(element('span[ng\\:bind="amount | currency"]').attr('class')).
+          toMatch(/ng-format-negative/);
      });
  */
 angularFilter.currency = function(amount){
@@ -47,17 +47,23 @@ angularFilter.currency = function(amount){
  * @returns {string} Number rounded to decimalPlaces and places a “,” after each third digit.
  *
  * @example
-     <span ng:non-bindable>{{1234.56789 | number}}</span>: {{1234.56789 | number}}<br/>
-     <span ng:non-bindable>{{1234.56789 | number:0}}</span>: {{1234.56789 | number:0}}<br/>
-     <span ng:non-bindable>{{1234.56789 | number:2}}</span>: {{1234.56789 | number:2}}<br/>
-     <span ng:non-bindable>{{-1234.56789 | number:4}}</span>: {{-1234.56789 | number:4}}
- *
+     Enter number: <input name='val' value='1234.56789' /><br/>
+     Default formatting: {{val | number}}<br/>
+     No fractions: {{val | number:0}}<br/>
+     Negative number: {{-val | number:4}}
+
  * @scenario
      it('should format numbers', function(){
-       expect(binding('1234.56789 | number')).toBe('1,234.57');
-       expect(binding('1234.56789 | number:0')).toBe('1,235');
-       expect(binding('1234.56789 | number:2')).toBe('1,234.57');
-       expect(binding('-1234.56789 | number:4')).toBe('-1,234.5679');
+       expect(binding('val | number')).toBe('1,234.57');
+       expect(binding('val | number:0')).toBe('1,235');
+       expect(binding('-val | number:4')).toBe('-1,234.5679');
+     });
+
+     it('should update', function(){
+       input('val').enter('3374.333');
+       expect(binding('val | number')).toBe('3,374.33');
+       expect(binding('val | number:0')).toBe('3,374');
+       expect(binding('-val | number:4')).toBe('-3,374.3330');
      });
  */
 angularFilter.number = function(number, fractionSize){
@@ -238,12 +244,19 @@ angularFilter.date = function(date, format) {
  *
  * @css ng-monospace Always applied to the encapsulating element.
  *
- * @example
-     <span ng:non-bindable>{{ {a:1, b:[]} | json }}</span>: <pre>{{ {a:1, b:[]} | json }}</pre>
+ * @example:
+     <input type="text" name="objTxt" value="{a:1, b:[]}"
+            ng:eval="obj = $eval(objTxt)"/>
+     <pre>{{ obj | json }}</pre>
  *
  * @scenario
      it('should jsonify filtered objects', function() {
-       expect(binding('{{ {a:1, b:[]} | json')).toBe('{\n  "a":1,\n  "b":[]}');
+       expect(binding('obj | json')).toBe('{\n  "a":1,\n  "b":[]}');
+     });
+
+     it('should update', function() {
+       input('objTxt').enter('[1, 2, 3]');
+       expect(binding('obj | json')).toBe('[1,2,3]');
      });
  *
  */
@@ -401,8 +414,8 @@ and one more: ftp://127.0.0.1/.</textarea>
          <td><div ng:bind="snippet"></div></td>
        </tr>
      </table>
- *
- * @scenario
+
+   @scenario
      it('should linkify the snippet with urls', function(){
        expect(using('#linky-filter').binding('snippet | linky')).
          toBe('Pretty text with some links:\n' +

src/validators.js

@@ -321,16 +321,6 @@ extend(angularValidator, {
    * 
    * @css ng-input-indicator-wait, ng-validation-error
    * 
-   * @exampleDescription
-   * <pre>
-   * function myValidator (inputToValidate, validationDone) {
-   *  // simulate delayed response, validate on even input length
-   *  setTimeout(function(){
-   *    validationDone(inputToValidate.length % 2);
-   *  }, 500);
-   * };
-   * </pre>
-   * 
    * @example
    * <script>
    *   function myValidator(inputToValidate, validationDone) {