From 86d2eebcd5fa60eaa5e7ed4c5ca38ff892076146 Mon Sep 17 00:00:00 2001 From: Steven Orvell Date: Fri, 14 Apr 2017 12:23:09 -0700 Subject: [PATCH] Fix jsdoc issues. --- lib/elements/dom-module.html | 14 +++++++------- lib/elements/dom-repeat.html | 4 ++-- lib/legacy/class.html | 13 ++++++++----- lib/legacy/legacy-element-mixin.html | 24 ++++++++++++++++++------ lib/legacy/templatizer-behavior.html | 3 ++- lib/utils/array-splice.html | 25 +++++++++++++++++++++++++ lib/utils/mixin.html | 3 +++ lib/utils/path.html | 8 ++++++-- lib/utils/style-gather.html | 3 ++- lib/utils/templatize.html | 14 ++++++++++++-- test/unit/shady.html | 2 +- 11 files changed, 86 insertions(+), 27 deletions(-) diff --git a/lib/elements/dom-module.html b/lib/elements/dom-module.html index 467b857336..29c0c1ae09 100644 --- a/lib/elements/dom-module.html +++ b/lib/elements/dom-module.html @@ -54,13 +54,13 @@ static get observedAttributes() { return ['id'] } /** - * Retrieves the dom specified by `selector` in the module specified by - * `id`. For example, this.import('foo', 'img'); - * @method register - * @param {string} id - * @param {string=} selector - * @return {Element} Returns the dom which matches `selector` in the module - * at the specified `id`. + * Retrieves the element specified by the css `selector` in the module + * registered by `id`. For example, this.import('foo', 'img'); + * @method import + * @param {string} id The id of the dom-module in which to search. + * @param {string=} selector The css selector by which to find the element. + * @return {Element} Returns the element which matches `selector` in the + * module registered at the specified `id`. */ static import(id, selector) { if (id) { diff --git a/lib/elements/dom-repeat.html b/lib/elements/dom-repeat.html index 0b7ee3f5f3..4a8ac93d84 100644 --- a/lib/elements/dom-repeat.html +++ b/lib/elements/dom-repeat.html @@ -448,8 +448,8 @@ } /** - * @param {function()} fn - * @param {number=} delay + * @param {function()} fn Function to debounce. + * @param {number=} delay Delay in ms to debounce by. */ __debounceRender(fn, delay) { this.__renderDebouncer = Polymer.Debouncer.debounce( diff --git a/lib/legacy/class.html b/lib/legacy/class.html index 3929697886..2b74a68be5 100644 --- a/lib/legacy/class.html +++ b/lib/legacy/class.html @@ -35,8 +35,10 @@ * to ensure that any legacy behaviors can rely on legacy Polymer API on * the underlying element. * - * @param {Object|Array} behaviors Behavior object or array of behaviors - * @param {HTMLElement} klass Element class + * @param {Object|Array} behaviors Behavior object or array of behaviors. + * @param {HTMLElement} klass Element class. + * @returns {HTMLElement} Returns a new Element class extended by the + * passed in `behaviors` and also by `Polymer.LegacyElementMixin`. * @memberof Polymer */ function mixinBehaviors(behaviors, klass) { @@ -105,9 +107,10 @@ } /** - * @param {Array} behaviors - * @param {Array=} list - * @param {Array=} exclude + * @param {Array} behaviors List of behaviors to flatten. + * @param {Array=} list Target list to flatten behaviors into. + * @param {Array=} exclude List of behaviors to exclude from the list. + * @returns {Array} Returns the list of flattened behaviors. */ function flattenBehaviors(behaviors, list, exclude) { list = list || []; diff --git a/lib/legacy/legacy-element-mixin.html b/lib/legacy/legacy-element-mixin.html index ad05eaebd6..dc1ab55fd5 100644 --- a/lib/legacy/legacy-element-mixin.html +++ b/lib/legacy/legacy-element-mixin.html @@ -192,6 +192,7 @@ * * @param {string} value String to deserialize * @param {*} type Type to deserialize the string to + * @returns {*} Returns the deserialized value in the `type` given. */ deserialize(value, type) { return this._deserializeValue(value, type); @@ -272,10 +273,15 @@ * * Note this method is provided as backward-compatible legacy API * only. It is not directly called by any Polymer features. - */ - chainObject(object, inherited) { - if (object && inherited && object !== inherited) { - object.__proto__ = inherited; + * @param {Object} object The object on which to set the prototype. + * @param {Object} prototype The prototype that will be set on the given + * `object`. + * @returns {Object} Returns the given `object` with its prototype set + * to the given `prototype` object. + */ + chainObject(object, prototype) { + if (object && prototype && object !== prototype) { + object.__proto__ = prototype; } return object; } @@ -582,8 +588,9 @@ /** * Returns the computed style value for the given property. - * @param {String} property - * @return {String} the computed value + * @param {String} property The css property name. + * @returns {String} Returns the computed css property value for the given + * `property`. */ getComputedStyleValue(property) { return styleInterface.getComputedStyleValue(this, property); @@ -610,6 +617,11 @@ * 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` + * @returns {Object} Returns a debouncer object on which exists the + * following methods: `isActive()` returns true if the debouncer is + * active; `cancel()` cancels the debouncer if it is active; + * `flush()` immediately invokes the debounced callback if the debouncer + * is active. */ debounce(jobName, callback, wait) { this._debouncers = this._debouncers || {}; diff --git a/lib/legacy/templatizer-behavior.html b/lib/legacy/templatizer-behavior.html index 653e52e5f8..8673bba042 100644 --- a/lib/legacy/templatizer-behavior.html +++ b/lib/legacy/templatizer-behavior.html @@ -87,7 +87,6 @@ * @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 {TemplateInstance} Description */ templatize(template, mutableData) { this._templatizerTemplate = template; @@ -109,6 +108,8 @@ * * @param {Object=} model Object containing initial property values to * populate into the template bindings. + * @return {TemplateInstanceBase} Returns the created instance of + * the template prepared by `templatize`. */ stamp(model) { return new this.ctor(model); diff --git a/lib/utils/array-splice.html b/lib/utils/array-splice.html index 34e45a65de..34bd0b7b0b 100644 --- a/lib/utils/array-splice.html +++ b/lib/utils/array-splice.html @@ -147,6 +147,23 @@ * Complexity: O(l * p) * l: The length of the current array * p: The length of the old array + * + * @param {Array} current The current "changed" array for which to + * calculate splices. + * @param {Integer} currentStart Starting index in the `current` array for + * which splices are calculated. + * @param {Integer} currentEnd Ending index in the `current` array for + * which splices are calculated. + * @param {Array} old The original "unchanged" array to compare `current` + * against to determine splices. + * @param {Integer} oldStart Starting index in the `old` array for + * which splices are calculated. + * @param {Integer} oldEnd Ending index in the `old` array for + * which splices are calculated. + * @return {Array} Returns an array of splice record objects. Each of these + * contains: `index` the location where the splice occurred; `removed` + * the array of removed items from this location; `addedCount` the number + * of items added at this location. */ calcSplices(current, currentStart, currentEnd, old, oldStart, oldEnd) { @@ -286,6 +303,14 @@ * non-shared portions of the arrays. * * @memberof Polymer.ArraySplice + * @param {Array} current The "changed" array for which splices will be + * calculated. + * @param {Array} previous The "unchanged" original array to compare + * `current` against to determine the splices. + * @return {Array} Returns an array of splice record objects. Each of these + * contains: `index` the location where the splice occurred; `removed` + * the array of removed items from this location; `addedCount` the number + * of items added at this location. */ calculateSplices(current, previous) { return ArraySplice.calculateSplices(current, previous); diff --git a/lib/utils/mixin.html b/lib/utils/mixin.html index 85a04b0e3a..0285f7782c 100644 --- a/lib/utils/mixin.html +++ b/lib/utils/mixin.html @@ -22,6 +22,9 @@ /** * Given a mixin producing function, memoize applications of mixin to base * @private + * @param {Object} mixin Mixin for which to create a caching mixin. + * @returns {Object} Returns a mixin which when applied multiple times to the + * same base will always return the same extended class. */ function cachingMixin(mixin) { return function(base) { diff --git a/lib/utils/path.html b/lib/utils/path.html index 869358d36e..2dfe89403c 100644 --- a/lib/utils/path.html +++ b/lib/utils/path.html @@ -76,8 +76,9 @@ * ``` * * @memberof Polymer.Path - * @param {string} path Path string - * @return {boolean} True if `path` is an ancestor of `base` + * @param {string} base Path string to test against. + * @param {string} path Path string to test. + * @return {boolean} True if `path` is an ancestor of `base`. */ isAncestor: function(base, path) { // base.startsWith(path + '.'); @@ -96,6 +97,9 @@ * ``` * * @memberof Polymer.Path + * @param {string} base Path string to test against. + * @param {string} path Path string to test. + * @return {boolean} True if `path` is a descendant of `base`. */ isDescendant: function(base, path) { // path.startsWith(base + '.'); diff --git a/lib/utils/style-gather.html b/lib/utils/style-gather.html index 1fb045f3bd..e18a347fc2 100644 --- a/lib/utils/style-gather.html +++ b/lib/utils/style-gather.html @@ -36,7 +36,8 @@ * Returns CSS text of styles in a space-separated list of `dom-module`s. * * @memberof Polymer.StyleGather - * @param {string} moduleIds + * @param {string} moduleIds List of dom-module id's within which to + * search for css. * @return {string} Concatenated CSS content from specified `dom-module`s */ cssFromModules(moduleIds) { diff --git a/lib/utils/templatize.html b/lib/utils/templatize.html index 383889faa7..82bb74e1c0 100644 --- a/lib/utils/templatize.html +++ b/lib/utils/templatize.html @@ -62,7 +62,10 @@ } } /** + * Configure the given `props` by calling `_setPendingProperty`. Also + * sets any properties stored in `__hostProps`. * @private + * @param {Object} props Object of property name-value pairs to set. */ _configureProperties(props) { let options = this.__templatizeOptions; @@ -113,6 +116,11 @@ } } /** + * Shows or hides the template instance top level child elements. For + * text nodes, `textContent` is removed while "hidden" and replaced when + * "shown." + * @param {boolean} hide Set to true to hide the children; + * set to false to show them. * @protected */ _showHideChildren(hide) { @@ -411,8 +419,9 @@ /** * Returns the template "model" associated with a given element, which * serves as the binding scope for the template instance the element is - * contained in. A template model is an instance of `Polymer.Base`, and - * should be used to manipulate data associated with this template instance. + * contained in. A template model is an instance of + * `TemplateInstanceBase`, and should be used to manipulate data + * associated with this template instance. * * Example: * @@ -423,6 +432,7 @@ * * @memberof Polymer.Templatize * @method modelForElement + * @param {HTMLElement} host * @param {HTMLElement} el Element for which to return a template model. * @return {TemplateInstanceBase} Template instance representing the * binding scope for the element diff --git a/test/unit/shady.html b/test/unit/shady.html index 72f4e4cd13..6fd4f8d0d9 100644 --- a/test/unit/shady.html +++ b/test/unit/shady.html @@ -29,7 +29,7 @@ }); }); -/** +/* * Test the `` element distribution algorithm by verifying the * resulting composed tree structure. */