remove shallow watch, update docs

Author: Narretz

src/ng/compile.js

@@ -186,28 +186,30 @@
  *   you want to shallow watch for changes (i.e. $watchCollection instead of $watch) you can use
  *   `=*` or `=*attr` (`=*?` or `=*?attr` if the property is optional).
  *
- * * `<` or `<attr` - set up one-way (one-directional) binding between a local scope property and the
- *   parent scope property of name defined via the value of the `attr` attribute. If no `attr`
- *   name is specified then the attribute name is assumed to be the same as the local name.
- *   Given `<dir my-attr="parentModel">` and directive definition of
- *   `scope: { localModel:'<myAttr' }`, then isolate scope property `localModel` will reflect the
+ * * `<` or `<attr` - set up a one-way (one-directional) binding between a local scope property and an
+ *   expression passed via the attribute `attr`. The expression is evaluated in the context of the
+ *   parent scope. If no `attr` name is specified then the attribute name is assumed to be the same as the
+ *   local name. You can also make the binding optional by adding `?`: `<?` or `<?attr`.
+ *
+ *   For example, given `<dir my-attr="parentModel">` and directive definition of
+ *   `scope: { localModel:'<myAttr' }`, then the isolated scope property `localModel` will reflect the
  *   value of `parentModel` on the parent scope. Any changes to `parentModel` will be reflected
  *   in `localModel`, but changes in `localModel` will not reflect in `parentModel`. There are however
  *   two caveats:
  *     1. one-way binding does not copy the value from the parent to the isolate scope, it simply
  *     sets the same value. That means if your bound value is an object, changes to its properties
- *     in the isolate scope will be reflected in the parent scope.
- *     2. one-way binding watches changes to the **identity** of the parent value. That is important should
- *     you one-way bind an object, and then replace that object in the isolated scope. If you now change
- *     a property of the object in your parent scope, the change will not be propagated to the isolated
- *     scope, because the identity of the object has not changed. Instead you must assign a new object.
+ *     in the isolated scope will be reflected in the parent scope (because both reference the same object).
+ *     2. one-way binding watches changes to the **identity** of the parent value. That means the
+ *     {@link ng.$rootScope.Scope#$watch`$watch`} on the parent value only fires if the reference
+ *     to the value has changed. In most cases, this should not be of concern, but can be important
+ *     to know if you one-way bind to an object, and then replace that object in the isolated scope.
+ *     If you now change a property of the object in
+ *     your parent scope, the change will not be propagated to the isolated scope, because the identity
+ *     of the object has not changed. Instead you must assign a new object.
  *
  *   One-way binding is useful if you do not plan to propagate changes to your isolated scope bindings
  *   back to the parent. However, it does not make this completely impossible.
  *
- *   Same as with bi-directional bindings, you can also use shallow watch for changes (i.e. $watchCollection instead of $watch):
- *   `<*` or `<*attr` (`<*?` or `<*?attr` if the property is optional).
- *
  * * `&` or `&attr` - provides a way to execute an expression in the context of the parent scope.
  *   If no `attr` name is specified then the attribute name is assumed to be the same as the
  *   local name. Given `<widget my-attr="count = count + value">` and widget definition of
@@ -848,7 +850,7 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
   var EVENT_HANDLER_ATTR_REGEXP = /^(on[a-z]+|formaction)$/;
 
   function parseIsolateBindings(scope, directiveName, isController) {
-    var LOCAL_REGEXP = /^\s*([@&]|[=<](\*?))(\??)\s*(\w*)\s*$/;
+    var LOCAL_REGEXP = /^\s*([@&<]|=(\*?))(\??)\s*(\w*)\s*$/;
 
     var bindings = {};
 
@@ -3064,15 +3066,10 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
 
             destination[scopeName] = parentGet(scope);
 
-            if (definition.collection) {
-              removeWatch = scope.$watchCollection(parentGet, function parentCollectionValueWatchAction(newParentValue) {
-                destination[scopeName] = newParentValue;
-              });
-            } else {
-              removeWatch = scope.$watch(parentGet, function parentValueWatchAction(newParentValue) {
-                destination[scopeName] = newParentValue;
-              }, parentGet.literal);
-            }
+            removeWatch = scope.$watch(parentGet, function parentValueWatchAction(newParentValue) {
+              destination[scopeName] = newParentValue;
+            }, parentGet.literal);
+
             removeWatchCollection.push(removeWatch);
             break;
 

test/ng/compileSpec.js

@@ -3537,8 +3537,6 @@ describe('$compile', function() {
             owRefAlias: '< owRef',
             owOptref: '<?',
             owOptrefAlias: '<? owOptref',
-            owColref: '<*',
-            owColrefAlias: '<* owColref',
             expr: '&',
             optExpr: '&?',
             exprAlias: '&expr',
@@ -4479,77 +4477,6 @@ describe('$compile', function() {
             expect(componentScope.owOptrefAlias).toBe(undefined);
           }));
         });
-
-        describe('collection object reference', function() {
-          it('should update isolate scope when origin scope changes', inject(function() {
-            $rootScope.collection = [{
-              name: 'Gabriel',
-              value: 18
-            }, {
-              name: 'Tony',
-              value: 91
-            }];
-            $rootScope.query = "";
-            $rootScope.$apply();
-
-            compile('<div><span my-component ow-colref="collection | filter:query">');
-
-            expect(componentScope.owColref).toEqual($rootScope.collection);
-            expect(componentScope.owColrefAlias).toEqual(componentScope.owColref);
-
-            $rootScope.query = "Gab";
-            $rootScope.$apply();
-
-            expect(componentScope.owColref).toEqual([$rootScope.collection[0]]);
-            expect(componentScope.owColrefAlias).toEqual([$rootScope.collection[0]]);
-          }));
-
-
-          it('should not update the origin scope when isolate scope collection is replaced', inject(function() {
-            $rootScope.collection = [{
-              name: 'Gabriel',
-              value: 18
-            }, {
-              name: 'Tony',
-              value: 91
-            }];
-
-            compile('<div><span my-component ow-colref="collection">');
-
-            componentScope.owColref = [{
-              name: 'Boris',
-              value: 55
-            }];
-            componentScope.$apply();
-
-            expect($rootScope.collection[1]).toEqual({name: 'Tony', value: 91});
-          }));
-
-
-          it('should update the origin scope when isolate scope item changes', inject(function() {
-            $rootScope.collection = [{
-              name: 'Gabriel',
-              value: 18
-            }, {
-              name: 'Tony',
-              value: 91
-            }];
-
-            compile('<div><span my-component ow-colref="collection">');
-
-            var newItem = {
-              name: 'Pablo',
-              value: 10
-            };
-            componentScope.owColref[0].value = 72;
-            componentScope.owColref.push(newItem);
-            componentScope.$apply();
-
-            expect($rootScope.collection[0].value).toBe(72);
-            expect($rootScope.collection[2]).toEqual(newItem);
-          }));
-
-        });
       });
     });