From e194d40afd5bb914af78f3c63160c31d858d6489 Mon Sep 17 00:00:00 2001
From: Kevin Schaaf <kschaaf@google.com>
Date: Tue, 28 Feb 2017 17:07:32 -0800
Subject: [PATCH] More API docs.

---
 lib/legacy/legacy-element-mixin.html | 12 +++--
 lib/mixins/element-mixin.html        | 68 ++++++++++++++++++++++++++--
 2 files changed, 71 insertions(+), 9 deletions(-)

diff --git a/lib/legacy/legacy-element-mixin.html b/lib/legacy/legacy-element-mixin.html
index 0edda56d..655a2403 100644
--- a/lib/legacy/legacy-element-mixin.html
+++ b/lib/legacy/legacy-element-mixin.html
@@ -59,7 +59,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
 
       /**
-       * TODOC
+       * Legacy callback called during the `constructor`, for overriding
+       * by the user.
        */
       created() {}
 
@@ -70,7 +71,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
 
       /**
-       * TODOC
+       * Legacy callback called during `connectedCallback`, for overriding
+       * by the user.
        */
       attached() {}
 
@@ -81,7 +83,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
 
       /**
-       * TODOC
+       * Legacy callback called during `disconnectedCallback`, for overriding
+       * by the user.
        */
       detached() {}
 
@@ -93,7 +96,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
 
       /**
-       * TODOC
+       * Legacy callback called during `attributeChangedChallback`, for overriding
+       * by the user.
        */
       attributeChanged() {}
 
diff --git a/lib/mixins/element-mixin.html b/lib/mixins/element-mixin.html
index 1fcd7fc2..ffd30ceb 100644
--- a/lib/mixins/element-mixin.html
+++ b/lib/mixins/element-mixin.html
@@ -514,10 +514,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
       /**
        * Overrides the default `Polymer.PropertyAccessors` to ensure class
-       * metaprogramming related to property accessors and effects is completed.
+       * metaprogramming related to property accessors and effects has
+       * completed (calls `finalize`).
        *
-       * It also initializes any property defaults based on the `properties`
-       * metadata's `value` property.
+       * It also initializes any property defaults provided via `value` in
+       * `properties` metadata.
        *
        * @override
        */
@@ -550,6 +551,16 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
         }
       }
 
+      /**
+       * Provides a default implementation of the standard Custom Elements
+       * `connectedCallback`.
+       *
+       * The default implementation enables the property effects system and
+       * flushes any pending properties, and updates shimmed CSS properties
+       * when using the ShadyCSS scoping/custom properties polyfill.
+       *
+       * @override
+       */
       connectedCallback() {
         if (window.ShadyCSS) {
           window.ShadyCSS.styleElement(this);
@@ -557,8 +568,20 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
         this._flushProperties();
       }
 
+      /**
+       * Provides a default implementation of the standard Custom Elements
+       * `disconnectedCallback`.
+       *
+       * @override
+       */
       disconnectedCallback() {}
 
+      /**
+       * Overrides the `Polymer.PropertyEffects` ready callback to attach
+       * the stamped template content (`this.root`) to the dom.
+       *
+       * @override
+       */
       ready() {
         super.ready();
         if (this._template) {
@@ -567,7 +590,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
 
       /**
-       * Attach an element's stamped dom to itself. By default,
+       * Attaches an element's stamped dom to itself. By default,
        * this method creates a `shadowRoot` and adds the dom to it.
        * However, this method may be overridden to allow an element
        * to put its dom in another location.
@@ -595,6 +618,17 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
         }
       }
 
+      /**
+       * Provides a default implementation of the standard Custom Elements
+       * `attributeChangedCallback`.
+       *
+       * By default, attributes declared in `properties` metadata are
+       * deserialized using their `type` information to properties of the
+       * same name.  "Dash-cased" attributes are deserialzed to "camelCase"
+       * properties.
+       *
+       * @override
+       */
       attributeChangedCallback(name, old, value) {
         if (old !== value) {
           let property = caseMap.dashToCamelCase(name);
@@ -651,17 +685,41 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     return PolymerElement;
   });
 
-  // telemetry
+  /**
+   * Provides basic tracking of element definitions (registrations) and
+   * instance counts.
+   *
+   * @namespace
+   */
   Polymer.telemetry = {
+    /**
+     * Total number of Polymer element instances created.
+     * @type {number}
+     */
     instanceCount: 0,
+    /**
+     * Array of Polymer element classes that have been finalized.
+     * @type {Array<Polymer.Element>}
+     */
     registrations: [],
+    /**
+     * @private
+     */
     _regLog: function(prototype) {
       console.log('[' + prototype.is + ']: registered')
     },
+    /**
+     * Registers a class prototype for telemetry purposes.
+     * @protected
+     */
     register: function(prototype) {
       this.registrations.push(prototype);
       Polymer.log && this._regLog(prototype);
     },
+    /**
+     * Logs all elements registered with an `is` to the console.
+     * @public
+     */
     dumpRegistrations: function() {
       this.registrations.forEach(this._regLog);
     }