From 8a11c8c3f338f67ba4ae3cb61a586946c1719ac4 Mon Sep 17 00:00:00 2001
From: Kevin Schaaf <kschaaf@google.com>
Date: Fri, 14 Apr 2017 12:16:35 -0700
Subject: [PATCH] Fix jsdoc issues.

---
 lib/mixins/element-mixin.html      | 79 ++++++++++++++++++++----------
 lib/mixins/property-accessors.html |  1 +
 lib/mixins/property-effects.html   | 59 +++++++++++++---------
 lib/mixins/template-stamp.html     |  9 ++--
 4 files changed, 97 insertions(+), 51 deletions(-)

diff --git a/lib/mixins/element-mixin.html b/lib/mixins/element-mixin.html
index c24438407d..607c112dfc 100644
--- a/lib/mixins/element-mixin.html
+++ b/lib/mixins/element-mixin.html
@@ -126,7 +126,9 @@
      * (1) super chain mixes togther to make `propertiesForClass` which is
      * then used to make `observedAttributes`.
      * (2) properties effects and observers are created from it at `finalize` time.
-     * @param {HTMLElement} klass
+     *
+     * @param {HTMLElement} klass Element class
+     * @return {Object} Object containing own properties for this class
      * @private
      */
     function ownPropertiesForClass(klass) {
@@ -142,7 +144,9 @@
     /**
      * Returns the `observers` array specifically on `klass`. Use for
      * setting up observers.
-     * @param {HTMLElement} klass
+     *
+     * @param {HTMLElement} klass Element class
+     * @return {Array} Array containing own observers for this class
      * @private
      */
     function ownObserversForClass(klass) {
@@ -158,8 +162,10 @@
     /**
      * Mixes `props` into `flattenedProps` but upgrades shorthand type
      * syntax to { type: Type}.
-     * @param {Object} flattenedProps
-     * @param {Object} props
+     *
+     * @param {Object} flattenedProps Bag to collect flattened properties into
+     * @param {Object} props Bag of properties to add to `flattenedProps`
+     * @return {Objecg} The input `flattenedProps` bag
      * @private
      */
     function flattenProperties(flattenedProps, props) {
@@ -178,8 +184,9 @@
      * constructor's `config.properties`. This list is used to create
      * (1) observedAttributes,
      * (2) class property default values
-     * @param {HTMLElement} klass
-     * @return {PolymerElementProperties}
+     *
+     * @param {HTMLElement} klass Element class
+     * @return {PolymerElementProperties} Flattened properties for this class
      * @private
      */
     function propertiesForClass(klass) {
@@ -202,8 +209,10 @@
      * This list is created as an optimization since it is a subset of
      * the list returned from `propertiesForClass`.
      * This list is used in `_initializeProperties` to set property defaults.
-     * @param {HTMLElement} klass
-     * @return {PolymerElementProperties}
+     *
+     * @param {HTMLElement} klass Element class
+     * @return {PolymerElementProperties} Flattened properties for this class
+     *   that have default values
      * @private
      */
     function propertyDefaultsForClass(klass) {
@@ -224,7 +233,9 @@
 
     /**
      * Returns true if a `klass` has finalized. Called in `ElementClass.finalize()`
-     * @param {HTMLElement} klass
+     * @param {HTMLElement} klass Element class
+     * @return {boolean} True if all metaprogramming for this class has been
+     *   completed
      * @private
      */
     function hasClassFinalized(klass) {
@@ -235,7 +246,8 @@
      * Called by `ElementClass.finalize()`. Ensures this `klass` and
      * *all superclasses* are finalized by traversing the prototype chain
      * and calling `klass.finalize()`.
-     * @param {HTMLElement} klass
+     *
+     * @param {HTMLElement} klass Element class
      * @private
      */
     function finalizeClassAndSuper(klass) {
@@ -252,6 +264,9 @@
      * a `template`. This includes creating accessors and effects
      * for properties in `config` and the `template` as well as preparing the
      * `template` for stamping.
+     *
+     * @param {HTMLElement} klass Element class
+     * @private
      */
     function finalizeClass(klass) {
       klass.__finalized = true;
@@ -287,8 +302,10 @@
      * Leverages `PropertyEffects` to create property accessors and effects
      * supporting, observers, reflecting to attributes, change notification,
      * computed properties, and read only properties.
-     * @param {HTMLElement} proto
-     * @param {Object} properties
+     * @param {HTMLElement} proto Element class prototype to add accessors
+     *    and effects to
+     * @param {Object} properties Flattened bag of property descriptors for
+     *    this class
      * @private
      */
     function finalizeProperties(proto, properties) {
@@ -300,13 +317,18 @@
     /**
      * Configures a `proto` based on a `observers` array.
      * Leverages `PropertyEffects` to create observers.
-     * @param {HTMLElement} proto
-     * @param {Array} observers
+     * @param {HTMLElement} proto Element class prototype to add accessors
+     *   and effects to
+     * @param {Object} observers Flattened array of observer descriptors for
+     *   this class
+     * @param {Object} dynamicFns Object containing keys for any properties
+     *   that are functions and should trigger the effect when the function
+     *   reference is changed
      * @private
      */
-    function finalizeObservers(proto, observers, dynamicProperties) {
+    function finalizeObservers(proto, observers, dynamicFns) {
       for (let i=0; i < observers.length; i++) {
-        proto._createMethodObserver(observers[i], dynamicProperties);
+        proto._createMethodObserver(observers[i], dynamicFns);
       }
     }
 
@@ -359,7 +381,8 @@
      * and/or provide an advanced api for manipulating them.
      * Also consider adding warnings when an effect cannot be changed.
      *
-     * @param {HTMLElement} proto
+     * @param {HTMLElement} proto Element class prototype to add accessors
+     *   and effects to
      * @param {string} name Name of the property.
      * @param {object} info Info object from which to create property effects.
      * Supported keys:
@@ -399,12 +422,14 @@
      * Configures an element `proto` to function with a given `template`.
      * The element name `is` and extends `ext` must be specified for ShadyCSS
      * style scoping.
-     * @param {HTMLElement} proto
-     * @param {HTMLTemplateElement} template
+     *
+     * @param {HTMLElement} proto Element class prototype to add accessors
+     *   and effects to
+     * @param {HTMLTemplateElement} template Template to process and bind
      * @param {string} baseURI URL against which to resolve urls in
-     * style element cssText.
-     * @param {string} is
-     * @param {string} ext
+     *   style element cssText
+     * @param {string} is Tag name (or type extension name) for this element
+     * @param {string=} ext For type extensions, the tag name that was extended
      * @private
      */
     function finalizeTemplate(proto, template, baseURI, is, ext) {
@@ -470,7 +495,7 @@
       }
 
       /**
-       * Returns the template stamped into this element's shadow root.
+       * Returns the template that will be stamped into this element's shadow root.
        *
        * If a `static get is()` getter is defined, the default implementation
        * will return the first `<template>` in a `dom-module` whose `id`
@@ -504,7 +529,7 @@
        *     }
        *   }
        *
-       * @returns {HTMLTemplateElement|string}
+       * @returns {HTMLTemplateElement|string} Template to be stamped
        */
       static get template() {
         if (!this.hasOwnProperty(goog.reflect.objectProperty('_template', this))) {
@@ -526,7 +551,7 @@
        * matching this element's static `is` property.
        * Note, this path should contain a trailing `/`.
        *
-       * @returns {string}
+       * @returns {string} The import path for this element class
        */
       static get importPath() {
         if (!this.hasOwnProperty(goog.reflect.objectProperty('_importPath', this))) {
@@ -833,6 +858,7 @@
      */
     registrations: [],
     /**
+     * @param {HTMLElement} prototype Element prototype to log
      * @private
      */
     _regLog: function(prototype) {
@@ -840,6 +866,7 @@
     },
     /**
      * Registers a class prototype for telemetry purposes.
+     * @param {HTMLElement} prototype Element prototype to register
      * @protected
      */
     register: function(prototype) {
@@ -868,7 +895,7 @@
    *
    * These properties are retained unless a value of `null` is set.
    *
-   * @param {Object=} properties Bag of custom property key/values to
+   * @param {Object=} props Bag of custom property key/values to
    *   apply to the document.
    */
   Polymer.updateStyles = function(props) {
diff --git a/lib/mixins/property-accessors.html b/lib/mixins/property-accessors.html
index b15568e4c8..609b31c2cc 100644
--- a/lib/mixins/property-accessors.html
+++ b/lib/mixins/property-accessors.html
@@ -427,6 +427,7 @@
        *
        * @param {string} property Name of the property
        * @param {*} value Value to set
+       * @return {boolean} Returns true if the property changed
        * @protected
        */
       _setPendingProperty(property, value) {
diff --git a/lib/mixins/property-effects.html b/lib/mixins/property-effects.html
index c10078ae17..1a21f9212d 100644
--- a/lib/mixins/property-effects.html
+++ b/lib/mixins/property-effects.html
@@ -86,11 +86,12 @@
    * on an instance.
    *
    * @param {Object} inst The instance with effects to run
-   * @param {string} type Type of effect to run
+   * @param {string} effects Array of effects to run for this property
    * @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
    * @param {*=} extraArgs Additional metadata to pass to effect function
+   * @return {boolean} True if an effect ran for this property
    * @private
    */
   function runEffects(inst, effects, props, oldProps, hasPaths, extraArgs) {
@@ -117,6 +118,7 @@
    * @param {*} oldProps Old properties
    * @param {boolean=} hasPaths True with `props` contains one or more paths
    * @param {*=} extraArgs Additional metadata to pass to effect function
+   * @return {boolean} True if an effect ran for this property
    * @private
    */
   function runEffectsForProperty(inst, effects, dedupeId, prop, props, oldProps, hasPaths, extraArgs) {
@@ -175,8 +177,8 @@
    *
    * @param {Object} inst The instance the effect will be run on
    * @param {string} property Name of property
-   * @param {*} value Current value of property
-   * @param {*} old Previous value of property
+   * @param {Object} props Bag of current property changes
+   * @param {Object} oldProps Bag of previous values for changed properties
    * @param {Object} info Effect metadata
    * @private
    */
@@ -201,6 +203,7 @@
    * sent.
    *
    * @param {Element} inst The instance with effects to run
+   * @param {Object} notifyProps Bag of properties to notify
    * @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
@@ -234,7 +237,8 @@
    *
    * @param {Element} inst The element from which to fire the event
    * @param {string} path The path that was changed
-   * @param {*} value
+   * @param {Object} props Bag of current property changes
+   * @return {boolean} Returns true if the path was notified
    * @private
    */
   function notifyPath(inst, path, props) {
@@ -276,8 +280,8 @@
    *
    * @param {Element} inst The instance the effect will be run on
    * @param {string} property Name of property
-   * @param {*} value Current value of property
-   * @param {*} old Previous value of property
+   * @param {Object} props Bag of current property changes
+   * @param {Object} oldProps Bag of previous values for changed properties
    * @param {Object} info Effect metadata
    * @param {boolean} hasPaths True with `props` contains one or more paths
    * @private
@@ -301,7 +305,7 @@
    * the event contained path information, translate that path to the host
    * scope's name for that path first.
    *
-   * @param {Event} e Notification event (e.g. '<property>-changed')
+   * @param {Event} event Notification event (e.g. '<property>-changed')
    * @param {Object} inst Host element instance handling the notification event
    * @param {string} fromProp Child element property that was bound
    * @param {string} toPath Host property/path that was bound
@@ -334,8 +338,8 @@
    *
    * @param {Object} inst The instance the effect will be run on
    * @param {string} property Name of property
-   * @param {*} value Current value of property
-   * @param {*} old Previous value of property
+   * @param {Object} props Bag of current property changes
+   * @param {Object} oldProps Bag of previous values for changed properties
    * @param {Object} info Effect metadata
    * @private
    */
@@ -383,8 +387,8 @@
    *
    * @param {Object} inst The instance the effect will be run on
    * @param {string} property Name of property
-   * @param {*} value Current value of property
-   * @param {*} old Previous value of property
+   * @param {Object} props Bag of current property changes
+   * @param {Object} oldProps Bag of previous values for changed properties
    * @param {Object} info Effect metadata
    * @private
    */
@@ -514,11 +518,11 @@
    *
    * @param {Element} inst The instance the effect will be run on
    * @param {string} path Name of property
-   * @param {*} value Current value of property
-   * @param {*} old Previous value of property
+   * @param {Object} props Bag of current property changes
+   * @param {Object} oldProps Bag of previous values for changed properties
    * @param {Object} info Effect metadata
    * @param {boolean} hasPaths True with `props` contains one or more paths
-   * @param {Array} nodes List of nodes associated with `nodeInfoList` template
+   * @param {Array} nodeList List of nodes associated with `nodeInfoList` template
    *   metadata
    * @private
    */
@@ -548,7 +552,9 @@
    * either as a property or attribute.
    *
    * @param {Object} inst The instance owning the binding effect
-   * @param {Object} info Effect metadata
+   * @param {Node} node Target node for binding
+   * @param {Object} binding Binding metadata
+   * @param {Object} part Binding part metadata
    * @param {*} value Value to set
    * @private
    */
@@ -582,6 +588,7 @@
    * @param {Node} node Node the value will be set to
    * @param {*} value Value to set
    * @param {Object} binding Binding metadata
+   * @param {Object} part Binding part metadata
    * @return {*} Transformed value to set
    * @private
    */
@@ -660,7 +667,7 @@
    * the final value set to the property/attribute.
    *
    * @param {Node} node Bound node to initialize
-   * @param {Object} bindings Binding metadata
+   * @param {Object} binding Binding metadata
    * @private
    */
   function setupCompoundStorage(node, binding) {
@@ -688,7 +695,7 @@
    *
    * @param {Object} node Child element to add listener to
    * @param {Object} inst Host element instance to handle notification event
-   * @param {Object} info Listener metadata stored via addAnnotatedListener
+   * @param {Object} binding Binding metadata
    * @private
    */
   function addNotifyListener(node, inst, binding) {
@@ -709,9 +716,10 @@
    *
    * @param {Element | Object} model Prototype or instance
    * @param {Object} sig Method signature metadata
-   * @param {string} type
+   * @param {string} type Type of property effect to add
    * @param {Function} effectFn Function to run when arguments change
-   * @param {*=} methodInfo
+   * @param {*=} methodInfo Effect-specific information to be included in
+   *   method effect metadata
    * @param {Object=} dynamicFns Map indicating whether method names should
    *   be included as a dependency to the effect. Note, defaults to true
    *   if the signature is statci (sig.static is true).
@@ -749,9 +757,10 @@
    *
    * @param {Object} inst The instance the effect will be run on
    * @param {string} property Name of property
-   * @param {*} value Current value of property
-   * @param {*} old Previous value of property
+   * @param {Object} props Bag of current property changes
+   * @param {Object} oldProps Bag of previous values for changed properties
    * @param {Object} info Effect metadata
+   * @return {*} Returns the return value from the method invocation
    * @private
    */
   function runMethodEffect(inst, property, props, oldProps, info) {
@@ -918,6 +927,8 @@
    *
    * @param {Object} data Instance data storage object to read properties from
    * @param {Array<Object>} args Array of argument metadata
+   * @param {string} path Property/path name that triggered the method effect
+   * @param {Object} props Bag of current property changes
    * @return {Array<*>} Array of argument values
    * @private
    */
@@ -1166,7 +1177,7 @@
       /**
        * Removes the given property effect.
        *
-       * @param {string} path Property the effect was associated with
+       * @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
        */
@@ -1259,6 +1270,8 @@
        *
        * @param {string | !Array<number|string>} path Path to set
        * @param {*} value Value to set
+       * @param {boolean=} shouldNotify Set to true if this change should
+       *  cause a property notification event dispatch
        * @param {boolean=} isPathNotification If the path being set is a path
        *   notification of an already changed value, as opposed to a request
        *   to set and notify the change.  In the latter `false` case, a dirty
@@ -2046,6 +2059,7 @@
        *
        * The `effect` object should match the format in `_addPropertyEffect`.
        *
+       * @param {Object} templateInfo Template metadata to add effect to
        * @param {string} prop Property that should trigger the effect
        * @param {Object=} effect Effect metadata object
        * @protected
@@ -2342,6 +2356,7 @@
        * @param {HTMLElement} inst Element that should be used as scope for
        *   binding dependencies
        * @param {Object} part Binding part metadata
+       * @param {string} path Property/path that triggered this effect
        * @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
diff --git a/lib/mixins/template-stamp.html b/lib/mixins/template-stamp.html
index 67031ceea4..3b067a00a8 100644
--- a/lib/mixins/template-stamp.html
+++ b/lib/mixins/template-stamp.html
@@ -291,8 +291,9 @@
        * `_contentForTemplate` method to retrieve the content for this template
        * (an optimization to avoid the cost of cloning nested template content).
        *
-       * @param {Node} node Node to parse
-       * @param {Object} templateInfo Template metadata for current template
+       * @param {HTMLTemplateElement} node Node to parse (a <template>)
+       * @param {Object} outerTemplateInfo Template metadata for current template
+       *   that includes the template `node`
        * @param {Object} nodeInfo Node metadata for current template.
        * @return {boolean} `true` if the visited node added node-specific
        *   metadata to `nodeInfo`
@@ -338,7 +339,7 @@
        * @param {Object} templateInfo Template metadata for current template
        * @param {Object} nodeInfo Node metadata for current template.
        * @param {string} name Attribute name
-       * @param {string} name Attribute value
+       * @param {*} value Attribute value
        * @return {boolean} `true` if the visited node added node-specific
        *   metadata to `nodeInfo`
        */
@@ -429,6 +430,8 @@
        * @param {Node} node Node to add listener on
        * @param {string} eventName Name of event
        * @param {string} methodName Name of method
+       * @param {*=} context Context the method will be called on (defaults
+       *   to `node`)
        * @return {Function} Generated handler function
        */
       _addMethodEventListenerToNode(node, eventName, methodName, context) {