add docs

src/ng/directive/ngModel.js

@@ -880,6 +880,24 @@ NgModelController.prototype = {
     this.$options = this.$options.createChild(options);
   },
 
+  /**
+   * @ngdoc method
+   *
+   * @name  ngModel.ngModelController#$format
+   *
+   * @description
+   *
+   * Run the ngModel.$formatters on the current $modelValue and
+   * set the result to the $viewValue.
+   *
+   * This method also sets the `ng-empty` or `ng-not-empty`
+   * class based on the on the $viewValue.
+   *
+   * Note that `$render()` must be called to update the DOM
+   * of the control with the new $viewValue.
+   *
+   * @return {mixed} The formatted value.
+   */
   $format: function() {
     var formatters = this.$formatters,
         idx = formatters.length;
@@ -891,12 +909,50 @@ NgModelController.prototype = {
 
     if (this.$viewValue !== viewValue) {
       this.$$updateEmptyClasses(viewValue);
-      this.$viewValue = this.$lastCommittedViewValue = viewValue;
+      this.$viewValue = this.$$lastCommittedViewValue = viewValue;
     }
 
     return viewValue;
   },
 
+  /**
+   * @ngdoc method
+   *
+   * @name  ngModel.ngModelController#$setModelValue
+   *
+   * @param {*} modelValue value from the model.
+   *
+   * @description
+   *
+   * Runs the whole model -> view pipeline on the modelValue passed to the
+   * function.
+   *
+   * The modelValue argument should be the same value that is currently set on
+   * the scope.
+   *
+   * The following actions are performed by this method:
+   *
+   * - the $modelValue is set
+   * - the $modelValue is formatted and the result is set to $viewValue
+   * - `ng-empty` / `ng-not-empty` is set on the element
+   * - if the $viewValue has changed
+   *   - $render() is called on the control
+   *   - the `$validators` are run and the validation status is set
+   *
+   * This method is called by ngModel internally when the bound scope value changes.
+   * Application developers usually do not have to call this function themselves.
+   *
+   * This function can be used when the $viewValue or the rendered DOM value of the control should
+   * be updated after a user input.
+   * For example, consider a text input with an autocomplete list for countries.
+   * A user enters `ge` and then selects `Germany` from the list.
+   * Based on this, the autocomplete widget will call $setViewValue({label: 'Germany', id: 'de'}),
+   * but the rendered value will still be `ge`.
+   * The widget can then call ctrl.$setModelValue(ctrl.$modelValue) to run the model -> view
+   * pipeline again, which includes a formatter that converts the object into the string `Germany`
+   * which is set to the $viewValue and rendered in the DOM.
+   *
+   */
   $setModelValue: function(modelValue) {
     this.$modelValue = this.$$rawModelValue = modelValue;
     this.$$parserValid = undefined;