From a8105e55a42d5a7c04b08c402f247d8b7741d3ef Mon Sep 17 00:00:00 2001 From: 43081j <43081j@users.noreply.github.com> Date: Tue, 14 Nov 2017 21:48:13 +0000 Subject: [PATCH] add return jsdoc to void functions --- lib/elements/array-selector.html | 4 ++ lib/elements/dom-bind.html | 1 + lib/elements/dom-if.html | 1 + lib/elements/dom-module.html | 1 + lib/elements/dom-repeat.html | 1 + lib/legacy/legacy-element-mixin.html | 11 +++++ lib/legacy/polymer.dom.html | 2 + lib/legacy/templatizer-behavior.html | 1 + lib/mixins/element-mixin.html | 9 ++++ lib/mixins/property-accessors.html | 16 +++++- lib/mixins/property-effects.html | 50 +++++++++++++++++++ lib/mixins/template-stamp.html | 3 ++ lib/utils/async.html | 4 ++ lib/utils/debounce.html | 65 +++++++++++++------------ lib/utils/flattened-nodes-observer.html | 4 ++ lib/utils/flush.html | 2 + lib/utils/gestures.html | 45 +++++++++++++++-- lib/utils/render-status.html | 3 ++ lib/utils/settings.html | 3 ++ lib/utils/templatize.html | 3 ++ 20 files changed, 194 insertions(+), 35 deletions(-) diff --git a/lib/elements/array-selector.html b/lib/elements/array-selector.html index 9deba97345..680452cc8e 100644 --- a/lib/elements/array-selector.html +++ b/lib/elements/array-selector.html @@ -269,6 +269,7 @@ * Deselects the given item if it is already selected. * * @param {*} item Item from `items` array to deselect + * @return {void} */ deselect(item) { let idx = this.__selectedMap.get(item); @@ -291,6 +292,7 @@ * Deselects the given index if it is already selected. * * @param {number} idx Index from `items` array to deselect + * @return {void} */ deselectIndex(idx) { this.deselect(this.items[idx]); @@ -301,6 +303,7 @@ * deselect the item if already selected. * * @param {*} item Item from `items` array to select + * @return {void} */ select(item) { this.selectIndex(this.items.indexOf(item)); @@ -311,6 +314,7 @@ * deselect the item if already selected. * * @param {number} idx Index from `items` array to select + * @return {void} */ selectIndex(idx) { let item = this.items[idx]; diff --git a/lib/elements/dom-bind.html b/lib/elements/dom-bind.html index 508cfa79aa..6d1283989c 100644 --- a/lib/elements/dom-bind.html +++ b/lib/elements/dom-bind.html @@ -90,6 +90,7 @@ /** * Forces the element to render its content. This is typically only * necessary to call if HTMLImports with the async attribute are used. + * @return {void} */ render() { let template; diff --git a/lib/elements/dom-if.html b/lib/elements/dom-if.html index 246f9bef72..9da7f11356 100644 --- a/lib/elements/dom-if.html +++ b/lib/elements/dom-if.html @@ -140,6 +140,7 @@ * that multiple changes trigger only a single render. The render method * should be called if, for example, template rendering is required to * validate application state. + * @return {void} */ render() { Polymer.flush(); diff --git a/lib/elements/dom-module.html b/lib/elements/dom-module.html index 552d96e089..d18837c048 100644 --- a/lib/elements/dom-module.html +++ b/lib/elements/dom-module.html @@ -110,6 +110,7 @@ * when a dom-module is imperatively created. For * example, `document.createElement('dom-module').register('foo')`. * @param {string=} id The id at which to register the dom-module. + * @return {void} */ register(id) { id = id || this.id; diff --git a/lib/elements/dom-repeat.html b/lib/elements/dom-repeat.html index b989994fec..ec62e6a87c 100644 --- a/lib/elements/dom-repeat.html +++ b/lib/elements/dom-repeat.html @@ -496,6 +496,7 @@ * that multiple changes trigger only a single render. The render method * should be called if, for example, template rendering is required to * validate application state. + * @return {void} */ render() { // Queue this repeater, then flush all in order diff --git a/lib/legacy/legacy-element-mixin.html b/lib/legacy/legacy-element-mixin.html index 349a0b22f2..482dfeacd9 100644 --- a/lib/legacy/legacy-element-mixin.html +++ b/lib/legacy/legacy-element-mixin.html @@ -250,6 +250,7 @@ * @param {string} property Property name to reflect. * @param {string=} attribute Attribute name to reflect. * @param {*=} value Property value to reflect. + * @return {void} */ reflectPropertyToAttribute(property, attribute, value) { this._propertyToAttribute(property, attribute, value); @@ -264,6 +265,7 @@ * @param {*} value Value to serialize. * @param {string} attribute Attribute name to serialize to. * @param {Element} node Element to set attribute to. + * @return {void} */ serializeValueToAttribute(value, attribute, node) { this._valueToNodeAttribute(/** @type {Element} */ (node || this), value, attribute); @@ -382,6 +384,7 @@ * @param {Element} node Element to add event listener to. * @param {string} eventName Name of event to listen for. * @param {string} methodName Name of handler method on `this` to call. + * @return {void} */ listen(node, eventName, methodName) { node = /** @type {!Element} */ (node || this); @@ -407,6 +410,7 @@ * @param {string} eventName Name of event to stop listening to. * @param {string} methodName Name of handler method on `this` to not call anymore. + * @return {void} */ unlisten(node, eventName, methodName) { node = /** @type {!Element} */ (node || this); @@ -432,6 +436,7 @@ * Defaults to `all`. * @param {Element=} node Element to apply scroll direction setting. * Defaults to `this`. + * @return {void} */ setScrollDirection(direction, node) { Polymer.Gestures.setTouchAction(/** @type {Element} */ (node || this), DIRECTION_MAP[direction] || 'auto'); @@ -465,6 +470,7 @@ * Force this element to distribute its children to its local dom. * This should not be necessary as of Polymer 2.0.2 and is provided only * for backwards compatibility. + * @return {void} */ distributeContent() { if (window.ShadyDOM && this.shadowRoot) { @@ -677,6 +683,7 @@ * Immediately calls the debouncer `callback` and inactivates it. * * @param {string} jobName The name of the debouncer started with `debounce` + * @return {void} */ flushDebouncer(jobName) { this._debouncers = this._debouncers || {}; @@ -690,6 +697,7 @@ * Cancels an active debouncer. The `callback` will not be called. * * @param {string} jobName The name of the debouncer started with `debounce` + * @return {void} */ cancelDebouncer(jobName) { this._debouncers = this._debouncers || {}; @@ -721,6 +729,7 @@ * * @param {number} handle Handle returned from original `async` call to * cancel. + * @return {void} */ cancelAsync(handle) { handle < 0 ? Polymer.Async.microTask.cancel(~handle) : @@ -833,6 +842,7 @@ * @param {string} transformText Transform setting. * @param {Element=} node Element to apply the transform to. * Defaults to `this` + * @return {void} */ transform(transformText, node) { node = /** @type {Element} */ (node || this); @@ -849,6 +859,7 @@ * @param {number} z Z offset. * @param {Element=} node Element to apply the transform to. * Defaults to `this`. + * @return {void} */ translate3d(x, y, z, node) { node = /** @type {Element} */ (node || this); diff --git a/lib/legacy/polymer.dom.html b/lib/legacy/polymer.dom.html index 54125e847e..85345ddb70 100644 --- a/lib/legacy/polymer.dom.html +++ b/lib/legacy/polymer.dom.html @@ -68,6 +68,7 @@ * * @param {Polymer.FlattenedNodesObserver} observerHandle Observer instance * to disconnect. + * @return {void} */ unobserveNodes(observerHandle) { observerHandle.disconnect(); @@ -75,6 +76,7 @@ /** * Provided as a backwards-compatible API only. This method does nothing. + * @return {void} */ notifyObserver() {} diff --git a/lib/legacy/templatizer-behavior.html b/lib/legacy/templatizer-behavior.html index dc240d9dfe..2721f8795a 100644 --- a/lib/legacy/templatizer-behavior.html +++ b/lib/legacy/templatizer-behavior.html @@ -100,6 +100,7 @@ * @param {boolean=} mutableData When `true`, the generated class will skip * strict dirty-checking for objects and arrays (always consider them to * be "dirty"). Defaults to false. + * @return {void} * @this {TemplatizerUser} */ templatize(template, mutableData) { diff --git a/lib/mixins/element-mixin.html b/lib/mixins/element-mixin.html index 2f53bc8e34..7f26212c3e 100644 --- a/lib/mixins/element-mixin.html +++ b/lib/mixins/element-mixin.html @@ -229,6 +229,7 @@ * and calling `klass.finalize()`. * * @param {PolymerElementConstructor} klass Element class + * @return {void} * @private */ function finalizeClassAndSuper(klass) { @@ -247,6 +248,7 @@ * `template` for stamping. * * @param {PolymerElementConstructor} klass Element class + * @return {void} * @private */ function finalizeClass(klass) { @@ -287,6 +289,7 @@ * and effects to * @param {Object} properties Flattened bag of property descriptors for * this class + * @return {void} * @private */ function finalizeProperties(proto, properties) { @@ -305,6 +308,7 @@ * @param {Object} dynamicFns Object containing keys for any properties * that are functions and should trigger the effect when the function * reference is changed + * @return {void} * @private */ function finalizeObservers(proto, observers, dynamicFns) { @@ -369,6 +373,7 @@ * Supported keys: * @param {Object} allProps Flattened map of all properties defined in this * element (including inherited properties) + * @return {void} * @private */ function createPropertyFromConfig(proto, name, info, allProps) { @@ -468,6 +473,7 @@ * creating property accessors and any property effect metadata needed for * the features used. * + * @return {void} * @public */ static finalize() { @@ -626,6 +632,7 @@ * style scoping. * * @param {string} is Tag name (or type extension name) for this element + * @return {void} * @protected */ static _finalizeTemplate(is) { @@ -766,6 +773,7 @@ * * @param {Object=} properties Bag of custom property key/values to * apply to this element. + * @return {void} * @suppress {invalidCasts} */ updateStyles(properties) { @@ -873,6 +881,7 @@ * * @param {Object=} props Bag of custom property key/values to * apply to the document. + * @return {void} */ Polymer.updateStyles = function(props) { if (window.ShadyCSS) { diff --git a/lib/mixins/property-accessors.html b/lib/mixins/property-accessors.html index 15900ab7bc..fdae8380c3 100644 --- a/lib/mixins/property-accessors.html +++ b/lib/mixins/property-accessors.html @@ -46,6 +46,7 @@ * * @param {Object} model Prototype or instance * @param {string} property Name of property + * @return {void} * @private */ function saveAccessorValue(model, property) { @@ -110,6 +111,7 @@ * Attribute names are mapped to property names using the `dash-case` to * `camelCase` convention * + * @return {void} */ static createPropertiesForAttributes() { let a$ = this.observedAttributes; @@ -165,6 +167,7 @@ * Provided as an override point for performing any setup work prior * to initializing the property accessor system. * + * @return {void} * @protected */ _initializeProperties() { @@ -202,6 +205,7 @@ * * @param {Object} props Bag of property values that were overwritten * when creating property accessors. + * @return {void} * @protected */ _initializeProtoProperties(props) { @@ -220,6 +224,7 @@ * * @param {Object} props Bag of property values that were overwritten * when creating property accessors. + * @return {void} * @protected */ _initializeInstanceProperties(props) { @@ -233,6 +238,7 @@ * * @param {string} attribute Name of attribute to ensure is set. * @param {string} value of the attribute. + * @return {void} */ _ensureAttribute(attribute, value) { if (!this.hasAttribute(attribute)) { @@ -249,6 +255,7 @@ * @param {string} attribute Name of attribute to deserialize. * @param {?string} value of the attribute. * @param {*=} type type to deserialize to. + * @return {void} */ _attributeToProperty(attribute, value, type) { // Don't deserialize back to property if currently reflecting @@ -264,6 +271,7 @@ * @param {string} property Property name to reflect. * @param {string=} attribute Attribute name to reflect. * @param {*=} value Property value to refect. + * @return {void} */ _propertyToAttribute(property, attribute, value) { this.__serializing = true; @@ -284,6 +292,7 @@ * @param {Element} node Element to set attribute to. * @param {*} value Value to serialize. * @param {string} attribute Attribute name to serialize to. + * @return {void} */ _valueToNodeAttribute(node, value, attribute) { let str = this._serializeValue(value); @@ -407,6 +416,7 @@ * @param {string} property Name of the property * @param {boolean=} readOnly When true, no setter is created; the * protected `_setProperty` function must be used to set the property + * @return {void} * @protected */ _createPropertyAccessor(property, readOnly) { @@ -447,6 +457,7 @@ * * @param {string} property Name of the property * @param {*} value Value to set + * @return {void} * @protected */ _setProperty(property, value) { @@ -499,6 +510,7 @@ * Marks the properties as invalid, and enqueues an async * `_propertiesChanged` callback. * + * @return {void} * @protected */ _invalidateProperties() { @@ -520,6 +532,8 @@ * For elements, generally `connectedCallback` is a normal spot to do so. * It is safe to call this method multiple times as it only turns on * property accessors once. + * + * @return {void} */ _enableProperties() { if (!this.__dataEnabled) { @@ -538,7 +552,7 @@ * set), and resets the pending set of changes. Generally, this method * should not be called in user code. * - * + * @return {void} * @protected */ _flushProperties() { diff --git a/lib/mixins/property-effects.html b/lib/mixins/property-effects.html index dc4bffa2cb..6954439941 100644 --- a/lib/mixins/property-effects.html +++ b/lib/mixins/property-effects.html @@ -205,6 +205,7 @@ * @param {Object} props Bag of current property changes * @param {Object} oldProps Bag of previous values for changed properties * @param {?} info Effect metadata + * @return {void} * @private */ function runObserverEffect(inst, property, props, oldProps, info) { @@ -232,6 +233,7 @@ * @param {Object} props Bag of current property changes * @param {Object} oldProps Bag of previous values for changed properties * @param {boolean} hasPaths True with `props` contains one or more paths + * @return {void} * @private */ function runNotifyEffects(inst, notifyProps, props, oldProps, hasPaths) { @@ -287,6 +289,7 @@ * @param {*} value The value of the changed property * @param {string | null | undefined} path If a sub-path of this property changed, the path * that changed (optional). + * @return {void} * @private * @suppress {invalidCasts} */ @@ -313,6 +316,7 @@ * @param {Object} oldProps Bag of previous values for changed properties * @param {?} info Effect metadata * @param {boolean} hasPaths True with `props` contains one or more paths + * @return {void} * @private */ function runNotifyEffect(inst, property, props, oldProps, info, hasPaths) { @@ -339,6 +343,7 @@ * @param {string} fromProp Child element property that was bound * @param {string} toPath Host property/path that was bound * @param {boolean} negate Whether the binding was negated + * @return {void} * @private */ function handleNotification(event, inst, fromProp, toPath, negate) { @@ -370,6 +375,7 @@ * @param {Object} props Bag of current property changes * @param {Object} oldProps Bag of previous values for changed properties * @param {?} info Effect metadata + * @return {void} * @private */ function runReflectEffect(inst, property, props, oldProps, info) { @@ -394,6 +400,7 @@ * @param {!Object} changedProps Bag of changed properties * @param {!Object} oldProps Bag of previous values for changed properties * @param {boolean} hasPaths True with `props` contains one or more paths + * @return {void} * @private */ function runComputedEffects(inst, changedProps, oldProps, hasPaths) { @@ -419,6 +426,7 @@ * @param {Object} props Bag of current property changes * @param {Object} oldProps Bag of previous values for changed properties * @param {?} info Effect metadata + * @return {void} * @private */ function runComputedEffect(inst, property, props, oldProps, info) { @@ -438,6 +446,7 @@ * @param {!PropertyEffectsType} inst The instance whose props are changing * @param {string | !Array<(string|number)>} path Path that has changed * @param {*} value Value of changed path + * @return {void} * @private */ function computeLinkedPaths(inst, path, value) { @@ -473,6 +482,7 @@ * @param {string=} literal Literal text surrounding binding parts (specified * only for 'property' bindings, since these must be initialized as part * of boot-up) + * @return {void} * @private */ function addBinding(constructor, templateInfo, nodeInfo, kind, target, parts, literal) { @@ -505,6 +515,7 @@ * @param {!Binding} binding Binding metadata * @param {!BindingPart} part Binding part metadata * @param {number} index Index into `nodeInfoList` for this node + * @return {void} */ function addEffectForBindingPart(constructor, templateInfo, binding, part, index) { if (!part.literal) { @@ -546,6 +557,7 @@ * @param {boolean} hasPaths True with `props` contains one or more paths * @param {Array} nodeList List of nodes associated with `nodeInfoList` template * metadata + * @return {void} * @private */ function runBindingEffect(inst, path, props, oldProps, info, hasPaths, nodeList) { @@ -578,6 +590,7 @@ * @param {!Binding} binding Binding metadata * @param {!BindingPart} part Binding part metadata * @param {*} value Value to set + * @return {void} * @private */ function applyBindingValue(inst, node, binding, part, value) { @@ -658,6 +671,7 @@ * * @param {!PropertyEffectsType} inst Instance that bas been previously bound * @param {TemplateInfo} templateInfo Template metadata + * @return {void} * @private */ function setupBindings(inst, templateInfo) { @@ -691,6 +705,7 @@ * * @param {Node} node Bound node to initialize * @param {Binding} binding Binding metadata + * @return {void} * @private */ function setupCompoundStorage(node, binding) { @@ -719,6 +734,7 @@ * @param {Object} node Child element to add listener to * @param {!PropertyEffectsType} inst Host element instance to handle notification event * @param {Binding} binding Binding metadata + * @return {void} * @private */ function addNotifyListener(node, inst, binding) { @@ -746,6 +762,7 @@ * @param {boolean|Object=} dynamicFn Boolean or object map indicating whether * method names should be included as a dependency to the effect. Note, * defaults to true if the signature is static (sig.static is true). + * @return {void} * @private */ function createMethodEffect(model, sig, type, effectFn, methodInfo, dynamicFn) { @@ -1010,6 +1027,7 @@ * @param {Array} array The array the mutations occurred on * @param {string} path The path to the array that was mutated * @param {Array} splices Array of splice records + * @return {void} * @private */ function notifySplices(inst, array, path, splices) { @@ -1032,6 +1050,7 @@ * @param {number} index Index at which the array mutation occurred * @param {number} addedCount Number of added items * @param {Array} removed Array of removed items + * @return {void} * @private */ function notifySplice(inst, array, path, index, addedCount, removed) { @@ -1216,6 +1235,7 @@ * @param {string} property Property that should trigger the effect * @param {string} type Effect type, from this.PROPERTY_EFFECT_TYPES * @param {Object=} effect Effect metadata object + * @return {void} * @protected */ _addPropertyEffect(property, type, effect) { @@ -1234,6 +1254,7 @@ * @param {string} property Property the effect was associated with * @param {string} type Effect type, from this.PROPERTY_EFFECT_TYPES * @param {Object=} effect Effect metadata object to remove + * @return {void} */ _removePropertyEffect(property, type, effect) { let effects = ensureOwnEffectMap(this, type)[property]; @@ -1387,6 +1408,7 @@ * @param {Node} node The node to set a property on * @param {string} prop The property to set * @param {*} value The value to set + * @return {void} * @protected */ _setUnmanagedPropertyToNode(node, prop, value) { @@ -1497,6 +1519,7 @@ * `_flushClients`. * * @param {Object} client PropertyEffects client to enqueue + * @return {void} * @protected */ _enqueueClient(client) { @@ -1510,6 +1533,7 @@ * Flushes any clients previously enqueued via `_enqueueClient`, causing * their `_flushProperties` method to run. * + * @return {void} * @protected */ _flushClients() { @@ -1557,6 +1581,7 @@ * `_flushProperties` call on client dom and before any element * observers are called. * + * @return {void} * @protected */ _readyClients() { @@ -1575,6 +1600,7 @@ * @param {boolean=} setReadOnly When true, any private values set in * `props` will be set. By default, `setProperties` will not set * `readOnly: true` root properties. + * @return {void} * @public */ setProperties(props, setReadOnly) { @@ -1666,6 +1692,7 @@ * @param {Object} changedProps Bag of changed properties * @param {Object} oldProps Bag of previous values for changed properties * @param {boolean} hasPaths True with `props` contains one or more paths + * @return {void} * @protected */ _propagatePropertyChanges(changedProps, oldProps, hasPaths) { @@ -1686,6 +1713,7 @@ * * @param {string | !Array} to Target path to link. * @param {string | !Array} from Source path to link. + * @return {void} * @public */ linkPaths(to, from) { @@ -1702,6 +1730,7 @@ * linking the paths. * * @param {string | !Array} path Target path to unlink. + * @return {void} * @public */ unlinkPaths(path) { @@ -1738,6 +1767,7 @@ * Note that splice records _must_ be normalized such that they are * reported in index order (raw results from `Object.observe` are not * ordered and must be normalized/merged before notifying). + * @return {void} * @public */ notifySplices(path, splices) { @@ -1787,6 +1817,7 @@ * @param {*} value Value to set at the specified path. * @param {Object=} root Root object from which the path is evaluated. * When specified, no notification will occur. + * @return {void} * @public */ set(path, value, root) { @@ -1944,6 +1975,7 @@ * * @param {string} path Path that should be notified. * @param {*=} value Value at the path (optional). + * @return {void} * @public */ notifyPath(path, value) { @@ -1973,6 +2005,7 @@ * @param {string} property Property name * @param {boolean=} protectedSetter Creates a custom protected setter * when `true`. + * @return {void} * @protected */ _createReadOnlyProperty(property, protectedSetter) { @@ -1993,6 +2026,7 @@ * @param {string} methodName Name of observer method to call * @param {boolean=} dynamicFn Whether the method name should be included as * a dependency to the effect. + * @return {void} * @protected */ _createPropertyObserver(property, methodName, dynamicFn) { @@ -2015,6 +2049,7 @@ * @param {string} expression Method expression * @param {boolean|Object=} dynamicFn Boolean or object map indicating * whether method names should be included as a dependency to the effect. + * @return {void} * @protected */ _createMethodObserver(expression, dynamicFn) { @@ -2031,6 +2066,7 @@ * full API docs. * * @param {string} property Property name + * @return {void} * @protected */ _createNotifyingProperty(property) { @@ -2049,6 +2085,7 @@ * full API docs. * * @param {string} property Property name + * @return {void} * @protected */ _createReflectedProperty(property) { @@ -2075,6 +2112,7 @@ * @param {string} expression Method expression * @param {boolean|Object=} dynamicFn Boolean or object map indicating * whether method names should be included as a dependency to the effect. + * @return {void} * @protected */ _createComputedProperty(property, expression, dynamicFn) { @@ -2120,6 +2158,7 @@ * @param {string} property Property that should trigger the effect * @param {string} type Effect type, from this.PROPERTY_EFFECT_TYPES * @param {Object=} effect Effect metadata object + * @return {void} * @protected */ static addPropertyEffect(property, type, effect) { @@ -2133,6 +2172,7 @@ * @param {string} methodName Name of observer method to call * @param {boolean=} dynamicFn Whether the method name should be included as * a dependency to the effect. + * @return {void} * @protected */ static createPropertyObserver(property, methodName, dynamicFn) { @@ -2148,6 +2188,7 @@ * * @param {string} expression Method expression * @param {boolean|Object=} dynamicFn Boolean or object map indicating + * @return {void} * whether method names should be included as a dependency to the effect. * @protected */ @@ -2160,6 +2201,7 @@ * events to notify of changes to the property. * * @param {string} property Property name + * @return {void} * @protected */ static createNotifyingProperty(property) { @@ -2179,6 +2221,7 @@ * @param {string} property Property name * @param {boolean=} protectedSetter Creates a custom protected setter * when `true`. + * @return {void} * @protected */ static createReadOnlyProperty(property, protectedSetter) { @@ -2190,6 +2233,7 @@ * to a (dash-cased) attribute of the same name. * * @param {string} property Property name + * @return {void} * @protected */ static createReflectedProperty(property) { @@ -2207,6 +2251,7 @@ * @param {string} expression Method expression * @param {boolean|Object=} dynamicFn Boolean or object map indicating whether * method names should be included as a dependency to the effect. + * @return {void} * @protected */ static createComputedProperty(property, expression, dynamicFn) { @@ -2288,6 +2333,7 @@ * @param {Object} templateInfo Template metadata to add effect to * @param {string} prop Property that should trigger the effect * @param {Object=} effect Effect metadata object + * @return {void} * @protected */ static _addTemplatePropertyEffect(templateInfo, prop, effect) { @@ -2351,6 +2397,7 @@ * * @param {!StampedTemplate} dom DocumentFragment previously returned * from `_stampTemplate` associated with the nodes to be removed + * @return {void} * @protected */ _removeBoundDom(dom) { @@ -2662,6 +2709,7 @@ /** * @param {*} inst Instance to add to hostStack + * @return {void} * @this {hostStack} */ registerHost(inst) { @@ -2673,6 +2721,7 @@ /** * @param {*} inst Instance to begin hosting + * @return {void} * @this {hostStack} */ beginHosting(inst) { @@ -2681,6 +2730,7 @@ /** * @param {*} inst Instance to end hosting + * @return {void} * @this {hostStack} */ endHosting(inst) { diff --git a/lib/mixins/template-stamp.html b/lib/mixins/template-stamp.html index a848dc0034..a8cf993534 100644 --- a/lib/mixins/template-stamp.html +++ b/lib/mixins/template-stamp.html @@ -254,6 +254,7 @@ * @param {Node} root Root node whose `childNodes` will be parsed * @param {!TemplateInfo} templateInfo Template metadata for current template * @param {!NodeInfo} nodeInfo Node metadata for current template. + * @return {void} */ static _parseTemplateChildNodes(root, templateInfo, nodeInfo) { if (root.localName === 'script' || root.localName === 'style') { @@ -462,6 +463,7 @@ * @param {Node} node Node to add event listener to * @param {string} eventName Name of event * @param {Function} handler Listener function to add + * @return {void} */ _addEventListenerToNode(node, eventName, handler) { node.addEventListener(eventName, handler); @@ -473,6 +475,7 @@ * @param {Node} node Node to remove event listener from * @param {string} eventName Name of event * @param {Function} handler Listener function to remove + * @return {void} */ _removeEventListenerFromNode(node, eventName, handler) { node.removeEventListener(eventName, handler); diff --git a/lib/utils/async.html b/lib/utils/async.html index 1283856349..93539de62b 100644 --- a/lib/utils/async.html +++ b/lib/utils/async.html @@ -89,6 +89,7 @@ * * @memberof Polymer.Async.timeOut * @param {number} handle Handle returned from `run` of callback to cancel + * @return {void} */ cancel: window.clearTimeout.bind(window) }, @@ -114,6 +115,7 @@ * * @memberof Polymer.Async.timeOut * @param {number} handle Handle returned from `run` of callback to cancel + * @return {void} */ cancel: window.cancelAnimationFrame.bind(window) }, @@ -144,6 +146,7 @@ * * @memberof Polymer.Async.idlePeriod * @param {number} handle Handle returned from `run` of callback to cancel + * @return {void} */ cancel(handle) { window.cancelIdleCallback ? @@ -186,6 +189,7 @@ * * @memberof Polymer.Async.microTask * @param {number} handle Handle returned from `run` of callback to cancel + * @return {void} */ cancel(handle) { const idx = handle - microtaskLastHandle; diff --git a/lib/utils/debounce.html b/lib/utils/debounce.html index 7fff476678..bdffe012ce 100644 --- a/lib/utils/debounce.html +++ b/lib/utils/debounce.html @@ -35,6 +35,7 @@ * * @param {!AsyncModule} asyncModule Object with Async interface. * @param {function()} callback Callback to run. + * @return {void} */ setConfig(asyncModule, callback) { this._asyncModule = asyncModule; @@ -46,6 +47,8 @@ } /** * Cancels an active debouncer and returns a reference to itself. + * + * @return {void} */ cancel() { if (this.isActive()) { @@ -55,6 +58,8 @@ } /** * Flushes an active debouncer and returns a reference to itself. + * + * @return {void} */ flush() { if (this.isActive()) { @@ -70,36 +75,36 @@ isActive() { return this._timer != null; } - /** - * Creates a debouncer if no debouncer is passed as a parameter - * 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 {Debouncer?} debouncer Debouncer object. - * @param {!AsyncModule} asyncModule Object with Async interface - * @param {function()} callback Callback to run. - * @return {!Debouncer} Returns a debouncer object. - */ + /** + * Creates a debouncer if no debouncer is passed as a parameter + * 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 {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, callback) { if (debouncer instanceof Debouncer) { debouncer.cancel(); diff --git a/lib/utils/flattened-nodes-observer.html b/lib/utils/flattened-nodes-observer.html index 5ea0085a4e..f5985229ac 100644 --- a/lib/utils/flattened-nodes-observer.html +++ b/lib/utils/flattened-nodes-observer.html @@ -106,6 +106,8 @@ * Activates an observer. This method is automatically called when * a `FlattenedNodesObserver` is created. It should only be called to * re-activate an observer that has been deactivated via the `disconnect` method. + * + * @return {void} */ connect() { if (isSlot(this._target)) { @@ -133,6 +135,8 @@ * the observer callback will not be called when changes to flattened nodes * occur. The `connect` method may be subsequently called to reactivate * the observer. + * + * @return {void} */ disconnect() { if (isSlot(this._target)) { diff --git a/lib/utils/flush.html b/lib/utils/flush.html index 331442292d..4cfcee7b3c 100644 --- a/lib/utils/flush.html +++ b/lib/utils/flush.html @@ -19,6 +19,7 @@ * * @memberof Polymer * @param {Polymer.Debouncer} debouncer Debouncer to enqueue + * @return {void} */ Polymer.enqueueDebouncer = function(debouncer) { debouncerQueue.push(debouncer); @@ -44,6 +45,7 @@ * - ShadyDOM distribution * * @memberof Polymer + * @return {void} */ Polymer.flush = function() { let shadyDOM, debouncers; diff --git a/lib/utils/gestures.html b/lib/utils/gestures.html index b741455a9d..455dff95c7 100644 --- a/lib/utils/gestures.html +++ b/lib/utils/gestures.html @@ -126,6 +126,7 @@ /** * @param {boolean=} setup True to add, false to remove. + * @return {void} */ function setupTeardownMouseCanceller(setup) { let events = IS_TOUCH_ONLY ? ['click'] : MOUSE_EVENTS; @@ -321,6 +322,7 @@ /** * @private * @param {Event} ev Event. + * @return {void} */ _handleNative: function(ev) { let handled; @@ -382,6 +384,7 @@ /** * @private * @param {TouchEvent} ev Event. + * @return {void} */ _handleTouchAction: function(ev) { let t = ev.changedTouches[0]; @@ -460,6 +463,7 @@ * @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} * @this {Gestures} */ _add: function(node, evType, handler) { @@ -500,6 +504,7 @@ * @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} * @this {Gestures} */ _remove: function(node, evType, handler) { @@ -530,6 +535,7 @@ * * @memberof Polymer.Gestures * @param {GestureRecognizer} recog Gesture recognizer descriptor + * @return {void} * @this {Gestures} */ register: function(recog) { @@ -567,6 +573,7 @@ * @memberof Polymer.Gestures * @param {Element} node Node to set touch action setting on * @param {string} value Touch action value + * @return {void} */ setTouchAction: function(node, value) { if (HAS_NATIVE_TA) { @@ -582,6 +589,7 @@ * @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. + * @return {void} */ _fire: function(target, type, detail) { let ev = new Event(type, { bubbles: true, cancelable: true, composed: true }); @@ -601,6 +609,7 @@ * * @memberof Polymer.Gestures * @param {string} evName Event name. + * @return {void} * @this {Gestures} */ prevent: function(evName) { @@ -618,6 +627,7 @@ * Calling this method in production may cause duplicate taps or other Gestures. * * @memberof Polymer.Gestures + * @return {void} */ resetMouseCanceller: function() { if (POINTERSTATE.mouse.mouseIgnoreJob) { @@ -642,7 +652,10 @@ upfn: null }, - /** @this {GestureRecognizer} */ + /** + * @this {GestureRecognizer} + * @return {void} + */ reset: function() { untrackDocument(this.info); }, @@ -650,6 +663,7 @@ /** * @this {GestureRecognizer} * @param {MouseEvent} e + * @return {void} */ mousedown: function(e) { if (!hasLeftMouseButton(e)) { @@ -675,6 +689,7 @@ /** * @this {GestureRecognizer} * @param {TouchEvent} e + * @return {void} */ touchstart: function(e) { this._fire('down', Gestures._findOriginalTarget(e), e.changedTouches[0], e); @@ -682,6 +697,7 @@ /** * @this {GestureRecognizer} * @param {TouchEvent} e + * @return {void} */ touchend: function(e) { this._fire('up', Gestures._findOriginalTarget(e), e.changedTouches[0], e); @@ -691,6 +707,7 @@ * @param {EventTarget} target * @param {Event} event * @param {Function} preventer + * @return {void} */ _fire: function(type, target, event, preventer) { Gestures._fire(target, type, { @@ -733,7 +750,10 @@ prevent: false }, - /** @this {GestureRecognizer} */ + /** + * @this {GestureRecognizer} + * @return {void} + */ reset: function() { this.info.state = 'start'; this.info.started = false; @@ -764,6 +784,7 @@ /** * @this {GestureRecognizer} * @param {MouseEvent} e + * @return {void} */ mousedown: function(e) { if (!hasLeftMouseButton(e)) { @@ -806,6 +827,7 @@ /** * @this {GestureRecognizer} * @param {TouchEvent} e + * @return {void} */ touchstart: function(e) { let ct = e.changedTouches[0]; @@ -815,6 +837,7 @@ /** * @this {GestureRecognizer} * @param {TouchEvent} e + * @return {void} */ touchmove: function(e) { let t = Gestures._findOriginalTarget(e); @@ -834,6 +857,7 @@ /** * @this {GestureRecognizer} * @param {TouchEvent} e + * @return {void} */ touchend: function(e) { let t = Gestures._findOriginalTarget(e); @@ -851,6 +875,7 @@ * @this {GestureRecognizer} * @param {EventTarget} target * @param {Touch} touch + * @return {void} */ _fire: function(target, touch) { let secondlast = this.info.moves[this.info.moves.length - 2]; @@ -892,13 +917,20 @@ y: NaN, prevent: false }, - /** @this {GestureRecognizer} */ + /** + * @this {GestureRecognizer} + * @return {void} + */ reset: function() { this.info.x = NaN; this.info.y = NaN; this.info.prevent = false; }, - /** @this {GestureRecognizer} */ + /** + * @this {GestureRecognizer} + * @param {MouseEvent} e + * @return {void} + */ save: function(e) { this.info.x = e.clientX; this.info.y = e.clientY; @@ -906,6 +938,7 @@ /** * @this {GestureRecognizer} * @param {MouseEvent} e + * @return {void} */ mousedown: function(e) { if (hasLeftMouseButton(e)) { @@ -915,6 +948,7 @@ /** * @this {GestureRecognizer} * @param {MouseEvent} e + * @return {void} */ click: function(e) { if (hasLeftMouseButton(e)) { @@ -924,6 +958,7 @@ /** * @this {GestureRecognizer} * @param {TouchEvent} e + * @return {void} */ touchstart: function(e) { this.save(e.changedTouches[0], e); @@ -931,6 +966,7 @@ /** * @this {GestureRecognizer} * @param {TouchEvent} e + * @return {void} */ touchend: function(e) { this.forward(e.changedTouches[0], e); @@ -939,6 +975,7 @@ * @this {GestureRecognizer} * @param {Event | Touch} e * @param {Event=} preventer + * @return {void} */ forward: function(e, preventer) { let dx = Math.abs(e.clientX - this.info.x); diff --git a/lib/utils/render-status.html b/lib/utils/render-status.html index 6f44578908..6405f93973 100644 --- a/lib/utils/render-status.html +++ b/lib/utils/render-status.html @@ -87,6 +87,7 @@ * @param {*} context Context object the callback function will be bound to * @param {function()} callback Callback function * @param {Array} args An array of arguments to call the callback function with + * @return {void} */ beforeNextRender: function(context, callback, args) { if (!scheduled) { @@ -108,6 +109,7 @@ * @param {*} context Context object the callback function will be bound to * @param {function()} callback Callback function * @param {Array} args An array of arguments to call the callback function with + * @return {void} */ afterNextRender: function(context, callback, args) { if (!scheduled) { @@ -121,6 +123,7 @@ * tasks. * * @memberof Polymer.RenderStatus + * @return {void} */ flush: flush diff --git a/lib/utils/settings.html b/lib/utils/settings.html index 7d5163e848..a2c8cc30df 100644 --- a/lib/utils/settings.html +++ b/lib/utils/settings.html @@ -57,6 +57,7 @@ * * @memberof Polymer * @param {string} path The new root path + * @return {void} */ Polymer.setRootPath = function(path) { Polymer.rootPath = path; @@ -89,6 +90,7 @@ * * @memberof Polymer * @param {(function(*,string,string,Node):*)|undefined} newSanitizeDOMValue the global sanitizeDOMValue callback + * @return {void} */ Polymer.setSanitizeDOMValue = function(newSanitizeDOMValue) { Polymer.sanitizeDOMValue = newSanitizeDOMValue; @@ -111,6 +113,7 @@ * * @memberof Polymer * @param {boolean} usePassive enable or disable passive touch gestures globally + * @return {void} */ Polymer.setPassiveTouchGestures = function(usePassive) { Polymer.passiveTouchGestures = usePassive; diff --git a/lib/utils/templatize.html b/lib/utils/templatize.html index 8723f9c9b5..c4290724e2 100644 --- a/lib/utils/templatize.html +++ b/lib/utils/templatize.html @@ -92,6 +92,7 @@ * sets any properties stored in `__hostProps`. * @private * @param {Object} props Object of property name-value pairs to set. + * @return {void} */ _configureProperties(props) { let options = this.__templatizeOptions; @@ -115,6 +116,7 @@ * * @param {string} prop Property or path name * @param {*} value Value of the property to forward + * @return {void} */ forwardHostProp(prop, value) { if (this._setPendingPropertyOrPath(prop, value, false, true)) { @@ -147,6 +149,7 @@ * "shown." * @param {boolean} hide Set to true to hide the children; * set to false to show them. + * @return {void} * @protected */ _showHideChildren(hide) {