From fb0e617c3d86098d79da9639fcaa05c25cf00fa3 Mon Sep 17 00:00:00 2001
From: Martin Staffa <mjstaffa@gmail.com>
Date: Wed, 31 May 2017 20:46:48 +0200
Subject: [PATCH 1/4] docs($compile): add more info about optional bindings

This also deletes the incorrect info that a missing attribute
in a non-optional binding will throw.

Closes #15989
---
 docs/content/error/$compile/iscp.ngdoc | 14 +++++-----
 src/ng/compile.js                      | 37 +++++++++++++++++++++++---
 2 files changed, 40 insertions(+), 11 deletions(-)

diff --git a/docs/content/error/$compile/iscp.ngdoc b/docs/content/error/$compile/iscp.ngdoc
index 78f82f2f6c61..4d693fc2d996 100644
--- a/docs/content/error/$compile/iscp.ngdoc
+++ b/docs/content/error/$compile/iscp.ngdoc
@@ -10,13 +10,13 @@ myModule.directive('directiveName', function factory() {
   return {
     ...
     scope: {
-      'attrName': '@', // OK
-      'attrName2': '=localName', // OK
-      'attrName3': '<?localName', // OK
-      'attrName4': ' = name', // OK
-      'attrName5': 'name',    // ERROR: missing mode @&=
-      'attrName6': 'name=',   // ERROR: must be prefixed with @&=
-      'attrName7': '=name?',  // ERROR: ? must come directly after the mode
+      'localName': '@', // OK
+      'localName2': '=attr', // OK
+      'localName3': '<?attr', // OK
+      'localName4': ' = attr', // OK
+      'localName5': 'attr',    // ERROR: missing mode @&=
+      'localName6': 'attr=',   // ERROR: must be prefixed with @&=
+      'localName7': '=attr?',  // ERROR: ? must come directly after the mode
     }
     ...
   }
diff --git a/src/ng/compile.js b/src/ng/compile.js
index a2d9730c3920..dd8cbc89b149 100644
--- a/src/ng/compile.js
+++ b/src/ng/compile.js
@@ -303,16 +303,15 @@
  *   name. Given `<my-component my-attr="parentModel">` and the isolate scope definition `scope: {
  *   localModel: '=myAttr' }`, the property `localModel` on the directive's scope will reflect the
  *   value of `parentModel` on the parent scope. Changes to `parentModel` will be reflected in
- *   `localModel` and vice versa. Optional attributes should be marked as such with a question mark:
- *   `=?` or `=?attr`. If the binding expression is non-assignable, or if the attribute isn't
- *   optional and doesn't exist, an exception ({@link error/$compile/nonassign `$compile:nonassign`})
+ *   `localModel` and vice versa. If the binding expression is non-assignable, an exception
+ *   ({@link error/$compile/nonassign `$compile:nonassign`})
  *   will be thrown upon discovering changes to the local value, since it will be impossible to sync
  *   them back to the parent scope. By default, the {@link ng.$rootScope.Scope#$watch `$watch`}
  *   method is used for tracking changes, and the equality check is based on object identity.
  *   However, if an object literal or an array literal is passed as the binding expression, the
  *   equality check is done by value (using the {@link angular.equals} function). It's also possible
  *   to watch the evaluated value shallowly with {@link ng.$rootScope.Scope#$watchCollection
- *   `$watchCollection`}: use `=*` or `=*attr` (`=*?` or `=*?attr` if the attribute is optional).
+ *   `$watchCollection`}: use `=*` or `=*attr`
  *
   * * `<` 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
@@ -347,6 +346,36 @@
  *   and values into the expression wrapper fn. For example, if the expression is `increment(amount)`
  *   then we can specify the amount value by calling the `localFn` as `localFn({amount: 22})`.
  *
+ * All 4 kinds of bindings (`@`, `=`, `<`, and `&`) can be made optional by adding `?` to the expression.
+ * The marker must come before the attribute name.
+ * See the {@link error/$compile/iscp the Invalid Isolate Scope Definition error} for definition examples.
+ * This is useful to refine the interface directives provides.
+ * One subtle difference between optional and non-optional happens **when the binding attribute is not
+ * set**:
+ * - the binding is optional: the property will not be defined
+ * - the binding is not optional: the property is defined
+ *
+ * ```js
+ *app.directive('testDir', function() {
+    return {
+      scope: {
+        notoptional: '=',
+        optional: '=?',
+      },
+      bindToController: true,
+      controller: function() {
+        this.$onInit = function() {
+          console.log(this.hasOwnProperty('notoptional')) // true
+          console.log(this.hasOwnProperty('optional')) // false
+        }
+      }
+    }
+  })
+ *```
+ *
+ *
+ * ##### Combining directives with different scope defintions
+ *
  * In general it's possible to apply more than one directive to one element, but there might be limitations
  * depending on the type of scope required by the directives. The following points will help explain these limitations.
  * For simplicity only two directives are taken into account, but it is also applicable for several directives:

From e303a43965d52b580910d64ab5c9f0f11fba9bf4 Mon Sep 17 00:00:00 2001
From: Martin Staffa <mjstaffa@googlemail.com>
Date: Fri, 2 Jun 2017 14:36:18 +0200
Subject: [PATCH 2/4] fixup! Better examples for iscp

---
 docs/content/error/$compile/iscp.ngdoc | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/content/error/$compile/iscp.ngdoc b/docs/content/error/$compile/iscp.ngdoc
index 4d693fc2d996..8153e44d4a05 100644
--- a/docs/content/error/$compile/iscp.ngdoc
+++ b/docs/content/error/$compile/iscp.ngdoc
@@ -11,12 +11,14 @@ myModule.directive('directiveName', function factory() {
     ...
     scope: {
       'localName': '@', // OK
-      'localName2': '=attr', // OK
+      'localName2': '&attr', // OK
       'localName3': '<?attr', // OK
       'localName4': ' = attr', // OK
-      'localName5': 'attr',    // ERROR: missing mode @&=
-      'localName6': 'attr=',   // ERROR: must be prefixed with @&=
-      'localName7': '=attr?',  // ERROR: ? must come directly after the mode
+      'localName5': ' =*attr', // OK      
+      'localName6': 'attr',    // ERROR: missing mode @&=<
+      'localName7': 'attr=',   // ERROR: must be prefixed with @&=<
+      'localName8': '=attr?',  // ERROR: ? must come directly after the mode
+      'localName9': '<*'  // ERROR: * is only valid with =
     }
     ...
   }

From 3bc74b7923b5f09777cded9c5999b78e7a5adfe3 Mon Sep 17 00:00:00 2001
From: Martin Staffa <mjstaffa@googlemail.com>
Date: Fri, 2 Jun 2017 14:37:52 +0200
Subject: [PATCH 3/4] fixup! typos

---
 src/ng/compile.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/ng/compile.js b/src/ng/compile.js
index dd8cbc89b149..c1dfed7bbd7d 100644
--- a/src/ng/compile.js
+++ b/src/ng/compile.js
@@ -348,8 +348,8 @@
  *
  * All 4 kinds of bindings (`@`, `=`, `<`, and `&`) can be made optional by adding `?` to the expression.
  * The marker must come before the attribute name.
- * See the {@link error/$compile/iscp the Invalid Isolate Scope Definition error} for definition examples.
- * This is useful to refine the interface directives provides.
+ * See the {@link error/$compile/iscp Invalid Isolate Scope Definition error} for definition examples.
+ * This is useful to refine the interface directives provide.
  * One subtle difference between optional and non-optional happens **when the binding attribute is not
  * set**:
  * - the binding is optional: the property will not be defined

From 4d852131277c53c282f1ea5e64539c94095e49de Mon Sep 17 00:00:00 2001
From: Martin Staffa <mjstaffa@gmail.com>
Date: Fri, 2 Jun 2017 17:49:38 +0200
Subject: [PATCH 4/4] re-add info about missing attr with 2way binding

---
 src/ng/compile.js | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/src/ng/compile.js b/src/ng/compile.js
index c1dfed7bbd7d..ef2e65ad379d 100644
--- a/src/ng/compile.js
+++ b/src/ng/compile.js
@@ -303,10 +303,12 @@
  *   name. Given `<my-component my-attr="parentModel">` and the isolate scope definition `scope: {
  *   localModel: '=myAttr' }`, the property `localModel` on the directive's scope will reflect the
  *   value of `parentModel` on the parent scope. Changes to `parentModel` will be reflected in
- *   `localModel` and vice versa. If the binding expression is non-assignable, an exception
- *   ({@link error/$compile/nonassign `$compile:nonassign`})
- *   will be thrown upon discovering changes to the local value, since it will be impossible to sync
- *   them back to the parent scope. By default, the {@link ng.$rootScope.Scope#$watch `$watch`}
+ *   `localModel` and vice versa. If the binding expression is non-assignable, or if the attribute
+ *   isn't  optional and doesn't exist, an exception
+ *   ({@link error/$compile/nonassign `$compile:nonassign`}) will be thrown upon discovering changes
+ *   to the local value, since it will be impossible to sync them back to the parent scope.
+ *
+ *   By default, the {@link ng.$rootScope.Scope#$watch `$watch`}
  *   method is used for tracking changes, and the equality check is based on object identity.
  *   However, if an object literal or an array literal is passed as the binding expression, the
  *   equality check is done by value (using the {@link angular.equals} function). It's also possible
@@ -316,7 +318,7 @@
   * * `<` 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`.
+ *   local name.
  *
  *   For example, given `<my-component my-attr="parentModel">` and directive definition of
  *   `scope: { localModel:'<myAttr' }`, then the isolated scope property `localModel` will reflect the
@@ -347,7 +349,7 @@
  *   then we can specify the amount value by calling the `localFn` as `localFn({amount: 22})`.
  *
  * All 4 kinds of bindings (`@`, `=`, `<`, and `&`) can be made optional by adding `?` to the expression.
- * The marker must come before the attribute name.
+ * The marker must come after the mode and before the attribute name.
  * See the {@link error/$compile/iscp Invalid Isolate Scope Definition error} for definition examples.
  * This is useful to refine the interface directives provide.
  * One subtle difference between optional and non-optional happens **when the binding attribute is not