docs(ngModelController): improve $parsers/$formatters with example

1 files changed, 14 insertions, 5 deletions

diff --git a/src/ng/directive/input.js b/src/ng/directive/input.js
index fd4ba746..21a46d4d 100644
--- a/src/ng/directive/input.js
+++ b/src/ng/directive/input.js
@@ -793,12 +793,21 @@ var VALID_CLASS = 'ng-valid',
  *
  * @property {string} $viewValue Actual string value in the view.
  * @property {*} $modelValue The value in the model, that the control is bound to.
- * @property {Array.<Function>} $parsers Whenever the control reads value from the DOM, it executes
- *     all of these functions to sanitize / convert the value as well as validate.
- *
- * @property {Array.<Function>} $formatters Whenever the model value changes, it executes all of
- *     these functions to convert the value as well as validate.
+ * @property {Array.<Function>} $parsers Array of functions to execute, as a pipeline, whenever
+ *     the control reads value from the DOM.  Each function is called, in turn, passing the value
+ *     through to the next. Used to sanitize / convert the value as well as validation.
  *
+ * @property {Array.<Function>} $formatters Array of functions to execute, as a pipeline, whenever
+ *     the model value changes. Each function is called, in turn, passing the value through to the
+ *     next. Used to format / convert values for display in the control and validation.
+ *      <pre>
+ *      function formatter(value) {
+ *        if (value) {
+ *          return value.toUpperCase();
+ *        }
+ *      }
+ *      ngModel.$formatters.push(formatter);
+ *      </pre>
  * @property {Object} $error An bject hash with all errors as keys.
  *
  * @property {boolean} $pristine True if user has not interacted with the control yet.