diff --git a/lib/utils/async.html b/lib/utils/async.html
index 6bcfbd4b61..d175ec9fd8 100644
--- a/lib/utils/async.html
+++ b/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++;
diff --git a/lib/utils/boot.html b/lib/utils/boot.html
index 677a295466..edefdce18d 100644
--- a/lib/utils/boot.html
+++ b/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);
diff --git a/lib/utils/debounce.html b/lib/utils/debounce.html
index e32b9ffe57..dc8f66a796 100644
--- a/lib/utils/debounce.html
+++ b/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;
}
}
diff --git a/lib/utils/gestures.html b/lib/utils/gestures.html
index 01f4660734..5d8183f848 100644
--- a/lib/utils/gestures.html
+++ b/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);