From 7360f42a34ad339cad6c5e2d969a0c8d299a5fea Mon Sep 17 00:00:00 2001
From: Kevin Schaaf <kschaaf@google.com>
Date: Wed, 1 Nov 2017 17:07:59 -0700
Subject: [PATCH] Clarify all elements between changes must apply mixing. Fixes
 #4914

---
 lib/legacy/mutable-data-behavior.html | 6 ++++++
 lib/mixins/mutable-data.html          | 6 ++++++
 2 files changed, 12 insertions(+)

diff --git a/lib/legacy/mutable-data-behavior.html b/lib/legacy/mutable-data-behavior.html
index 850edf185b..0d66613191 100644
--- a/lib/legacy/mutable-data-behavior.html
+++ b/lib/legacy/mutable-data-behavior.html
@@ -42,6 +42,9 @@
    * (e.g. `this.notifyPath('items')`) to update the tree.  Note that all
    * elements that wish to be updated based on deep mutations must apply this
    * mixin or otherwise skip strict dirty checking for objects/arrays.
+   * Specifically, any elements in the binding tree between the source of a
+   * mutation and the consumption of it must apply this behavior or enable the
+   * `Polymer.OptionalMutableDataBehavior`.
    *
    * In order to make the dirty check strategy configurable, see
    * `Polymer.OptionalMutableDataBehavior`.
@@ -102,6 +105,9 @@
    * (e.g. `this.notifyPath('items')`) to update the tree.  Note that all
    * elements that wish to be updated based on deep mutations must apply this
    * mixin or otherwise skip strict dirty checking for objects/arrays.
+   * Specifically, any elements in the binding tree between the source of a
+   * mutation and the consumption of it must enable this behavior or apply the
+   * `Polymer.OptionalMutableDataBehavior`.
    *
    * While this behavior adds the ability to forgo Object/Array dirty checking,
    * the `mutableData` flag defaults to false and must be set on the instance.
diff --git a/lib/mixins/mutable-data.html b/lib/mixins/mutable-data.html
index 1074aeca85..0f7ed415ee 100644
--- a/lib/mixins/mutable-data.html
+++ b/lib/mixins/mutable-data.html
@@ -57,6 +57,9 @@
    * (e.g. `this.notifyPath('items')`) to update the tree.  Note that all
    * elements that wish to be updated based on deep mutations must apply this
    * mixin or otherwise skip strict dirty checking for objects/arrays.
+   * Specifically, any elements in the binding tree between the source of a
+   * mutation and the consumption of it must apply this mixin or enable the
+   * `Polymer.OptionalMutableData` mixin.
    *
    * In order to make the dirty check strategy configurable, see
    * `Polymer.OptionalMutableData`.
@@ -132,6 +135,9 @@
    * (e.g. `this.notifyPath('items')`) to update the tree.  Note that all
    * elements that wish to be updated based on deep mutations must apply this
    * mixin or otherwise skip strict dirty checking for objects/arrays.
+   * Specifically, any elements in the binding tree between the source of a
+   * mutation and the consumption of it must enable this mixin or apply the
+   * `Polymer.MutableData` mixin.
    *
    * While this mixin adds the ability to forgo Object/Array dirty checking,
    * the `mutableData` flag defaults to false and must be set on the instance.