jsdoc fixes.

lib/utils/async.html

@@ -145,10 +145,10 @@
        * @memberof Polymer.Async.timeOut
        * @param {*} handle Handle returned from `run` of callback to cancel
        */
-      cancel(timer) {
-        return window.cancelIdleCallback ?
-          window.cancelIdleCallback(timer) :
-          window.clearTimeout(timer);
+      cancel(handle) {
+        window.cancelIdleCallback ?
+          window.cancelIdleCallback(handle) :
+          window.clearTimeout(handle);
       }
     },
 
@@ -172,7 +172,8 @@
        * Enqueues a function called at microtask timing.
        *
        * @memberof Polymer.Async.timeOut
-       * @param {Function} fn Callback to run
+       * @param {Function} callback Callback to run
+       * @return {*} Handle used for canceling task
        */
       run(callback) {
         microtaskNode.textContent = microtaskNodeContent++;

lib/utils/boot.html

@@ -18,6 +18,12 @@
    * @summary Polymer is a lightweight library built on top of the web
    * standards-based Web Components API's, and makes it easy to build your
    * own custom HTML elements.
+   * @param {Object} info Prototype for the custom element. It must contain
+   * an `is` property to specify the element name. Other properties populate
+   * the element prototype. The `properties`, `observers`, `hostAttributes`,
+   * and `listeners` properties are processed to create element features.
+   * @return {Object} Returns a custom element class for the given provided
+   * prototype `info` object. The name of the element if given by `info.is`.
    */
   window.Polymer = function(info) {
     return window.Polymer._polymerFn(info);

lib/utils/debounce.html

@@ -29,12 +29,12 @@
      * a callback and optional arguments to be passed to the run function
      * from the async module.
      *
-     * @param {!AsyncModule} asyncModule
-     * @param {function()} callback
+     * @param {!AsyncModule} asyncModule Object with Async interface.
+     * @param {function()} callback Callback to run.
      */
-    setConfig(asyncModule, cb) {
+    setConfig(asyncModule, callback) {
       this._asyncModule = asyncModule;
-      this._callback = cb;
+      this._callback = callback;
       this._timer = this._asyncModule.run(() => {
         this._timer = null;
         this._callback()
@@ -61,7 +61,7 @@
     /**
      * Returns true if the debouncer is active.
      *
-     * @return {boolean}
+     * @return {boolean} True if active.
      */
     isActive() {
       return this._timer != null;
@@ -70,18 +70,18 @@
    * Creates a debouncer if no debouncer is passed as a parameter
    * or it cancels an active debouncer otherwise.
    *
-   * @param {Polymer.Debouncer?} debouncer
-   * @param {!AsyncModule} asyncModule
-   * @param {function()} cb
-   * @return {!Debouncer}
+   * @param {Polymer.Debouncer?} debouncer Debouncer object.
+   * @param {!AsyncModule} asyncModule Object with Async interface
+   * @param {function()} callback Callback to run.
+   * @return {!Debouncer} Returns a debouncer object.
    */
-    static debounce(debouncer, asyncModule, cb) {
+    static debounce(debouncer, asyncModule, callback) {
       if (debouncer instanceof Debouncer) {
         debouncer.cancel();
       } else {
         debouncer = new Debouncer();
       }
-      debouncer.setConfig(asyncModule, cb);
+      debouncer.setConfig(asyncModule, callback);
       return debouncer;
     }
   }

lib/utils/gestures.html

@@ -86,7 +86,7 @@
   };
 
   /**
-   * @param {boolean=} setup
+   * @param {boolean=} setup True to add, false to remove.
    */
   function setupTeardownMouseCanceller(setup) {
     let events = IS_TOUCH_ONLY ? ['click'] : MOUSE_EVENTS;
@@ -235,6 +235,8 @@
      * @memberof Polymer.Gestures
      * @param {number} x Horizontal pixel coordinate
      * @param {number} y Vertical pixel coordinate
+     * @return {HTMLElement} Returns the deepest shadowRoot inclusive element
+     * found at the screen position given.
      */
     deepTargetFind: function(x, y) {
       let node = document.elementFromPoint(x, y);
@@ -260,6 +262,8 @@
      * a cheaper check than ev.composedPath()[0];
      *
      * @private
+     * @param {Event} ev Event.
+     * @returns {HTMLElement} Returns the event target.
      */
     _findOriginalTarget: function(ev) {
       // shadowdom
@@ -272,6 +276,7 @@
 
     /**
      * @private
+     * @param {Event} ev Event.
      */
     _handleNative: function(ev) {
       let handled;
@@ -332,6 +337,7 @@
 
     /**
      * @private
+     * @param {Event} ev Event.
      */
     _handleTouchAction: function(ev) {
       let t = ev.changedTouches[0];
@@ -373,6 +379,7 @@
      * @param {Node} node Node to add listener on
      * @param {string} evType Gesture type: `down`, `up`, `track`, or `tap`
      * @param {Function} handler Event listener function to call
+     * @returns {boolean} Returns true if a gesture event listener was added.
      */
     addListener: function(node, evType, handler) {
       if (this.gestures[evType]) {
@@ -389,6 +396,7 @@
      * @param {string} evType Gesture type: `down`, `up`, `track`, or `tap`
      * @param {Function} handler Event listener function previously passed to
      *  `addListener`.
+     * @returns {boolean} Returns true if a gesture event listener was removed.
      */
     removeListener: function(node, evType, handler) {
       if (this.gestures[evType]) {
@@ -401,6 +409,9 @@
      * automate the event listeners for the native events
      *
      * @private
+     * @param {HTMLElement} node Node on which to add the event.
+     * @param {string} evType Event type to add.
+     * @param {function} handler Event handler function.
      */
     _add: function(node, evType, handler) {
       let recognizer = this.gestures[evType];
@@ -436,6 +447,9 @@
      * automate event listener removal for native events
      *
      * @private
+     * @param {HTMLElement} node Node on which to remove the event.
+     * @param {string} evType Event type to remove.
+     * @param {function} handler Event handler function.
      */
     _remove: function(node, evType, handler) {
       let recognizer = this.gestures[evType];
@@ -474,6 +488,8 @@
 
     /**
      * @private
+     * @param {string} evName Event name.
+     * @return {Object} Returns the gesture for the given event name.
      */
     _findRecognizerByEvent: function(evName) {
       for (let i = 0, r; i < this.recognizers.length; i++) {
@@ -506,7 +522,12 @@
     },
 
     /**
+     * Dispatches an event on the `target` element of `type` with the given
+     * `detail`.
      * @private
+     * @param {HTMLElement} target The element on which to fire an event.
+     * @param {string} type The type of event to fire.
+     * @param {Object=} detail The detail object to populate on the event.
      */
     _fire: function(target, type, detail) {
       let ev = new Event(type, { bubbles: true, cancelable: true, composed: true });
@@ -525,6 +546,7 @@
      * Prevents the dispatch and default action of the given event name.
      *
      * @memberof Polymer.Gestures
+     * @param {string} evName Event name.
      */
     prevent: function(evName) {
       let recognizer = this._findRecognizerByEvent(evName);