Fix jsdoc issues.

Author: Steven Orvell

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

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(

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 || [];

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 || {};

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

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

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

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 + '.');

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

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