API docs for property-accessors

src/mixins/element-mixin.html

@@ -22,8 +22,6 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
  * features including template stamping, data-binding, attribute deserialization,
  * and property change observation.
  *
- * TODOC
- *
  * @polymerMixin
  * @mixes Polymer.PropertyEffects
  * @memberof Polymer

src/mixins/property-accessors.html

@@ -79,7 +79,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
    * the standard `static get observedAttributes()`, implement `_propertiesChanged`
    * on the class, and then call `MyClass.createPropertiesForAttributes()` once
    * on the class to generate property accessors for each observed attribute
-   * prior to instancing.
+   * prior to instancing.  Any `observedAttributes` will automatically be
+   * deserialized via `attributeChangedCallback` and set to the associated
+   * property using `dash-case`-to-`camelCase` convention.
    *
    * TODOC
    *
@@ -90,6 +92,14 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
     return class PropertyAccessors extends superClass {
 
+      /**
+       * Generates property accessors for all attributes in the standard
+       * static `observedAttributes` array.
+       *
+       * Attribute names are mapped to property names using the `dash-case` to
+       * `camelCase` convention
+       *
+       */
       static createPropertiesForAttributes() {
         let a$ = this.observedAttributes;
         for (let i=0; i < a$.length; i++) {
@@ -111,12 +121,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       /**
        * Initializes the local storage for property accessors.
        *
-       * Default initialization via initializing
-       * local property & pending data storage with any accessor values saved
-       * in `__dataProto`.  If instance properties had been set before the
-       * element upgraded and gained accessors on its prototype, these values
-       * are set into the prototype's accessors after being deleted from the
-       * instance.
+       * Provided as an override point for performing any setup work prior
+       * to initializing the property accessor system.
        *
        * @protected
        */
@@ -133,6 +139,18 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
         }
       }
 
+      /**
+       * Called at instance time with bag of properties that were overwritten
+       * by accessors on the prototype when accessors were created.
+       *
+       * The default implementation sets these properties back into the
+       * setter at instance time.  This method is provided as an override
+       * point for customizing or providing more efficient initialization.
+       *
+       * @param {Object} props Bag of property values that were overwritten
+       *   when creating property accessors.
+       * @protected
+       */
       _initializeProtoProperties(props) {
         for (let p in props) {
           this._setProperty(p, props[p]);