Merge pull request #4557 from Polymer/minor-docs-fixes

Minor doc fixes.

Author: kevinpschaaf

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,

lib/utils/debounce.html

@@ -68,7 +68,28 @@
     }
   /**
    * 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. The following
+   * example shows how a debouncer can be called multiple times within a
+   * microtask and "debounced" such that the provided callback function is
+   * called once. Add this method to a custom element:
+   *
+   * _debounceWork() {
+   *   this._debounceJob = Polymer.Debouncer.debounce(this._debounceJob,
+   *       Polymer.Async.microTask, () => {
+   *     this._doWork();
+   *   });
+   * }
+   *
+   * If the `_debounceWork` method is called multiple times within the same
+   * microtask, the `_doWork` function will be called only once at the next
+   * microtask checkpoint.
+   *
+   * 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(this._debounceJob)` at the end of the
+   * `_debounceWork` method. 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

test/unit/shady-events.html

@@ -221,6 +221,12 @@
 
   test('scoped focus and blur events do not retarget', function() {
     var el = fixture('focus');
+    var e = new Event('focus');
+    if (e.isTrused !== false) {
+      // skip browser if we cannot distinguish
+      // native focus events from user created ones
+      this.skip();
+    }
     el.fireScoped();
     assert.equal(el.events.length, 1);
     assert.equal(el.events[0], el.$.child);