docs(forms): add inline docs why ngModel runs a 2nd change detectio…

…n run (angular#12821)

Related to angular#11895

modules/@angular/forms/src/directives/ng_model.ts

@@ -27,6 +27,23 @@ export const formControlBinding: any = {
   useExisting: forwardRef(() => NgModel)
 };
 
+/**
+ * `ngModel` forces an additional change detection run when its inputs change:
+ * E.g.:
+ * ```
+ * <div>{{myModel.valid}}</div>
+ * <input [(ngModel)]="myValue" #myModel="ngModel">
+ * ```
+ * I.e. `ngModel` can export itself on the element and then be used in the template.
+ * Normally, this would result in expressions before the `input` that use the exported directive
+ * to have and old value as they have been
+ * dirty checked before. As this is a very common case for `ngModel`, we added this second change
+ * detection run.
+ *
+ * Notes:
+ * - this is just one extra run no matter how many `ngModel` have been changed.
+ * - this is a general problem when using `exportAs` for directives!
+ */
 const resolvedPromise = Promise.resolve(null);
 
 /**