Fixes #4553, #4554

lib/elements/dom-repeat.html

@@ -157,8 +157,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
         /**
          * The name of the variable to add to the binding scope with the index
-         * for the inst.  If `sort` is provided, the index will reflect the
-         * sorted order (rather than the original array order).
+         * of the instance in the sorted and filtered list of rendered items.
+         * Note, for the index in the `this.items` array, use the value of the
+         * `itemsIndexAs` property.
          */
         indexAs: {
           type: String,
@@ -167,8 +168,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
         /**
          * The name of the variable to add to the binding scope with the index
-         * for the inst.  If `sort` is provided, the index will reflect the
-         * sorted order (rather than the original array order).
+         * of the instance in the `this.items` array. Note, for the index of
+         * this instance in the sorted and filtered list of rendered items,
+         * use the value of the `indexAs` property.
          */
         itemsIndexAs: {
           type: String,

lib/utils/debounce.html

@@ -68,7 +68,19 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     }
   /**
    * Creates a debouncer if no debouncer is passed as a parameter
-   * or it cancels an active debouncer otherwise.
+   * or it cancels an active debouncer otherwise. For example, the following
+   * code can be called multiple times within a microtask and the provided
+   * function will be debounced (called once at the next microtask checkpoint):
+   *
+   * let job = Polymer.Debouncer.debounce(job, Polymer.Async.microTask, () => {
+   *   console.log('debounced!');
+   * });
+   *
+   * Note: In testing it is often convenient to avoid asynchrony. To accomplish
+   * this with a debouncer, you can use `Polymer.enqueueDebouncer` and
+   * `Polymer.flush`. For example, extend the above example by adding
+   * `Polymer.enqueueDebouncer(job)`. Then in a test, call `Polymer.flush` to
+   * ensure the debouncer has completed.
    *
    * @param {Polymer.Debouncer?} debouncer Debouncer object.
    * @param {!AsyncModule} asyncModule Object with Async interface