doc($filter): added $filter documentation

10 files changed, 115 insertions, 64 deletions

diff --git a/docs/spec/ngdocSpec.js b/docs/spec/ngdocSpec.js
index bc2bb2ee..effdaa70 100644
--- a/docs/spec/ngdocSpec.js
+++ b/docs/spec/ngdocSpec.js
@@ -547,7 +547,7 @@ describe('ngdoc', function() {
         });
         doc.html_usage_filter(dom);
         expect(dom).toContain('myFilter_expression | myFilter:b');
-        expect(dom).toContain('angular.filter.myFilter(a, b)');
+        expect(dom).toContain('$filter(\'myFilter\')(a, b)');
       });
     });
 
diff --git a/docs/src/ngdoc.js b/docs/src/ngdoc.js
index 7f97b906..6e8d7408 100644
--- a/docs/src/ngdoc.js
+++ b/docs/src/ngdoc.js
@@ -380,9 +380,9 @@ Doc.prototype = {
 
       dom.h('In JavaScript', function() {
         dom.tag('code', function() {
-          dom.text('angular.filter.');
+          dom.text('$filter(\'');
           dom.text(self.shortName);
-          dom.text('(');
+          dom.text('\')(');
           self.parameters(dom, ', ');
           dom.text(')');
         });
diff --git a/src/service/filter.js b/src/service/filter.js
index 9d6a4001..3164b2d4 100644
--- a/src/service/filter.js
+++ b/src/service/filter.js
@@ -1,12 +1,87 @@
 'use strict';
 
+/**
+ * @ngdoc object
+ * @name angular.module.NG.$filterProvider
+ * @description
+ *
+ * Filters are just functions which transform input to an output. However filters need to be Dependency Injected. To
+ * achieve this a filter definition consists of a factory function which is annotated with dependencies and is
+ * responsible for creating a the filter function.
+ *
+ * <pre>
+ *   // Filter registration
+ *   function MyModule($provide, $filterProvider) {
+ *     // create a service to demonstrate injection (not always needed)
+ *     $provide.value('greet', function(name){
+ *       return 'Hello ' + name + '!':
+ *     });
+ *
+ *     // register a filter factory which uses the
+ *     // greet service to demonstrate DI.
+ *     $filterProvider.register('greet', function(greet){
+ *       // return the filter function which uses the greet service
+ *       // to generate salutation
+ *       return function(text) {
+ *         // filters need to be forgiving so check input validity
+ *         return text && greet(text) || text;
+ *       };
+ *     };
+ *   }
+ * </pre>
+ *
+ * The filter function is registered with the `$injector` under the filter name suffixe with `$Filter`.
+ * <pre>
+ *   it('should be the same instance', inject(
+ *     function($filterProvider) {
+ *       $filterProvider.register('reverse', function(){
+ *         return ...;
+ *       });
+ *     },
+ *     function($filter, revers$Filter) {
+ *       expect($filter('reverse')).toBe(reverse$Filter);
+ *     });
+ * </pre>
+ *
+ *
+ * For more information about how angular filters work, and how to create your own filters, see
+ * {@link guide/dev_guide.templates.filters Understanding Angular Filters} in the angular Developer
+ * Guide.
+ */
+/**
+ * @ngdoc method
+ * @name angular.module.NG.$filterProvider#register
+ * @methodOf angular.module.NG.$filterProvider
+ * @description
+ * Register filter factory function.
+ *
+ * @param {String} name Name of the filter.
+ * @param {function} fn The filter factory function which is injectable.
+ */
+
+
+/**
+ * @ngdoc function
+ * @name angular.module.NG.$filter
+ * @function
+ * @description
+ * Filters are used for formatting data displayed to the user.
+ *
+ * The general syntax in templates is as follows:
+ *
+ *         {{ expression | [ filter_name ] }}
+ *
+ * @param {String} name Name of the filter function to retrieve
+ * @return {Function} the filter function
+ */
 $FilterProvider.$inject = ['$provide'];
 function $FilterProvider($provide) {
   var suffix = '$Filter';
 
-  $provide.filter = function(name, factory) {
+  function register(name, factory) {
     return $provide.factory(name + suffix, factory);
   };
+  this.register = register;
 
   this.$get = ['$injector', function($injector) {
     return function(name) {
@@ -16,15 +91,15 @@ function $FilterProvider($provide) {
 
   ////////////////////////////////////////
 
-  $provide.filter('currency', currencyFilter);
-  $provide.filter('date', dateFilter);
-  $provide.filter('filter', filterFilter);
-  $provide.filter('html', htmlFilter);
-  $provide.filter('json', jsonFilter);
-  $provide.filter('limitTo', limitToFilter);
-  $provide.filter('linky', linkyFilter);
-  $provide.filter('lowercase', lowercaseFilter);
-  $provide.filter('number', numberFilter);
-  $provide.filter('orderBy', orderByFilter);
-  $provide.filter('uppercase', uppercaseFilter);
+  register('currency', currencyFilter);
+  register('date', dateFilter);
+  register('filter', filterFilter);
+  register('html', htmlFilter);
+  register('json', jsonFilter);
+  register('limitTo', limitToFilter);
+  register('linky', linkyFilter);
+  register('lowercase', lowercaseFilter);
+  register('number', numberFilter);
+  register('orderBy', orderByFilter);
+  register('uppercase', uppercaseFilter);
 }
diff --git a/src/service/filter/filter.js b/src/service/filter/filter.js
index 05ae6bfa..7efd6618 100644
--- a/src/service/filter/filter.js
+++ b/src/service/filter/filter.js
@@ -1,8 +1,8 @@
 'use strict';
 
 /**
- * @ngdoc function
- * @name angular.service.filter.filter
+ * @ngdoc filter
+ * @name angular.module.NG.$filter.filter
  * @function
  *
  * @description
diff --git a/src/service/filter/filters.js b/src/service/filter/filters.js
index 1034896b..95844da3 100644
--- a/src/service/filter/filters.js
+++ b/src/service/filter/filters.js
@@ -1,35 +1,8 @@
 'use strict';
 
 /**
- * @ngdoc overview
- * @name angular.filter
- * @description
- *
- * Filters are used for formatting data displayed to the user.
- *
- * The general syntax in templates is as follows:
- *
- *         {{ expression | [ filter_name ] }}
- *
- * Following is the list of built-in angular filters:
- *
- * * {@link angular.filter.currency currency}
- * * {@link angular.filter.date date}
- * * {@link angular.filter.html html}
- * * {@link angular.filter.json json}
- * * {@link angular.filter.linky linky}
- * * {@link angular.filter.lowercase lowercase}
- * * {@link angular.filter.number number}
- * * {@link angular.filter.uppercase uppercase}
- *
- * For more information about how angular filters work, and how to create your own filters, see
- * {@link guide/dev_guide.templates.filters Understanding Angular Filters} in the angular Developer
- * Guide.
- */
-
-/**
  * @ngdoc filter
- * @name angular.filter.currency
+ * @name angular.module.NG.$filter.currency
  * @function
  *
  * @description
@@ -80,7 +53,7 @@ function currencyFilter($locale) {
 
 /**
  * @ngdoc filter
- * @name angular.filter.number
+ * @name angular.module.NG.$filter.number
  * @function
  *
  * @description
@@ -266,7 +239,7 @@ var DATE_FORMATS_SPLIT = /((?:[^yMdHhmsaZE']+)|(?:'(?:[^']|'')*')|(?:E+|y+|M+|d+
 
 /**
  * @ngdoc filter
- * @name angular.filter.date
+ * @name angular.module.NG.$filter.date
  * @function
  *
  * @description
@@ -391,7 +364,7 @@ function dateFilter($locale) {
 
 /**
  * @ngdoc filter
- * @name angular.filter.json
+ * @name angular.module.NG.$filter.json
  * @function
  *
  * @description
@@ -427,9 +400,10 @@ function jsonFilter() {
 
 /**
  * @ngdoc filter
- * @name angular.filter.lowercase
+ * @name angular.module.NG.$filter.lowercase
  * @function
- *
+ * @description
+ * Converts string to lowercase.
  * @see angular.lowercase
  */
 var lowercaseFilter = valueFn(lowercase);
@@ -437,9 +411,10 @@ var lowercaseFilter = valueFn(lowercase);
 
 /**
  * @ngdoc filter
- * @name angular.filter.uppercase
+ * @name angular.module.NG.$filter.uppercase
  * @function
- *
+ * @description
+ * Converts string to uppercase.
  * @see angular.uppercase
  */
 var uppercaseFilter = valueFn(uppercase);
@@ -447,7 +422,7 @@ var uppercaseFilter = valueFn(uppercase);
 
 /**
  * @ngdoc filter
- * @name angular.filter.html
+ * @name angular.module.NG.$filter.html
  * @function
  *
  * @description
@@ -539,6 +514,7 @@ var uppercaseFilter = valueFn(uppercase);
      </doc:scenario>
    </doc:example>
  */
+//TODO(misko): turn sensitization into injectable service
 function htmlFilter() {
   return function(html, option){
     return new HTML(html, option);
@@ -548,7 +524,7 @@ function htmlFilter() {
 
 /**
  * @ngdoc filter
- * @name angular.filter.linky
+ * @name angular.module.NG.$filter.linky
  * @function
  *
  * @description
diff --git a/src/service/filter/limitTo.js b/src/service/filter/limitTo.js
index 219322f4..ca1f49cb 100644
--- a/src/service/filter/limitTo.js
+++ b/src/service/filter/limitTo.js
@@ -2,7 +2,7 @@
 
 /**
  * @ngdoc function
- * @name angular.service.filter.limitTo
+ * @name angular.module.NG.$filter.limitTo
  * @function
  *
  * @description
diff --git a/src/service/filter/orderBy.js b/src/service/filter/orderBy.js
index 08b86743..abbffef7 100644
--- a/src/service/filter/orderBy.js
+++ b/src/service/filter/orderBy.js
@@ -2,7 +2,7 @@
 
 /**
  * @ngdoc function
- * @name angular.Array.orderBy
+ * @name angular.module.NG.$filter.orderBy
  * @function
  *
  * @description
diff --git a/test/directivesSpec.js b/test/directivesSpec.js
index 51cc5489..3ca60ae4 100644
--- a/test/directivesSpec.js
+++ b/test/directivesSpec.js
@@ -41,8 +41,8 @@ describe("directive", function() {
       expect(lowercase(element.html())).toEqual('<div onclick="">hello</div>');
     }));
 
-    it('should set element element', inject(function($rootScope, $compile, $provide) {
-      $provide.filter('myElement', valueFn(function() {
+    it('should set element element', inject(function($rootScope, $compile, $filterProvider) {
+      $filterProvider.register('myElement', valueFn(function() {
         return jqLite('<a>hello</a>');
       }));
       var element = $compile('<div ng:bind="0|myElement"></div>')($rootScope);
@@ -73,9 +73,9 @@ describe("directive", function() {
       expect(element.text()).toEqual('Hello Misko!');
     }));
 
-    it('should have $element set to current bind element', inject(function($rootScope, $compile, $provide) {
+    it('should have $element set to current bind element', inject(function($rootScope, $compile, $filterProvider) {
       var innerText;
-      $provide.filter('myFilter', valueFn(function(text) {
+      $filterProvider.register('myFilter', valueFn(function(text) {
         innerText = innerText || this.$element.text();
         return text;
       }));
diff --git a/test/service/filter/filtersSpec.js b/test/service/filter/filtersSpec.js
index 8d05d951..275dbab4 100644
--- a/test/service/filter/filtersSpec.js
+++ b/test/service/filter/filtersSpec.js
@@ -8,9 +8,9 @@ describe('filters', function() {
     filter = $filter;
   }));
 
-  it('should called the filter when evaluating expression', inject(function($rootScope, $provide) {
+  it('should called the filter when evaluating expression', inject(function($rootScope, $filterProvider) {
     var filter = jasmine.createSpy('myFilter');
-    $provide.filter('myFilter', valueFn(filter));
+    $filterProvider.register('myFilter', valueFn(filter));
 
     $rootScope.$eval('10|myFilter');
     expect(filter).toHaveBeenCalledWith(10);
diff --git a/test/service/parseSpec.js b/test/service/parseSpec.js
index 506d3373..2742f381 100644
--- a/test/service/parseSpec.js
+++ b/test/service/parseSpec.js
@@ -191,8 +191,8 @@ describe('parser', function() {
     expect(scope.$eval("'a' + 'b c'")).toEqual("ab c");
   });
 
-  it('should parse filters', inject(function($provide) {
-    $provide.filter('substring', valueFn(function(input, start, end) {
+  it('should parse filters', inject(function($filterProvider) {
+    $filterProvider.register('substring', valueFn(function(input, start, end) {
       return input.substring(start, end);
     }));