From a0b6f7d45480a931c872b4ec3fcd1c5990e39a29 Mon Sep 17 00:00:00 2001
From: robw <rob.whitehead@gmail.com>
Date: Fri, 11 Dec 2015 14:02:43 -0800
Subject: [PATCH] docs(ngModel): add section explaining ngModel watching by
 reference and not value add section to ngModel docs explaining that for
 objects and collections changing a property doesn't trigger re-rendering.

largely lifted from already-existing section on same topic in ngOptions.

Closes: #13224
---
 src/ng/directive/ngModel.js | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/ng/directive/ngModel.js b/src/ng/directive/ngModel.js
index 0f07da3e6581..3b2f72e8548d 100644
--- a/src/ng/directive/ngModel.js
+++ b/src/ng/directive/ngModel.js
@@ -937,6 +937,21 @@ var NgModelController = ['$scope', '$exceptionHandler', '$attrs', '$element', '$
  *  - {@link ng.directive:select select}
  *  - {@link ng.directive:textarea textarea}
  *
+ * # Complex Models (objects or collections)
+ *
+ * By default, `ngModel` watches the model by reference, not value. This is important to know when
+ * binding elements to models that are objects or collections. If properties of the object or collection
+ * change, the model won't be re-rendered unless the identity of the object is also changed. If the model
+ * is assigned to an entirely new object, its identity will be changed and a re-rendering will trigger.
+ *
+ * The rootScope method `$watchCollection` can be used to watch for changes, but it does a shallow comparison,
+ * meaning that changing properties deeper than the first level of the object (or of the item in the collection
+ * if it's an array) will not trigger a re-rendering of the model.
+ *
+ * Some directives have options that will cause them to use `$watchCollection` - for example, `ngOptions`
+ * will do so when a `track by` clause is included in the comprehension expression or if the select is given
+ * the `multiple` attribute.
+ *
  * # CSS classes
  * The following CSS classes are added and removed on the associated input/select/textarea element
  * depending on the validity of the model.