From ee4445f8a4739f43c790b9a2640595b757504878 Mon Sep 17 00:00:00 2001 From: Alexander Marks Date: Fri, 15 Dec 2017 15:55:14 -0800 Subject: [PATCH] Tighten Closure type annotations. (#4997) --- externs/closure-types.js | 12 +++++----- lib/elements/array-selector.html | 2 +- lib/elements/dom-bind.html | 5 +++- lib/elements/dom-module.html | 6 +++++ lib/legacy/legacy-element-mixin.html | 31 +++++++++++++------------ lib/legacy/polymer-fn.html | 2 +- lib/legacy/polymer.dom.html | 8 +++---- lib/utils/async.html | 6 ++--- lib/utils/flattened-nodes-observer.html | 15 +++++++++--- lib/utils/flush.html | 2 +- lib/utils/gestures.html | 27 +++++++++++---------- lib/utils/import-href.html | 6 ++--- lib/utils/mixin.html | 3 ++- lib/utils/settings.html | 6 +---- lib/utils/templatize.html | 2 ++ 15 files changed, 77 insertions(+), 56 deletions(-) diff --git a/externs/closure-types.js b/externs/closure-types.js index 81a2fa86f4..5f243df172 100644 --- a/externs/closure-types.js +++ b/externs/closure-types.js @@ -1145,7 +1145,7 @@ Polymer_LegacyElementMixin.prototype.flushDebouncer = function(jobName){}; */ Polymer_LegacyElementMixin.prototype.cancelDebouncer = function(jobName){}; /** -* @param {Function} callback The callback function to run, bound to `this`. +* @param {!Function} callback The callback function to run, bound to `this`. * @param {number=} waitTime Time to wait before calling the `callback`. If unspecified or 0, the callback will be run at microtask timing (before paint). @@ -1167,18 +1167,18 @@ Polymer_LegacyElementMixin.prototype.cancelAsync = function(handle){}; Polymer_LegacyElementMixin.prototype.create = function(tag, props){}; /** * @param {string} href URL to document to load. -* @param {Function} onload Callback to notify when an import successfully +* @param {!Function=} onload Callback to notify when an import successfully loaded. -* @param {Function} onerror Callback to notify when an import +* @param {!Function=} onerror Callback to notify when an import unsuccessfully loaded. -* @param {boolean} optAsync True if the import should be loaded `async`. +* @param {boolean=} optAsync True if the import should be loaded `async`. Defaults to `false`. * @return {HTMLLinkElement} */ Polymer_LegacyElementMixin.prototype.importHref = function(href, onload, onerror, optAsync){}; /** * @param {string} selector Selector to test. -* @param {Element=} node Element to test the selector against. +* @param {!Element=} node Element to test the selector against. * @return {boolean} */ Polymer_LegacyElementMixin.prototype.elementMatches = function(selector, node){}; @@ -1320,4 +1320,4 @@ Polymer_ArraySelectorMixin.prototype.select = function(item){}; * @param {number} idx Index from `items` array to select * @return {void} */ -Polymer_ArraySelectorMixin.prototype.selectIndex = function(idx){}; \ No newline at end of file +Polymer_ArraySelectorMixin.prototype.selectIndex = function(idx){}; diff --git a/lib/elements/array-selector.html b/lib/elements/array-selector.html index 680452cc8e..79408d2e08 100644 --- a/lib/elements/array-selector.html +++ b/lib/elements/array-selector.html @@ -211,7 +211,7 @@ /** * Clears the selection state. - * + * @return {void} */ clearSelection() { // Unbind previous selection diff --git a/lib/elements/dom-bind.html b/lib/elements/dom-bind.html index 6d1283989c..8b64cca385 100644 --- a/lib/elements/dom-bind.html +++ b/lib/elements/dom-bind.html @@ -61,16 +61,19 @@ this.__children = null; } - // assumes only one observed attribute + /** @return {void} */ attributeChangedCallback() { + // assumes only one observed attribute this.mutableData = true; } + /** @return {void} */ connectedCallback() { this.style.display = 'none'; this.render(); } + /** @return {void} */ disconnectedCallback() { this.__removeChildren(); } diff --git a/lib/elements/dom-module.html b/lib/elements/dom-module.html index d18837c048..3ca593b1a9 100644 --- a/lib/elements/dom-module.html +++ b/lib/elements/dom-module.html @@ -74,6 +74,12 @@ return null; } + /** + * @param {string} name Name of attribute. + * @param {?string} old Old value of attribute. + * @param {?string} value Current value of attribute. + * @return {void} + */ attributeChangedCallback(name, old, value) { if (old !== value) { this.register(); diff --git a/lib/legacy/legacy-element-mixin.html b/lib/legacy/legacy-element-mixin.html index 3ce281c363..4f912b8a8d 100644 --- a/lib/legacy/legacy-element-mixin.html +++ b/lib/legacy/legacy-element-mixin.html @@ -134,6 +134,7 @@ * @param {string} name Name of attribute. * @param {?string} old Old value of attribute. * @param {?string} value Current value of attribute. + * @return {void} * @override */ attributeChangedCallback(name, old, value) { @@ -487,7 +488,7 @@ * childNodes list is the same as the element's childNodes except that * any `` elements are replaced with the list of nodes distributed * to the ``, the result of its `getDistributedNodes` method. - * @return {Array} List of effective child nodes. + * @return {!Array} List of effective child nodes. * @suppress {invalidCasts} LegacyElementMixin must be applied to an HTMLElement */ getEffectiveChildNodes() { @@ -501,7 +502,7 @@ * `selector`. These can be dom children or elements distributed to * children that are insertion points. * @param {string} selector Selector to run. - * @return {Array} List of distributed elements that match selector. + * @return {!Array} List of distributed elements that match selector. * @suppress {invalidCasts} LegacyElementMixin must be applied to an HTMLElement */ queryDistributedElements(selector) { @@ -516,11 +517,11 @@ * any `` elements are replaced with the list of elements * distributed to the ``. * - * @return {Array} List of effective children. + * @return {!Array} List of effective children. */ getEffectiveChildren() { let list = this.getEffectiveChildNodes(); - return list.filter(function(/** @type {Node} */ n) { + return list.filter(function(/** @type {!Node} */ n) { return (n.nodeType === Node.ELEMENT_NODE); }); } @@ -560,7 +561,7 @@ * match `selector`. These can be dom child nodes or elements distributed * to children that are insertion points. * @param {string} selector Selector to run. - * @return {Array} List of effective child nodes that match selector. + * @return {!Array} List of effective child nodes that match selector. */ queryAllEffectiveChildren(selector) { return this.queryDistributedElements(selector); @@ -574,7 +575,7 @@ * * @param {string=} slctr CSS selector to choose the desired * ``. Defaults to `content`. - * @return {Array} List of distributed nodes for the ``. + * @return {!Array} List of distributed nodes for the ``. */ getContentChildNodes(slctr) { let content = this.root.querySelector(slctr || 'slot'); @@ -592,12 +593,12 @@ * * @param {string=} slctr CSS selector to choose the desired * ``. Defaults to `content`. - * @return {Array} List of distributed nodes for the + * @return {!Array} List of distributed nodes for the * ``. * @suppress {invalidCasts} */ getContentChildren(slctr) { - let children = /** @type {Array} */(this.getContentChildNodes(slctr).filter(function(n) { + let children = /** @type {!Array} */(this.getContentChildNodes(slctr).filter(function(n) { return (n.nodeType === Node.ELEMENT_NODE); })); return children; @@ -657,7 +658,7 @@ * } * * @param {string} jobName String to identify the debounce job. - * @param {function()} callback Function that is called (with `this` + * @param {function():void} callback Function that is called (with `this` * context) when the wait time elapses. * @param {number} wait Optional wait time in milliseconds (ms) after the * last signal that must elapse before invoking `callback` @@ -721,7 +722,7 @@ * By default (if no waitTime is specified), async callbacks are run at * microtask timing, which will occur before paint. * - * @param {Function} callback The callback function to run, bound to `this`. + * @param {!Function} callback The callback function to run, bound to `this`. * @param {number=} waitTime Time to wait before calling the * `callback`. If unspecified or 0, the callback will be run at microtask * timing (before paint). @@ -777,13 +778,13 @@ * element will contain the imported document contents. * * @param {string} href URL to document to load. - * @param {Function} onload Callback to notify when an import successfully + * @param {!Function=} onload Callback to notify when an import successfully * loaded. - * @param {Function} onerror Callback to notify when an import + * @param {!Function=} onerror Callback to notify when an import * unsuccessfully loaded. - * @param {boolean} optAsync True if the import should be loaded `async`. + * @param {boolean=} optAsync True if the import should be loaded `async`. * Defaults to `false`. - * @return {HTMLLinkElement} The link element for the URL to be loaded. + * @return {!HTMLLinkElement} The link element for the URL to be loaded. */ importHref(href, onload, onerror, optAsync) { // eslint-disable-line no-unused-vars let loadFn = onload ? onload.bind(this) : null; @@ -796,7 +797,7 @@ * prefixed. * * @param {string} selector Selector to test. - * @param {Element=} node Element to test the selector against. + * @param {!Element=} node Element to test the selector against. * @return {boolean} Whether the element matches the selector. */ elementMatches(selector, node) { diff --git a/lib/legacy/polymer-fn.html b/lib/legacy/polymer-fn.html index 579b3688cf..80106a89ed 100644 --- a/lib/legacy/polymer-fn.html +++ b/lib/legacy/polymer-fn.html @@ -29,7 +29,7 @@ * @function Polymer * @param {!PolymerInit} info Object containing Polymer metadata and functions * to become class methods. - * @return {!HTMLElement} Generated class + * @return {function(new: HTMLElement)} Generated class * @suppress {duplicate, invalidCasts, checkTypes} */ window.Polymer._polymerFn = function(info) { diff --git a/lib/legacy/polymer.dom.html b/lib/legacy/polymer.dom.html index c94ef3892b..bdd2da94b7 100644 --- a/lib/legacy/polymer.dom.html +++ b/lib/legacy/polymer.dom.html @@ -17,7 +17,7 @@ const p = Element.prototype; /** - * @const {function(this:Element, string): boolean} + * @const {function(this:Node, string): boolean} */ const normalizedMatchesSelector = p.matches || p.matchesSelector || p.mozMatchesSelector || p.msMatchesSelector || @@ -28,7 +28,7 @@ * * @function matchesSelector * @memberof Polymer.dom - * @param {!Element} node Node to check selector against + * @param {!Node} node Node to check selector against * @param {string} selector Selector to match * @return {boolean} True if node matched selector */ @@ -157,8 +157,8 @@ } /** - * @return {Array} Returns a flattened list of all child nodes and nodes assigned - * to child slots. + * @return {!Array} Returns a flattened list of all child nodes and + * nodes assigned to child slots. */ getEffectiveChildNodes() { return Polymer.FlattenedNodesObserver.getFlattenedNodes(this.node); diff --git a/lib/utils/async.html b/lib/utils/async.html index 0a6fdd0527..2505df3ec3 100644 --- a/lib/utils/async.html +++ b/lib/utils/async.html @@ -80,7 +80,7 @@ * * @function * @memberof Polymer.Async.timeOut - * @param {Function} fn Callback to run + * @param {!Function} fn Callback to run * @param {number=} delay Delay in milliseconds * @return {number} Handle used for canceling task */ @@ -145,7 +145,7 @@ * Enqueues a function called at `requestIdleCallback` timing. * * @memberof Polymer.Async.idlePeriod - * @param {function(IdleDeadline)} fn Callback to run + * @param {function(!IdleDeadline):void} fn Callback to run * @return {number} Handle used for canceling task */ run(fn) { @@ -187,7 +187,7 @@ * Enqueues a function called at microtask timing. * * @memberof Polymer.Async.microTask - * @param {Function} callback Callback to run + * @param {!Function=} callback Callback to run * @return {number} Handle used for canceling task */ run(callback) { diff --git a/lib/utils/flattened-nodes-observer.html b/lib/utils/flattened-nodes-observer.html index 78f74127c5..9ea217fc70 100644 --- a/lib/utils/flattened-nodes-observer.html +++ b/lib/utils/flattened-nodes-observer.html @@ -102,9 +102,15 @@ * or removals from the target's list of flattened nodes. */ constructor(target, callback) { - /** @type {MutationObserver} */ + /** + * @type {MutationObserver} + * @private + */ this._shadyChildrenObserver = null; - /** @type {MutationObserver} */ + /** + * @type {MutationObserver} + * @private + */ this._nativeChildrenObserver = null; this._connected = false; this._target = target; @@ -112,7 +118,10 @@ this._effectiveNodes = []; this._observer = null; this._scheduled = false; - /** @type {function()} */ + /** + * @type {function()} + * @private + */ this._boundSchedule = () => { this._schedule(); }; diff --git a/lib/utils/flush.html b/lib/utils/flush.html index 4cfcee7b3c..3feaad6166 100644 --- a/lib/utils/flush.html +++ b/lib/utils/flush.html @@ -18,7 +18,7 @@ * Adds a `Polymer.Debouncer` to a list of globally flushable tasks. * * @memberof Polymer - * @param {Polymer.Debouncer} debouncer Debouncer to enqueue + * @param {!Polymer.Debouncer} debouncer Debouncer to enqueue * @return {void} */ Polymer.enqueueDebouncer = function(debouncer) { diff --git a/lib/utils/gestures.html b/lib/utils/gestures.html index dacc404a63..29353f835d 100644 --- a/lib/utils/gestures.html +++ b/lib/utils/gestures.html @@ -427,9 +427,9 @@ * Adds an event listener to a node for the given gesture type. * * @memberof Polymer.Gestures - * @param {Node} node Node to add listener on + * @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 + * @param {!Function} handler Event listener function to call * @return {boolean} Returns true if a gesture event listener was added. * @this {Gestures} */ @@ -445,9 +445,9 @@ * Removes an event listener from a node for the given gesture type. * * @memberof Polymer.Gestures - * @param {Node} node Node to remove listener from + * @param {!Node} node Node to remove listener from * @param {string} evType Gesture type: `down`, `up`, `track`, or `tap` - * @param {Function} handler Event listener function previously passed to + * @param {!Function} handler Event listener function previously passed to * `addListener`. * @return {boolean} Returns true if a gesture event listener was removed. * @this {Gestures} @@ -464,7 +464,7 @@ * automate the event listeners for the native events * * @private - * @param {HTMLElement} node Node on which to add the event. + * @param {!HTMLElement} node Node on which to add the event. * @param {string} evType Event type to add. * @param {function(Event?)} handler Event handler function. * @return {void} @@ -504,7 +504,7 @@ * automate event listener removal for native events * * @private - * @param {HTMLElement} node Node on which to remove the event. + * @param {!HTMLElement} node Node on which to remove the event. * @param {string} evType Event type to remove. * @param {function(Event?)} handler Event handler function. * @return {void} @@ -536,7 +536,7 @@ * gesture event types. * * @memberof Polymer.Gestures - * @param {GestureRecognizer} recog Gesture recognizer descriptor + * @param {!GestureRecognizer} recog Gesture recognizer descriptor * @return {void} * @this {Gestures} */ @@ -573,7 +573,7 @@ * adding event listeners. * * @memberof Polymer.Gestures - * @param {Element} node Node to set touch action setting on + * @param {!Element} node Node to set touch action setting on * @param {string} value Touch action value * @return {void} */ @@ -594,9 +594,9 @@ * Dispatches an event on the `target` element of `type` with the given * `detail`. * @private - * @param {EventTarget} target The element on which to fire an event. + * @param {!EventTarget} 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. + * @param {!Object=} detail The detail object to populate on the event. * @return {void} */ _fire: function(target, type, detail) { @@ -712,7 +712,7 @@ }, /** * @param {string} type - * @param {EventTarget} target + * @param {!EventTarget} target * @param {Event} event * @param {Function} preventer * @return {void} @@ -881,7 +881,7 @@ /** * @this {GestureRecognizer} - * @param {EventTarget} target + * @param {!EventTarget} target * @param {Touch} touch * @return {void} */ @@ -990,6 +990,9 @@ let dy = Math.abs(e.clientY - this.info.y); // find original target from `preventer` for TouchEvents, or `e` for MouseEvents let t = Gestures._findOriginalTarget(/** @type {Event} */(preventer || e)); + if (!t) { + return; + } // dx,dy can be NaN if `click` has been simulated and there was no `down` for `start` if (isNaN(dx) || isNaN(dy) || (dx <= TAP_DISTANCE && dy <= TAP_DISTANCE) || isSyntheticClick(e)) { // prevent taps from being generated if an event has canceled them diff --git a/lib/utils/import-href.html b/lib/utils/import-href.html index 24b394159e..89402ffb5d 100644 --- a/lib/utils/import-href.html +++ b/lib/utils/import-href.html @@ -36,13 +36,13 @@ * * @memberof Polymer * @param {string} href URL to document to load. - * @param {Function=} onload Callback to notify when an import successfully + * @param {!Function=} onload Callback to notify when an import successfully * loaded. - * @param {Function=} onerror Callback to notify when an import + * @param {!Function=} onerror Callback to notify when an import * unsuccessfully loaded. * @param {boolean=} optAsync True if the import should be loaded `async`. * Defaults to `false`. - * @return {HTMLLinkElement} The link element for the URL to be loaded. + * @return {!HTMLLinkElement} The link element for the URL to be loaded. */ Polymer.importHref = function(href, onload, onerror, optAsync) { let link = /** @type {HTMLLinkElement} */ diff --git a/lib/utils/mixin.html b/lib/utils/mixin.html index 525d1bc209..e97b3e2123 100644 --- a/lib/utils/mixin.html +++ b/lib/utils/mixin.html @@ -38,6 +38,7 @@ * @memberof Polymer * @template T * @param {T} mixin ES6 class expression mixin to wrap + * @return {T} * @suppress {invalidCasts} */ Polymer.dedupingMixin = function(mixin) { @@ -68,7 +69,7 @@ return extended; } - return dedupingMixin; + return /** @type {T} */ (dedupingMixin); }; /* eslint-enable valid-jsdoc */ diff --git a/lib/utils/settings.html b/lib/utils/settings.html index a2c8cc30df..88304a8e13 100644 --- a/lib/utils/settings.html +++ b/lib/utils/settings.html @@ -16,11 +16,6 @@ (function() { 'use strict'; - /** - * Legacy settings. - * @namespace - * @memberof Polymer - */ const settings = Polymer.Settings || {}; settings.useShadow = !(window.ShadyDOM); settings.useNativeCSSProperties = @@ -32,6 +27,7 @@ * Sets the global, legacy settings. * * @deprecated + * @namespace * @memberof Polymer */ Polymer.Settings = settings; diff --git a/lib/utils/templatize.html b/lib/utils/templatize.html index c4290724e2..28810322f1 100644 --- a/lib/utils/templatize.html +++ b/lib/utils/templatize.html @@ -257,6 +257,7 @@ /** * @constructor * @extends {base} + * @private */ let klass = class extends base { }; klass.prototype.__templatizeOptions = options; @@ -464,6 +465,7 @@ // Host property forwarding must be installed onto template instance addPropagateEffects(template, templateInfo, options); // Subclass base class and add reference for this specific template + /** @private */ let klass = class TemplateInstance extends baseClass {}; klass.prototype._methodHost = findMethodHost(template); klass.prototype.__dataHost = template;