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);