docs(ngModelOptions): add some docs for $cancelUpdate

Author: shahata

src/ng/directive/input.js

@@ -2214,6 +2214,15 @@ var ngValueDirective = function() {
  * events that will trigger a model update and/or a debouncing delay so that the actual update only
  * takes place when a timer expires; this timer will be reset after another change takes place.
  *
+ * Given the nature of `ngModelOptions`, the value displayed inside input fields in the view might
+ * be different then the value in the actual model. This means that if you update the model you
+ * should also invoke `$cancelUpdate` on the relevant input field in order to make sure it is
+ * synchronized with the model and that any debounced action is canceled.
+ *
+ * The easiest way to reference the control's `$cancelUpdate` method is by making sure the input
+ * is placed inside a form that has a `name` attribute. This is important because form controllers
+ * are published to the related scope under the name in their `name` attribute.
+ *
  * @param {Object} ngModelOptions options to apply to the current model. Valid keys are:
  *   - `updateOn`: string specifying which event should be the input bound to. You can set several
  *     events using an space delimited list. There is a special event called `default` that
@@ -2226,49 +2235,72 @@ var ngValueDirective = function() {
  * @example
 
   The following example shows how to override immediate updates. Changes on the inputs within the
-  form will update the model only when the control loses focus (blur event).
+  form will update the model only when the control loses focus (blur event). If `escape` key is
+  pressed while the input field is focused, the value is reset to the value in the current model.
 
   <example name="ngModelOptions-directive-blur">
     <file name="index.html">
       <div ng-controller="Ctrl">
-        Name:
-        <input type="text"
-               ng-model="user.name"
-               ng-model-options="{ updateOn: 'blur' }" /><br />
-
-        Other data:
-        <input type="text" ng-model="user.data" /><br />
-
+        <form name="userForm">
+          Name:
+          <input type="text" name="userName"
+                 ng-model="user.name"
+                 ng-model-options="{ updateOn: 'blur' }"
+                 ng-keyup="cancel($event)" /><br />
+
+          Other data:
+          <input type="text" ng-model="user.data" /><br />
+        </form>
         <pre>user.name = <span ng-bind="user.name"></span></pre>
       </div>
     </file>
     <file name="app.js">
       function Ctrl($scope) {
-       $scope.user = { name: 'say', data: '' };
+        $scope.user = { name: 'say', data: '' };
+
+        $scope.cancel = function (e) {
+          if (e.keyCode == 27) {
+            $scope.userForm.userName.$cancelUpdate();
+          }
+        };
       }
     </file>
     <file name="protractor.js" type="protractor">
       var model = element(by.binding('user.name'));
       var input = element(by.model('user.name'));
       var other = element(by.model('user.data'));
+
       it('should allow custom events', function() {
         input.sendKeys(' hello');
         expect(model.getText()).toEqual('say');
         other.click();
         expect(model.getText()).toEqual('say hello');
       });
+
+      it('should $cancelUpdate when model changes', function() {
+        input.sendKeys(' hello');
+        expect(input.getAttribute('value')).toEqual('say hello');
+        input.sendKeys(protractor.Key.ESCAPE);
+        expect(input.getAttribute('value')).toEqual('say');
+        other.click();
+        expect(model.getText()).toEqual('say');
+      });
     </file>
   </example>
 
-  This one shows how to debounce model changes. Model will be updated only 500 milliseconds after last change.
+  This one shows how to debounce model changes. Model will be updated only 1 sec after last change.
+  If the `Clear` button is pressed, any debounced action is canceled and the value becomes empty.
 
   <example name="ngModelOptions-directive-debounce">
     <file name="index.html">
       <div ng-controller="Ctrl">
-        Name:
-        <input type="text"
-               ng-model="user.name"
-               ng-model-options="{ debounce: 500 }" /><br />
+        <form name="userForm">
+          Name:
+          <input type="text" name="userName"
+                 ng-model="user.name"
+                 ng-model-options="{ debounce: 1000 }" />
+          <button ng-click="userForm.userName.$cancelUpdate(); user.name=''">Clear</button><br />
+        </form>
         <pre>user.name = <span ng-bind="user.name"></span></pre>
       </div>
     </file>