From 36792f94d25d5ef9c2261eb21fbf873e7bd6d970 Mon Sep 17 00:00:00 2001
From: Steven Orvell <sorvell@google.com>
Date: Thu, 20 Apr 2017 17:08:12 -0700
Subject: [PATCH] Fixes #4553, #4554

---
 lib/elements/dom-repeat.html | 10 ++++++----
 lib/utils/debounce.html      | 14 +++++++++++++-
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/lib/elements/dom-repeat.html b/lib/elements/dom-repeat.html
index 69690143f0..5efa30a43d 100644
--- a/lib/elements/dom-repeat.html
+++ b/lib/elements/dom-repeat.html
@@ -157,8 +157,9 @@
 
         /**
          * 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 @@
 
         /**
          * 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,
diff --git a/lib/utils/debounce.html b/lib/utils/debounce.html
index dc8f66a796..636af2cc15 100644
--- a/lib/utils/debounce.html
+++ b/lib/utils/debounce.html
@@ -68,7 +68,19 @@
     }
   /**
    * 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