docs(forms): additional documentation for $touched vs $pristine states

Author: matsko

docs/content/guide/forms.ngdoc

@@ -62,6 +62,8 @@ To allow styling of form as well as controls, `ngModel`  adds these CSS classes:
 - `ng-invalid`
 - `ng-pristine`
 - `ng-dirty`
+- `ng-touched`
+- `ng-untouched`
 
 The following example uses the CSS to display validity of each form control.
 In the example both `user.name` and `user.email` are required, but are rendered with red background only when they are dirty.

src/ng/directive/input.js

@@ -1638,7 +1638,8 @@ var NgModelController = ['$scope', '$exceptionHandler', '$attrs', '$element', '$
    * Sets the control to its pristine state.
    *
    * This method can be called to remove the 'ng-dirty' class and set the control to its pristine
-   * state (ng-pristine class).
+   * state (ng-pristine class). A model is considered to be pristine when the model has not been changed
+   * from when first compiled within then form.
    */
   this.$setPristine = function () {
     ctrl.$dirty = false;
@@ -1655,7 +1656,9 @@ var NgModelController = ['$scope', '$exceptionHandler', '$attrs', '$element', '$
    * Sets the control to its untouched state.
    *
    * This method can be called to remove the 'ng-touched' class and set the control to its
-   * untouched state (ng-untouched class).
+   * untouched state (ng-untouched class). Upon compilation, a model is set as untouched
+   * by default, however this function can be used to restore that state if the model has
+   * already been touched by the user.
    */
   this.$setUntouched = function() {
     ctrl.$touched = false;
@@ -1671,7 +1674,9 @@ var NgModelController = ['$scope', '$exceptionHandler', '$attrs', '$element', '$
    * Sets the control to its touched state.
    *
    * This method can be called to remove the 'ng-untouched' class and set the control to its
-   * touched state (ng-touched class).
+   * touched state (ng-touched class). A model is considered to be touched when the user has
+   * first interacted (focussed) on the model input element and then shifted focus away (blurred)
+   * from the input element.
    */
   this.$setTouched = function() {
     ctrl.$touched = true;
@@ -1921,8 +1926,8 @@ var NgModelController = ['$scope', '$exceptionHandler', '$attrs', '$element', '$
  * - Binding the view into the model, which other directives such as `input`, `textarea` or `select`
  *   require.
  * - Providing validation behavior (i.e. required, number, email, url).
- * - Keeping the state of the control (valid/invalid, dirty/pristine, validation errors).
- * - Setting related css classes on the element (`ng-valid`, `ng-invalid`, `ng-dirty`, `ng-pristine`) including animations.
+ * - Keeping the state of the control (valid/invalid, dirty/pristine, touched/untouched, validation errors).
+ * - Setting related css classes on the element (`ng-valid`, `ng-invalid`, `ng-dirty`, `ng-pristine`, `ng-touched`, `ng-untouched`) including animations.
  * - Registering the control with its parent {@link ng.directive:form form}.
  *
  * Note: `ngModel` will try to bind to the property given by evaluating the expression on the