From 72a454e93f47f25b8646c4f30e9a33d108a638bf Mon Sep 17 00:00:00 2001
From: Kevin Schaaf <kschaaf@google.com>
Date: Fri, 14 Apr 2017 11:04:18 -0700
Subject: [PATCH 1/8] Enable error on jsdoc mistake.

---
 .eslintrc.json | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/.eslintrc.json b/.eslintrc.json
index 4ab15499c8..2f2f881d38 100644
--- a/.eslintrc.json
+++ b/.eslintrc.json
@@ -4,7 +4,10 @@
   "rules": {
     "no-console": "off",
     "no-var": "error",
-    "strict": "error"
+    "strict": "error",
+    "valid-jsdoc": ["error", {
+      "requireReturn": false
+    }]
   },
   "env": {
     "browser": true,

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 2/8] 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) {

From 86d2eebcd5fa60eaa5e7ed4c5ca38ff892076146 Mon Sep 17 00:00:00 2001
From: Steven Orvell <sorvell@google.com>
Date: Fri, 14 Apr 2017 12:23:09 -0700
Subject: [PATCH 3/8] 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 `<slot>` element distribution algorithm by verifying the
  * resulting composed tree structure.
  */

From 38a13f668498910384bf96e7ffc3bcc30439aa09 Mon Sep 17 00:00:00 2001
From: Steven Orvell <sorvell@google.com>
Date: Fri, 14 Apr 2017 12:45:18 -0700
Subject: [PATCH 4/8] jsdoc fixes.

---
 lib/utils/async.html    | 11 ++++++-----
 lib/utils/boot.html     |  6 ++++++
 lib/utils/debounce.html | 22 +++++++++++-----------
 lib/utils/gestures.html | 24 +++++++++++++++++++++++-
 4 files changed, 46 insertions(+), 17 deletions(-)

diff --git a/lib/utils/async.html b/lib/utils/async.html
index 6bcfbd4b61..d175ec9fd8 100644
--- a/lib/utils/async.html
+++ b/lib/utils/async.html
@@ -145,10 +145,10 @@
        * @memberof Polymer.Async.timeOut
        * @param {*} handle Handle returned from `run` of callback to cancel
        */
-      cancel(timer) {
-        return window.cancelIdleCallback ?
-          window.cancelIdleCallback(timer) :
-          window.clearTimeout(timer);
+      cancel(handle) {
+        window.cancelIdleCallback ?
+          window.cancelIdleCallback(handle) :
+          window.clearTimeout(handle);
       }
     },
 
@@ -172,7 +172,8 @@
        * Enqueues a function called at microtask timing.
        *
        * @memberof Polymer.Async.timeOut
-       * @param {Function} fn Callback to run
+       * @param {Function} callback Callback to run
+       * @return {*} Handle used for canceling task
        */
       run(callback) {
         microtaskNode.textContent = microtaskNodeContent++;
diff --git a/lib/utils/boot.html b/lib/utils/boot.html
index 677a295466..edefdce18d 100644
--- a/lib/utils/boot.html
+++ b/lib/utils/boot.html
@@ -18,6 +18,12 @@
    * @summary Polymer is a lightweight library built on top of the web
    * standards-based Web Components API's, and makes it easy to build your
    * own custom HTML elements.
+   * @param {Object} info Prototype for the custom element. It must contain
+   * an `is` property to specify the element name. Other properties populate
+   * the element prototype. The `properties`, `observers`, `hostAttributes`,
+   * and `listeners` properties are processed to create element features.
+   * @return {Object} Returns a custom element class for the given provided
+   * prototype `info` object. The name of the element if given by `info.is`.
    */
   window.Polymer = function(info) {
     return window.Polymer._polymerFn(info);
diff --git a/lib/utils/debounce.html b/lib/utils/debounce.html
index e32b9ffe57..dc8f66a796 100644
--- a/lib/utils/debounce.html
+++ b/lib/utils/debounce.html
@@ -29,12 +29,12 @@
      * a callback and optional arguments to be passed to the run function
      * from the async module.
      *
-     * @param {!AsyncModule} asyncModule
-     * @param {function()} callback
+     * @param {!AsyncModule} asyncModule Object with Async interface.
+     * @param {function()} callback Callback to run.
      */
-    setConfig(asyncModule, cb) {
+    setConfig(asyncModule, callback) {
       this._asyncModule = asyncModule;
-      this._callback = cb;
+      this._callback = callback;
       this._timer = this._asyncModule.run(() => {
         this._timer = null;
         this._callback()
@@ -61,7 +61,7 @@
     /**
      * Returns true if the debouncer is active.
      *
-     * @return {boolean}
+     * @return {boolean} True if active.
      */
     isActive() {
       return this._timer != null;
@@ -70,18 +70,18 @@
    * Creates a debouncer if no debouncer is passed as a parameter
    * or it cancels an active debouncer otherwise.
    *
-   * @param {Polymer.Debouncer?} debouncer
-   * @param {!AsyncModule} asyncModule
-   * @param {function()} cb
-   * @return {!Debouncer}
+   * @param {Polymer.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, cb) {
+    static debounce(debouncer, asyncModule, callback) {
       if (debouncer instanceof Debouncer) {
         debouncer.cancel();
       } else {
         debouncer = new Debouncer();
       }
-      debouncer.setConfig(asyncModule, cb);
+      debouncer.setConfig(asyncModule, callback);
       return debouncer;
     }
   }
diff --git a/lib/utils/gestures.html b/lib/utils/gestures.html
index 01f4660734..5d8183f848 100644
--- a/lib/utils/gestures.html
+++ b/lib/utils/gestures.html
@@ -86,7 +86,7 @@
   };
 
   /**
-   * @param {boolean=} setup
+   * @param {boolean=} setup True to add, false to remove.
    */
   function setupTeardownMouseCanceller(setup) {
     let events = IS_TOUCH_ONLY ? ['click'] : MOUSE_EVENTS;
@@ -235,6 +235,8 @@
      * @memberof Polymer.Gestures
      * @param {number} x Horizontal pixel coordinate
      * @param {number} y Vertical pixel coordinate
+     * @return {HTMLElement} Returns the deepest shadowRoot inclusive element
+     * found at the screen position given.
      */
     deepTargetFind: function(x, y) {
       let node = document.elementFromPoint(x, y);
@@ -260,6 +262,8 @@
      * a cheaper check than ev.composedPath()[0];
      *
      * @private
+     * @param {Event} ev Event.
+     * @returns {HTMLElement} Returns the event target.
      */
     _findOriginalTarget: function(ev) {
       // shadowdom
@@ -272,6 +276,7 @@
 
     /**
      * @private
+     * @param {Event} ev Event.
      */
     _handleNative: function(ev) {
       let handled;
@@ -332,6 +337,7 @@
 
     /**
      * @private
+     * @param {Event} ev Event.
      */
     _handleTouchAction: function(ev) {
       let t = ev.changedTouches[0];
@@ -373,6 +379,7 @@
      * @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
+     * @returns {boolean} Returns true if a gesture event listener was added.
      */
     addListener: function(node, evType, handler) {
       if (this.gestures[evType]) {
@@ -389,6 +396,7 @@
      * @param {string} evType Gesture type: `down`, `up`, `track`, or `tap`
      * @param {Function} handler Event listener function previously passed to
      *  `addListener`.
+     * @returns {boolean} Returns true if a gesture event listener was removed.
      */
     removeListener: function(node, evType, handler) {
       if (this.gestures[evType]) {
@@ -401,6 +409,9 @@
      * automate the event listeners for the native events
      *
      * @private
+     * @param {HTMLElement} node Node on which to add the event.
+     * @param {string} evType Event type to add.
+     * @param {function} handler Event handler function.
      */
     _add: function(node, evType, handler) {
       let recognizer = this.gestures[evType];
@@ -436,6 +447,9 @@
      * automate event listener removal for native events
      *
      * @private
+     * @param {HTMLElement} node Node on which to remove the event.
+     * @param {string} evType Event type to remove.
+     * @param {function} handler Event handler function.
      */
     _remove: function(node, evType, handler) {
       let recognizer = this.gestures[evType];
@@ -474,6 +488,8 @@
 
     /**
      * @private
+     * @param {string} evName Event name.
+     * @return {Object} Returns the gesture for the given event name.
      */
     _findRecognizerByEvent: function(evName) {
       for (let i = 0, r; i < this.recognizers.length; i++) {
@@ -506,7 +522,12 @@
     },
 
     /**
+     * Dispatches an event on the `target` element of `type` with the given
+     * `detail`.
      * @private
+     * @param {HTMLElement} 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.
      */
     _fire: function(target, type, detail) {
       let ev = new Event(type, { bubbles: true, cancelable: true, composed: true });
@@ -525,6 +546,7 @@
      * Prevents the dispatch and default action of the given event name.
      *
      * @memberof Polymer.Gestures
+     * @param {string} evName Event name.
      */
     prevent: function(evName) {
       let recognizer = this._findRecognizerByEvent(evName);

From dab794b2fe398a6239c7c74705b92e49fda3f5c6 Mon Sep 17 00:00:00 2001
From: Kevin Schaaf <kschaaf@google.com>
Date: Fri, 14 Apr 2017 14:01:26 -0700
Subject: [PATCH 5/8] Fix jsdoc warnings.

---
 lib/mixins/mutable-data.html | 10 ++++++----
 lib/utils/templatize.html    |  7 ++++---
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/lib/mixins/mutable-data.html b/lib/mixins/mutable-data.html
index 2cfe3d54d3..0adce76b25 100644
--- a/lib/mixins/mutable-data.html
+++ b/lib/mixins/mutable-data.html
@@ -8,6 +8,8 @@
 subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
 -->
 
+<link rel="import" href="../utils/mixin.html">
+
 <script>
 (function() {
   'use strict';
@@ -68,7 +70,7 @@
    * @summary Element class mixin to skip strict dirty-checking for objects
    *   and arrays
    */
-  Polymer.MutableData = (superClass) => {
+  Polymer.MutableData = Polymer.dedupingMixin((superClass) => {
 
     return class MutableData extends superClass {
       /**
@@ -94,7 +96,7 @@
 
     }
 
-  };
+  });
 
   /**
    * Element class mixin to add the optional ability to skip strict
@@ -133,7 +135,7 @@
    * @summary Element class mixin to optionally skip strict dirty-checking
    *   for objects and arrays
    */
-  Polymer.OptionalMutableData = (superClass) => {
+  Polymer.OptionalMutableData = Polymer.dedupingMixin((superClass) => {
 
     return class OptionalMutableData extends superClass {
 
@@ -171,7 +173,7 @@
       }
     }
 
-  };
+  });
 
   // Export for use by legacy behavior
   Polymer.MutableData._mutablePropertyChange = mutablePropertyChange;
diff --git a/lib/utils/templatize.html b/lib/utils/templatize.html
index 82bb74e1c0..5152176ee3 100644
--- a/lib/utils/templatize.html
+++ b/lib/utils/templatize.html
@@ -432,12 +432,13 @@
        *
        * @memberof Polymer.Templatize
        * @method modelForElement
-       * @param {HTMLElement} host
+       * @param {HTMLTemplateElement} template The model will be returned for
+       *   elements stamped from this template
        * @param {HTMLElement} el Element for which to return a template model.
        * @return {TemplateInstanceBase} Template instance representing the
        *   binding scope for the element
        */
-      modelForElement(host, el) {
+      modelForElement(template, el) {
         let model;
         while (el) {
           // An element with a __templatizeInstance marks the top boundary
@@ -446,7 +447,7 @@
           if ((model = el.__templatizeInstance)) {
             // Found an element stamped by another template; keep walking up
             // from its __dataHost
-            if (model.__dataHost != host) {
+            if (model.__dataHost != template) {
               el = model.__dataHost;
             } else {
               return model;

From 8cab18b15d8f82b3cca090ac2897fbb94af74ec4 Mon Sep 17 00:00:00 2001
From: Kevin Schaaf <kschaaf@google.com>
Date: Fri, 14 Apr 2017 14:39:00 -0700
Subject: [PATCH 6/8] Standardize @return, @param, type case.

---
 .eslintrc.json                          | 13 ++++++++++-
 lib/legacy/class.html                   |  4 ++--
 lib/legacy/legacy-element-mixin.html    | 30 ++++++++++++-------------
 lib/legacy/templatizer-behavior.html    |  2 +-
 lib/mixins/element-mixin.html           |  8 +++----
 lib/mixins/property-effects.html        |  4 ++--
 lib/utils/flattened-nodes-observer.html |  2 +-
 lib/utils/gestures.html                 |  6 ++---
 lib/utils/mixin.html                    |  2 +-
 test/unit/configure.html                |  2 +-
 10 files changed, 42 insertions(+), 31 deletions(-)

diff --git a/.eslintrc.json b/.eslintrc.json
index 2f2f881d38..3c7fac3497 100644
--- a/.eslintrc.json
+++ b/.eslintrc.json
@@ -6,7 +6,18 @@
     "no-var": "error",
     "strict": "error",
     "valid-jsdoc": ["error", {
-      "requireReturn": false
+      "requireReturn": false,
+      "prefer": {
+        "arg": "param",
+        "argument": "param",
+        "returns": "return"
+      },
+      "preferType": {
+        "Boolean": "boolean",
+        "Number": "number",
+        "String": "string",
+        "object": "Object"
+      }
     }]
   },
   "env": {
diff --git a/lib/legacy/class.html b/lib/legacy/class.html
index 2b74a68be5..a63c6a16a7 100644
--- a/lib/legacy/class.html
+++ b/lib/legacy/class.html
@@ -37,7 +37,7 @@
      *
      * @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
+     * @return {HTMLElement} Returns a new Element class extended by the
      * passed in `behaviors` and also by `Polymer.LegacyElementMixin`.
      * @memberof Polymer
      */
@@ -110,7 +110,7 @@
      * @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.
+     * @return {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 dc1ab55fd5..2add4236f4 100644
--- a/lib/legacy/legacy-element-mixin.html
+++ b/lib/legacy/legacy-element-mixin.html
@@ -192,7 +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.
+       * @return {*} Returns the deserialized value in the `type` given.
        */
       deserialize(value, type) {
         return this._deserializeValue(value, type);
@@ -276,7 +276,7 @@
        * @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
+       * @return {Object} Returns the given `object` with its prototype set
        * to the given `prototype` object.
        */
       chainObject(object, prototype) {
@@ -389,7 +389,7 @@
        *   - 'none': disable scrolling for this node
        *
        * @method setScrollDirection
-       * @param {String=} direction Direction to allow scrolling
+       * @param {string=} direction Direction to allow scrolling
        * Defaults to `all`.
        * @param {HTMLElement=} node Element to apply scroll direction setting.
        * Defaults to `this`.
@@ -529,7 +529,7 @@
        * an optional selector may be passed to choose the desired content.
        *
        * @method getContentChildNodes
-       * @param {String=} slctr CSS selector to choose the desired
+       * @param {string=} slctr CSS selector to choose the desired
        *   `<slot>`.  Defaults to `content`.
        * @return {Array<Node>} List of distributed nodes for the `<slot>`.
        */
@@ -548,7 +548,7 @@
        * elements are returned.
        *
        * @method getContentChildNodes
-       * @param {String=} slctr CSS selector to choose the desired
+       * @param {string=} slctr CSS selector to choose the desired
        *   `<content>`.  Defaults to `content`.
        * @return {Array<HTMLElement>} List of distributed nodes for the
        *   `<slot>`.
@@ -564,7 +564,7 @@
        *
        * @method isLightDescendant
        * @param {?Node} node The element to be checked.
-       * @return {Boolean} true if node is in this element's light DOM tree.
+       * @return {boolean} true if node is in this element's light DOM tree.
        */
       isLightDescendant(node) {
         return this !== node && this.contains(node) &&
@@ -588,8 +588,8 @@
 
       /**
        * Returns the computed style value for the given property.
-       * @param {String} property The css property name.
-       * @returns {String} Returns the computed css property value for the given
+       * @param {string} property The css property name.
+       * @return {string} Returns the computed css property value for the given
        * `property`.
        */
       getComputedStyleValue(property) {
@@ -612,12 +612,12 @@
        *     }
        *
        * @method debounce
-       * @param {String} jobName String to indentify the debounce job.
+       * @param {string} jobName String to indentify the debounce job.
        * @param {function()} 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`
-       * @returns {Object} Returns a debouncer object on which exists the
+       * @return {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
@@ -635,7 +635,7 @@
        * Returns whether a named debouncer is active.
        *
        * @method isDebouncerActive
-       * @param {String} jobName The name of the debouncer started with `debounce`
+       * @param {string} jobName The name of the debouncer started with `debounce`
        * @return {boolean} Whether the debouncer is active (has not yet fired).
        */
       isDebouncerActive(jobName) {
@@ -648,7 +648,7 @@
        * Immediately calls the debouncer `callback` and inactivates it.
        *
        * @method flushDebouncer
-       * @param {String} jobName The name of the debouncer started with `debounce`
+       * @param {string} jobName The name of the debouncer started with `debounce`
        */
       flushDebouncer(jobName) {
         this._debouncers = this._debouncers || {};
@@ -662,7 +662,7 @@
        * Cancels an active debouncer.  The `callback` will not be called.
        *
        * @method cancelDebouncer
-       * @param {String} jobName The name of the debouncer started with `debounce`
+       * @param {string} jobName The name of the debouncer started with `debounce`
        */
       cancelDebouncer(jobName) {
         this._debouncers = this._debouncers || {}
@@ -768,7 +768,7 @@
        * Toggles an HTML attribute on or off.
        *
        * @method toggleAttribute
-       * @param {String} name HTML attribute name
+       * @param {string} name HTML attribute name
        * @param {boolean=} bool Boolean to force the attribute on or off.
        *    When unspecified, the state of the attribute will be reversed.
        * @param {HTMLElement=} node Node to target.  Defaults to `this`.
@@ -790,7 +790,7 @@
        * Toggles a CSS class on or off.
        *
        * @method toggleClass
-       * @param {String} name CSS class name
+       * @param {string} name CSS class name
        * @param {boolean=} bool Boolean to force the class on or off.
        *    When unspecified, the state of the class will be reversed.
        * @param {HTMLElement=} node Node to target.  Defaults to `this`.
diff --git a/lib/legacy/templatizer-behavior.html b/lib/legacy/templatizer-behavior.html
index 8673bba042..7a15533b65 100644
--- a/lib/legacy/templatizer-behavior.html
+++ b/lib/legacy/templatizer-behavior.html
@@ -84,7 +84,7 @@
        * by `stamp` to create new instances of the template.
        *
        * @param {HTMLTemplateElement} template Template to prepare
-       * @param {Boolean=} mutableData When `true`, the generated class will skip
+       * @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.
        */
diff --git a/lib/mixins/element-mixin.html b/lib/mixins/element-mixin.html
index 607c112dfc..6f5e2d8739 100644
--- a/lib/mixins/element-mixin.html
+++ b/lib/mixins/element-mixin.html
@@ -384,9 +384,9 @@
      * @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.
+     * @param {Object} info Info object from which to create property effects.
      * Supported keys:
-     * @param {object} allProps Flattened map of all properties defined in this
+     * @param {Object} allProps Flattened map of all properties defined in this
      *   element (including inherited properties)
      * @private
      */
@@ -529,7 +529,7 @@
        *     }
        *   }
        *
-       * @returns {HTMLTemplateElement|string} Template to be stamped
+       * @return {HTMLTemplateElement|string} Template to be stamped
        */
       static get template() {
         if (!this.hasOwnProperty(goog.reflect.objectProperty('_template', this))) {
@@ -551,7 +551,7 @@
        * matching this element's static `is` property.
        * Note, this path should contain a trailing `/`.
        *
-       * @returns {string} The import path for this element class
+       * @return {string} The import path for this element class
        */
       static get importPath() {
         if (!this.hasOwnProperty(goog.reflect.objectProperty('_importPath', this))) {
diff --git a/lib/mixins/property-effects.html b/lib/mixins/property-effects.html
index 1a21f9212d..92537dcac5 100644
--- a/lib/mixins/property-effects.html
+++ b/lib/mixins/property-effects.html
@@ -482,7 +482,7 @@
    * @param {Object} templateInfo Template metadata for current template
    * @param {Object} binding Binding metadata
    * @param {Object} part Binding part metadata
-   * @param {Number} index Index into `nodeInfoList` for this node
+   * @param {number} index Index into `nodeInfoList` for this node
    */
   function addEffectForBindingPart(constructor, templateInfo, binding, part, index) {
     if (!part.literal) {
@@ -2280,7 +2280,7 @@
        * - Inline computed method (supports negation):
        *   `[[compute(a, 'literal', b)]]`, `[[!compute(a, 'literal', b)]]`
        *
-       * @param {String} text Text to parse from attribute or textContent
+       * @param {string} text Text to parse from attribute or textContent
        * @param {Object} templateInfo Current template metadata
        * @return {Array<Object>} Array of binding part metadata
        * @protected
diff --git a/lib/utils/flattened-nodes-observer.html b/lib/utils/flattened-nodes-observer.html
index 0a49b3ab0d..c1f75d038b 100644
--- a/lib/utils/flattened-nodes-observer.html
+++ b/lib/utils/flattened-nodes-observer.html
@@ -57,7 +57,7 @@
      * `<slot>` elements assigned to it, these are flattened as well.
      *
      * @param {Node} node The node for which to return the list of flattened nodes.
-     * @returns {Array} The list of flattened nodes for the given `node`.
+     * @return {Array} The list of flattened nodes for the given `node`.
     */
     static getFlattenedNodes(node) {
       if (isSlot(node)) {
diff --git a/lib/utils/gestures.html b/lib/utils/gestures.html
index 5d8183f848..4fe82a9ac0 100644
--- a/lib/utils/gestures.html
+++ b/lib/utils/gestures.html
@@ -263,7 +263,7 @@
      *
      * @private
      * @param {Event} ev Event.
-     * @returns {HTMLElement} Returns the event target.
+     * @return {HTMLElement} Returns the event target.
      */
     _findOriginalTarget: function(ev) {
       // shadowdom
@@ -379,7 +379,7 @@
      * @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
-     * @returns {boolean} Returns true if a gesture event listener was added.
+     * @return {boolean} Returns true if a gesture event listener was added.
      */
     addListener: function(node, evType, handler) {
       if (this.gestures[evType]) {
@@ -396,7 +396,7 @@
      * @param {string} evType Gesture type: `down`, `up`, `track`, or `tap`
      * @param {Function} handler Event listener function previously passed to
      *  `addListener`.
-     * @returns {boolean} Returns true if a gesture event listener was removed.
+     * @return {boolean} Returns true if a gesture event listener was removed.
      */
     removeListener: function(node, evType, handler) {
       if (this.gestures[evType]) {
diff --git a/lib/utils/mixin.html b/lib/utils/mixin.html
index 0285f7782c..e82cf6de4a 100644
--- a/lib/utils/mixin.html
+++ b/lib/utils/mixin.html
@@ -23,7 +23,7 @@
    * 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
+   * @return {Object} Returns a mixin which when applied multiple times to the
    * same base will always return the same extended class.
    */
   function cachingMixin(mixin) {
diff --git a/test/unit/configure.html b/test/unit/configure.html
index 02d7921283..2ea7beeaf7 100644
--- a/test/unit/configure.html
+++ b/test/unit/configure.html
@@ -113,7 +113,7 @@
 
   <dom-module id="x-configure-child">
     <template>
-      <x-configure-gchild id="gchild" content="{{content}}" object="{{object}}"></x-configure-gchild>
+      <x-configure-gchild id="gchild" content="{{content}}" object="{{Object}}"></x-configure-gchild>
     </template>
     <script>
     HTMLImports.whenReady(function() {

From 6d636138605ec8c629581388ab06722374f94a25 Mon Sep 17 00:00:00 2001
From: Kevin Schaaf <kschaaf@google.com>
Date: Fri, 14 Apr 2017 15:00:27 -0700
Subject: [PATCH 7/8] Remove unused @method

---
 lib/elements/array-selector.html     |  7 ------
 lib/elements/dom-module.html         |  2 --
 lib/elements/dom-repeat.html         |  3 ---
 lib/legacy/legacy-element-mixin.html | 32 ----------------------------
 lib/legacy/templatizer-behavior.html |  1 -
 lib/mixins/element-mixin.html        |  1 -
 lib/mixins/property-accessors.html   |  6 ------
 lib/mixins/property-effects.html     |  9 --------
 lib/utils/gestures.html              |  1 -
 lib/utils/import-href.html           |  1 -
 lib/utils/templatize.html            |  1 -
 11 files changed, 64 deletions(-)

diff --git a/lib/elements/array-selector.html b/lib/elements/array-selector.html
index 5cf7c3c8be..bff749c6aa 100644
--- a/lib/elements/array-selector.html
+++ b/lib/elements/array-selector.html
@@ -193,7 +193,6 @@
       /**
        * Clears the selection state.
        *
-       * @method clearSelection
        */
       clearSelection() {
         // Unbind previous selection
@@ -211,7 +210,6 @@
       /**
        * Returns whether the item is currently selected.
        *
-       * @method isSelected
        * @param {*} item Item from `items` array to test
        * @return {boolean} Whether the item is selected
        */
@@ -222,7 +220,6 @@
       /**
        * Returns whether the item is currently selected.
        *
-       * @method isSelected
        * @param {*} idx Index from `items` array to test
        * @return {boolean} Whether the item is selected
        */
@@ -252,7 +249,6 @@
       /**
        * Deselects the given item if it is already selected.
        *
-       * @method deselect
        * @param {*} item Item from `items` array to deselect
        */
       deselect(item) {
@@ -275,7 +271,6 @@
       /**
        * Deselects the given index if it is already selected.
        *
-       * @method deselect
        * @param {number} idx Index from `items` array to deselect
        */
       deselectIndex(idx) {
@@ -286,7 +281,6 @@
        * Selects the given item.  When `toggle` is true, this will automatically
        * deselect the item if already selected.
        *
-       * @method select
        * @param {*} item Item from `items` array to select
        */
       select(item) {
@@ -297,7 +291,6 @@
        * Selects the given index.  When `toggle` is true, this will automatically
        * deselect the item if already selected.
        *
-       * @method select
        * @param {number} idx Index from `items` array to select
        */
       selectIndex(idx) {
diff --git a/lib/elements/dom-module.html b/lib/elements/dom-module.html
index 29c0c1ae09..99edb7f109 100644
--- a/lib/elements/dom-module.html
+++ b/lib/elements/dom-module.html
@@ -56,7 +56,6 @@
     /**
      * 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
@@ -108,7 +107,6 @@
      * Registers the dom-module at a given id. This method should only be called
      * when a dom-module is imperatively created. For
      * example, `document.createElement('dom-module').register('foo')`.
-     * @method register
      * @param {string=} id The id at which to register the dom-module.
      */
     register(id) {
diff --git a/lib/elements/dom-repeat.html b/lib/elements/dom-repeat.html
index 4a8ac93d84..c791e66634 100644
--- a/lib/elements/dom-repeat.html
+++ b/lib/elements/dom-repeat.html
@@ -626,7 +626,6 @@
      * `modelForElement(el).set('item.<sub-prop>', value)`
      * should be used.
      *
-     * @method itemForElement
      * @param {HTMLElement} el Element for which to return the item.
      * @return {*} Item associated with the element.
      */
@@ -640,7 +639,6 @@
      * If `sort` is provided, the index will reflect the sorted order (rather
      * than the original array order).
      *
-     * @method indexForElement
      * @param {HTMLElement} el Element for which to return the index.
      * @return {*} Row index associated with the element (note this may
      *   not correspond to the array index if a user `sort` is applied).
@@ -663,7 +661,6 @@
      *     model.set('item.checked', true);
      *   }
      *
-     * @method modelForElement
      * @param {HTMLElement} el Element for which to return a template model.
      * @return {TemplateInstanceBase} Model representing the binding scope for
      *   the element.
diff --git a/lib/legacy/legacy-element-mixin.html b/lib/legacy/legacy-element-mixin.html
index 2add4236f4..a47de0b5fa 100644
--- a/lib/legacy/legacy-element-mixin.html
+++ b/lib/legacy/legacy-element-mixin.html
@@ -230,7 +230,6 @@
        * Copies own properties (including accessor descriptors) from a source
        * object to a target object.
        *
-       * @method extend
        * @param {Object} prototype Target object to copy properties to.
        * @param {Object} api Source object to copy properties from.
        * @return {Object} prototype object that was passed as first argument.
@@ -256,7 +255,6 @@
        * properties.  To ensure only `ownProperties` are copied from source
        * to target and that accessor implementations are copied, use `extend`.
        *
-       * @method mixin
        * @param {Object} target Target object to copy properties to.
        * @param {Object} source Source object to copy properties from.
        * @return {Object} Target object that was passed as first argument.
@@ -292,7 +290,6 @@
        * Calls `importNode` on the `content` of the `template` specified and
        * returns a document fragment containing the imported content.
        *
-       * @method instanceTemplate
        * @param {HTMLTemplateElement} template HTML template element to instance.
        * @return {DocumentFragment} Document fragment containing the imported
        *   template content.
@@ -309,7 +306,6 @@
       /**
        * Dispatches a custom event with an optional detail value.
        *
-       * @method fire
        * @param {string} type Name of event type.
        * @param {*=} detail Detail value containing event-specific
        *   payload.
@@ -337,7 +333,6 @@
        * Convenience method to add an event listener on a given element,
        * late bound to a named method on this element.
        *
-       * @method listen
        * @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.
@@ -362,7 +357,6 @@
        * Convenience method to remove an event listener from a given element,
        * late bound to a named method on this element.
        *
-       * @method unlisten
        * @param {Element} node Element to remove event listener from.
        * @param {string} eventName Name of event to stop listening to.
        * @param {string} methodName Name of handler method on `this` to not call
@@ -388,7 +382,6 @@
        *   - 'y': scroll only in the 'y' direction
        *   - 'none': disable scrolling for this node
        *
-       * @method setScrollDirection
        * @param {string=} direction Direction to allow scrolling
        * Defaults to `all`.
        * @param {HTMLElement=} node Element to apply scroll direction setting.
@@ -404,7 +397,6 @@
        *
        * This function calls `Polymer.dom(this.root).querySelector(slctr)`.
        *
-       * @method $$
        * @param {string} slctr Selector to run on this local DOM scope
        * @return {Element} Element found by the selector, or null if not found.
        */
@@ -429,7 +421,6 @@
        * a user should call `distributeContent` if distribution has been
        * invalidated due to an element being added or removed from the shadowRoot
        * that contains an insertion point (<slot>) inside its subtree.
-       * @method distributeContent
        */
       distributeContent() {
         if (window.ShadyDOM && this.shadowRoot) {
@@ -443,7 +434,6 @@
        * any `<content>` elements are replaced with the list of nodes distributed
        * to the `<content>`, the result of its `getDistributedNodes` method.
        *
-       * @method getEffectiveChildNodes
        * @return {Array<Node>} List of effctive child nodes.
        */
       getEffectiveChildNodes() {
@@ -454,7 +444,6 @@
        * Returns a list of nodes distributed within this element that match
        * `selector`. These can be dom children or elements distributed to
        * children that are insertion points.
-       * @method queryDistributedElements
        * @param {string} selector Selector to run.
        * @return {Array<Node>} List of distributed elements that match selector.
        */
@@ -468,7 +457,6 @@
        * any `<content>` elements are replaced with the list of elements
        * distributed to the `<content>`.
        *
-       * @method getEffectiveChildren
        * @return {Array<Node>} List of effctive children.
        */
       getEffectiveChildren() {
@@ -483,7 +471,6 @@
        * text content's of the element's effective childNodes (the elements
        * returned by <a href="#getEffectiveChildNodes>getEffectiveChildNodes</a>.
        *
-       * @method getEffectiveTextContent
        * @return {string} List of effctive children.
        */
       getEffectiveTextContent() {
@@ -501,7 +488,6 @@
        * Returns the first effective childNode within this element that
        * match `selector`. These can be dom child nodes or elements distributed
        * to children that are insertion points.
-       * @method queryEffectiveChildren
        * @param {string} selector Selector to run.
        * @return {Object<Node>} First effective child node that matches selector.
        */
@@ -514,7 +500,6 @@
        * Returns a list of effective childNodes within this element that
        * match `selector`. These can be dom child nodes or elements distributed
        * to children that are insertion points.
-       * @method queryEffectiveChildren
        * @param {string} selector Selector to run.
        * @return {Array<Node>} List of effective child nodes that match selector.
        */
@@ -528,7 +513,6 @@
        * If this element contains more than one `<slot>` in its local DOM,
        * an optional selector may be passed to choose the desired content.
        *
-       * @method getContentChildNodes
        * @param {string=} slctr CSS selector to choose the desired
        *   `<slot>`.  Defaults to `content`.
        * @return {Array<Node>} List of distributed nodes for the `<slot>`.
@@ -547,7 +531,6 @@
        * content.  This method differs from `getContentChildNodes` in that only
        * elements are returned.
        *
-       * @method getContentChildNodes
        * @param {string=} slctr CSS selector to choose the desired
        *   `<content>`.  Defaults to `content`.
        * @return {Array<HTMLElement>} List of distributed nodes for the
@@ -562,7 +545,6 @@
       /**
        * Checks whether an element is in this element's light DOM tree.
        *
-       * @method isLightDescendant
        * @param {?Node} node The element to be checked.
        * @return {boolean} true if node is in this element's light DOM tree.
        */
@@ -574,7 +556,6 @@
       /**
        * Checks whether an element is in this element's local DOM tree.
        *
-       * @method isLocalDescendant
        * @param {HTMLElement=} node The element to be checked.
        * @return {boolean} true if node is in this element's local DOM tree.
        */
@@ -611,7 +592,6 @@
        *       } 100);
        *     }
        *
-       * @method debounce
        * @param {string} jobName String to indentify the debounce job.
        * @param {function()} callback Function that is called (with `this`
        *   context) when the wait time elapses.
@@ -634,7 +614,6 @@
       /**
        * Returns whether a named debouncer is active.
        *
-       * @method isDebouncerActive
        * @param {string} jobName The name of the debouncer started with `debounce`
        * @return {boolean} Whether the debouncer is active (has not yet fired).
        */
@@ -647,7 +626,6 @@
       /**
        * Immediately calls the debouncer `callback` and inactivates it.
        *
-       * @method flushDebouncer
        * @param {string} jobName The name of the debouncer started with `debounce`
        */
       flushDebouncer(jobName) {
@@ -661,7 +639,6 @@
       /**
        * Cancels an active debouncer.  The `callback` will not be called.
        *
-       * @method cancelDebouncer
        * @param {string} jobName The name of the debouncer started with `debounce`
        */
       cancelDebouncer(jobName) {
@@ -678,7 +655,6 @@
        * By default (if no waitTime is specified), async callbacks are run at
        * microtask timing, which will occur before paint.
        *
-       * @method async
        * @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
@@ -693,7 +669,6 @@
       /**
        * Cancels an async operation started with `async`.
        *
-       * @method cancelAsync
        * @param {number} handle Handle returned from original `async` call to
        *   cancel.
        */
@@ -707,7 +682,6 @@
       /**
        * Convenience method for creating an element and configuring it.
        *
-       * @method create
        * @param {string} tag HTML element tag to create.
        * @param {Object} props Object of properties to configure on the
        *    instance.
@@ -735,7 +709,6 @@
        * In the `onload` callback, the `import` property of the `link`
        * element will contain the imported document contents.
        *
-       * @method importHref
        * @param {string} href URL to document to load.
        * @param {Function} onload Callback to notify when an import successfully
        *   loaded.
@@ -755,7 +728,6 @@
        * Polyfill for Element.prototype.matches, which is sometimes still
        * prefixed.
        *
-       * @method elementMatches
        * @param {string} selector Selector to test.
        * @param {Element=} node Element to test the selector against.
        * @return {boolean} Whether the element matches the selector.
@@ -767,7 +739,6 @@
       /**
        * Toggles an HTML attribute on or off.
        *
-       * @method toggleAttribute
        * @param {string} name HTML attribute name
        * @param {boolean=} bool Boolean to force the attribute on or off.
        *    When unspecified, the state of the attribute will be reversed.
@@ -789,7 +760,6 @@
       /**
        * Toggles a CSS class on or off.
        *
-       * @method toggleClass
        * @param {string} name CSS class name
        * @param {boolean=} bool Boolean to force the class on or off.
        *    When unspecified, the state of the class will be reversed.
@@ -824,7 +794,6 @@
        * Cross-platform helper for setting an element's CSS `translate3d`
        * property.
        *
-       * @method translate3d
        * @param {number} x X offset.
        * @param {number} y Y offset.
        * @param {number} z Z offset.
@@ -846,7 +815,6 @@
        * If the array is passed directly, **no change
        * notification is generated**.
        *
-       * @method arrayDelete
        * @param {string | !Array<number|string>} arrayOrPath Path to array from which to remove the item
        *   (or the array itself).
        * @param {*} item Item to remove.
diff --git a/lib/legacy/templatizer-behavior.html b/lib/legacy/templatizer-behavior.html
index 7a15533b65..4f3a14aa85 100644
--- a/lib/legacy/templatizer-behavior.html
+++ b/lib/legacy/templatizer-behavior.html
@@ -121,7 +121,6 @@
        * instance the element is contained in.  A template model should be used
        * to manipulate data associated with this template instance.
        *
-       * @method modelForElement
        * @param {HTMLElement} el Element for which to return a template model.
        * @return {TemplateInstanceBase} Model representing the binding scope for
        *   the element.
diff --git a/lib/mixins/element-mixin.html b/lib/mixins/element-mixin.html
index 6f5e2d8739..a8b6a0d8c2 100644
--- a/lib/mixins/element-mixin.html
+++ b/lib/mixins/element-mixin.html
@@ -677,7 +677,6 @@
        * However, this method may be overridden to allow an element
        * to put its dom in another location.
        *
-       * @method _attachDom
        * @throws {Error}
        * @suppress {missingReturn}
        * @param {NodeList} dom to attach to the element.
diff --git a/lib/mixins/property-accessors.html b/lib/mixins/property-accessors.html
index 609b31c2cc..ca9b9dea24 100644
--- a/lib/mixins/property-accessors.html
+++ b/lib/mixins/property-accessors.html
@@ -193,7 +193,6 @@
        * assigns the given value to the attribute.
        *
        *
-       * @method _ensureAttribute
        * @param {string} attribute Name of attribute to ensure is set.
        * @param {string} value of the attribute.
        */
@@ -209,7 +208,6 @@
        * This method calls the `_deserializeValue` method to convert the string to
        * a typed value.
        *
-       * @method _attributeToProperty
        * @param {string} attribute Name of attribute to deserialize.
        * @param {string} value of the attribute.
        * @param {*} type type to deserialize to.
@@ -225,7 +223,6 @@
       /**
        * Serializes a property to its associated attribute.
        *
-       * @method _propertyToAttribute
        * @param {string} property Property name to reflect.
        * @param {string=} attribute Attribute name to reflect.
        * @param {*=} value Property value to refect.
@@ -246,7 +243,6 @@
        * the attribute will be removed (this is the default for boolean
        * type `false`).
        *
-       * @method _valueToNodeAttribute
        * @param {Element} node Element to set attribute to.
        * @param {*} value Value to serialize.
        * @param {string} attribute Attribute name to serialize to.
@@ -267,7 +263,6 @@
        * HTML attributes.  Users may override this method on Polymer element
        * prototypes to provide serialization for custom types.
        *
-       * @method _serializeValue
        * @param {*} value Property value to serialize.
        * @return {string | undefined} String serialized from the provided property value.
        */
@@ -306,7 +301,6 @@
        * Note: The return value of `undefined` is used as a sentinel value to
        * indicate the attribute should be removed.
        *
-       * @method _deserializeValue
        * @param {string} value Attribute value to deserialize.
        * @param {*} type Type to deserialize the string to.
        * @return {*} Typed value deserialized from the provided string.
diff --git a/lib/mixins/property-effects.html b/lib/mixins/property-effects.html
index 92537dcac5..2db0fbffa6 100644
--- a/lib/mixins/property-effects.html
+++ b/lib/mixins/property-effects.html
@@ -1588,7 +1588,6 @@
        * Aliases one data path as another, such that path notifications from one
        * are routed to the other.
        *
-       * @method linkPaths
        * @param {string | !Array<string|number>} to Target path to link.
        * @param {string | !Array<string|number>} from Source path to link.
        * @public
@@ -1606,7 +1605,6 @@
        * Note, the path to unlink should be the target (`to`) used when
        * linking the paths.
        *
-       * @method unlinkPaths
        * @param {string | !Array<string|number>} path Target path to unlink.
        * @public
        */
@@ -1659,7 +1657,6 @@
        * `undefined` (this method does not throw when dereferencing undefined
        * paths).
        *
-       * @method get
        * @param {(string|!Array<(string|number)>)} path Path to the value
        *   to read.  The path may be specified as a string (e.g. `foo.bar.baz`)
        *   or an array of path parts (e.g. `['foo.bar', 'baz']`).  Note that
@@ -1684,7 +1681,6 @@
        * this method does nothing (this method does not throw when
        * dereferencing undefined paths).
        *
-       * @method set
        * @param {(string|!Array<(string|number)>)} path Path to the value
        *   to write.  The path may be specified as a string (e.g. `'foo.bar.baz'`)
        *   or an array of path parts (e.g. `['foo.bar', 'baz']`).  Note that
@@ -1718,7 +1714,6 @@
        * This method notifies other paths to the same array that a
        * splice occurred to the array.
        *
-       * @method push
        * @param {string} path Path to array.
        * @param {...*} items Items to push onto array
        * @return {number} New length of the array.
@@ -1744,7 +1739,6 @@
        * This method notifies other paths to the same array that a
        * splice occurred to the array.
        *
-       * @method pop
        * @param {string} path Path to array.
        * @return {*} Item that was removed.
        * @public
@@ -1770,7 +1764,6 @@
        * This method notifies other paths to the same array that a
        * splice occurred to the array.
        *
-       * @method splice
        * @param {string} path Path to array.
        * @param {number} start Index from which to start removing/inserting.
        * @param {number} deleteCount Number of items to remove.
@@ -1806,7 +1799,6 @@
        * This method notifies other paths to the same array that a
        * splice occurred to the array.
        *
-       * @method shift
        * @param {string} path Path to array.
        * @return {*} Item that was removed.
        * @public
@@ -1831,7 +1823,6 @@
        * This method notifies other paths to the same array that a
        * splice occurred to the array.
        *
-       * @method unshift
        * @param {string} path Path to array.
        * @param {...*} items Items to insert info array
        * @return {number} New length of the array.
diff --git a/lib/utils/gestures.html b/lib/utils/gestures.html
index 4fe82a9ac0..4ee65c3b87 100644
--- a/lib/utils/gestures.html
+++ b/lib/utils/gestures.html
@@ -562,7 +562,6 @@
      * This method should only be called during testing with simulated touch inputs.
      * Calling this method in production may cause duplicate taps or other Gestures.
      *
-     * @method resetMouseCanceller
      * @memberof Polymer.Gestures
      */
     resetMouseCanceller: function() {
diff --git a/lib/utils/import-href.html b/lib/utils/import-href.html
index 627eae9c9b..77933a4e43 100644
--- a/lib/utils/import-href.html
+++ b/lib/utils/import-href.html
@@ -35,7 +35,6 @@
    * element will contain the imported document contents.
    *
    * @memberof Polymer
-   * @method importHref
    * @param {string} href URL to document to load.
    * @param {Function=} onload Callback to notify when an import successfully
    *   loaded.
diff --git a/lib/utils/templatize.html b/lib/utils/templatize.html
index 5152176ee3..4a6ad4312a 100644
--- a/lib/utils/templatize.html
+++ b/lib/utils/templatize.html
@@ -431,7 +431,6 @@
        *   }
        *
        * @memberof Polymer.Templatize
-       * @method modelForElement
        * @param {HTMLTemplateElement} template The model will be returned for
        *   elements stamped from this template
        * @param {HTMLElement} el Element for which to return a template model.

From 28c15caa61b08e3dd2b9feee5bec13c17c38fafb Mon Sep 17 00:00:00 2001
From: Kevin Schaaf <kschaaf@google.com>
Date: Fri, 14 Apr 2017 15:02:41 -0700
Subject: [PATCH 8/8] Never accidental test change

---
 test/unit/configure.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/unit/configure.html b/test/unit/configure.html
index 2ea7beeaf7..02d7921283 100644
--- a/test/unit/configure.html
+++ b/test/unit/configure.html
@@ -113,7 +113,7 @@
 
   <dom-module id="x-configure-child">
     <template>
-      <x-configure-gchild id="gchild" content="{{content}}" object="{{Object}}"></x-configure-gchild>
+      <x-configure-gchild id="gchild" content="{{content}}" object="{{object}}"></x-configure-gchild>
     </template>
     <script>
     HTMLImports.whenReady(function() {