[ci skip] Update docs.

lib/legacy/mutable-data-behavior.html

@@ -17,7 +17,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
   /**
    * Legacy element behavior to skip strict dirty-checking for objects and arrays,
-   * for use on elements utilizing `Polymer.PropertyEffects`
+   * (always consider them to be "dirty") for use on legacy API Polymer elements.
    *
    * By default, `Polymer.PropertyEffects` performs strict dirty checking on
    * objects, which means that any deep modifications to an object or array will
@@ -31,9 +31,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
    *
    * In cases where neither immutable patterns or the data mutation API can be
    * used, applying this mixin will allow Polymer to skip dirty checking for
-   * objects and arrays.  This allows a user to make a deep modification to a
-   * bound object graph, and then either simply re-set the object (e.g.
-   * `this.items = this.items`) or call `notifyPath`
+   * objects and arrays (always consider them to be "dirty").  This allows a
+   * user to make a deep modification to a bound object graph, and then either
+   * simply re-set the object (e.g. `this.items = this.items`) or call `notifyPath`
    * (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.
@@ -79,17 +79,10 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
      * same object (using the temp cache as an in-turn backstop to prevent
      * cycles due to 2-way notification).
      *
-     * Users may override this method and call super setting `useObjectIdentity`
-     * to `true` to fall back to strict dirty checking if the mutable nature
-     * requires configurability.
-     *
      * @param {string} property Property name
      * @param {*} value New property value
      * @param {*} old Previous property value
-     * @param {boolean} useObjectIdentity When true, the method falls back
-     *   to using strict object identity dirty checking
      * @return {boolean} Whether the property should be considered a change
-     *   and enqueue a `_proeprtiesChanged` callback
      * @protected
      */
     _shouldPropertyChange(property, value, old) {

lib/mixins/mutable-data.html

@@ -33,7 +33,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
   /**
    * Element class mixin to add the ability to skip strict dirty-checking for
-   * objects and arrays, for use on elements utilizing `Polymer.PropertyEffects`
+   * objects and arrays (always consider them to be "dirty"), for use on
+   * elements utilizing `Polymer.PropertyEffects`
    *
    * By default, `Polymer.PropertyEffects` performs strict dirty checking on
    * objects, which means that any deep modifications to an object or array will
@@ -47,9 +48,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
    *
    * In cases where neither immutable patterns or the data mutation API can be
    * used, applying this mixin will allow Polymer to skip dirty checking for
-   * objects and arrays.  This allows a user to make a deep modification to a
-   * bound object graph, and then either simply re-set the object (e.g.
-   * `this.items = this.items`) or call `notifyPath`
+   * objects and arrays (always consider them to be "dirty").  This allows a
+   * user to make a deep modification to a bound object graph, and then either
+   * simply re-set the object (e.g. `this.items = this.items`) or call `notifyPath`
    * (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.
@@ -102,15 +103,10 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
        * same object (using the temp cache as an in-turn backstop to prevent
        * cycles due to 2-way notification).
        *
-       * Users may override this method and call super setting `useObjectIdentity`
-       * to `true` to fall back to strict dirty checking if the mutable nature
-       * requires configurability.
-       *
        * @param {string} property Property name
        * @param {*} value New property value
        * @param {*} old Previous property value
        * @return {boolean} Whether the property should be considered a change
-       *   and enqueue a `_proeprtiesChanged` callback
        * @protected
        */
       _shouldPropertyChange(property, value, old) {