docs(guide/forms, input): add information how to modify built-in validators

Closes angular#5757
Closes angular#7798

Author: Narretz

docs/content/guide/forms.ngdoc

@@ -365,6 +365,45 @@ In the following example we create two directives:
   </file>
 </example>
 
+# Modifying built-in validators
+
+Since Angular itself uses `$validators`, you can easily replace or remove built-in validators, should you find it necessary. For example, if you think the email regex isn't strict enough, the following example shows you how to override it. Note that you can alternatively use `ng-pattern` to further restrict the validation.
+
+<example module="form-example-modify-validators">
+  <file name="index.html">
+    <form name="form" class="css-form" novalidate>
+      <div>
+        Email:
+        <input type="email" ng-model="myEmail" name="myEmail" />{{myEmail}}<br />
+        <span ng-show="form.myEmail.$error.email">This email format is not supported!</span>
+      </div>
+    </form>
+  </file>
+
+  <file name="script.js">
+    var app = angular.module('form-example-modify-validators', []);
+
+    app.directive('input', function() {
+      var EMAIL_REGEXP = /^[a-z0-9!#$%&'*+/=?^_`{|}~.-]+@[a-z]([a-z0-9-]*[a-z0-9])?(\.[a-z]([a-z0-9-]*[a-z0-9])+)+$/i;
+
+      return {
+        require: 'ngModel',
+        restrict: 'E',
+        link: function(scope, elm, attrs, ctrl) {
+          if (ctrl && attrs.type === 'email') {
+            // only apply the validator if ngModel is present and the input is type email
+
+            // this is the default implementation copied from Angular, which will override the default and use our custom regex
+            ctrl.$validators.email = function(value) {
+              return ctrl.$isEmpty(value) || EMAIL_REGEXP.test(value);
+            };
+          }
+        }
+      };
+    });
+  </file>
+</example>
+
 
 # Implementing custom form controls (using `ngModel`)
 Angular implements all of the basic HTML form controls ({@link ng.directive:input input}, {@link ng.directive:select select}, {@link ng.directive:textarea textarea}), which should be sufficient for most cases.

src/ng/directive/input.js

@@ -650,6 +650,12 @@ var inputType = {
    * Text input with URL validation. Sets the `url` validation error key if the content is not a
    * valid URL.
    *
+   * <div class="alert alert-warning">
+   * **Note:** `input[url]` uses a regex to validate urls that is derived from the regex
+   * used in Chromium. If you need stricter validation, you can use `ng-pattern` or modify
+   * the built-in validators (see the {@link guide/forms Forms guide})
+   * </div>
+   *
    * @param {string} ngModel Assignable angular expression to data-bind to.
    * @param {string=} name Property name of the form under which the control is published.
    * @param {string=} required Sets `required` validation error key if the value is not entered.
@@ -727,6 +733,12 @@ var inputType = {
    * Text input with email validation. Sets the `email` validation error key if not a valid email
    * address.
    *
+   * <div class="alert alert-warning">
+   * **Note:** `input[email]` uses a regex to validate email addresses that is derived from the regex
+   * used in Chromium. If you need stricter validation (e.g. requiring a top-level domain), you can
+   * use `ng-pattern` or modify the built-in validators (see the {@link guide/forms Forms guide})
+   * </div>
+   *
    * @param {string} ngModel Assignable angular expression to data-bind to.
    * @param {string=} name Property name of the form under which the control is published.
    * @param {string=} required Sets `required` validation error key if the value is not entered.