doc($filter): added $filter documentation

5 files changed, 104 insertions, 53 deletions

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