Merge pull request #4913 from Polymer/arthurevans-patch-1

Clarify API docs for PropertyAccessors mixin

lib/mixins/property-accessors.html

@@ -74,12 +74,18 @@
    * or more property accessors (getter/setter pair) that enqueue an async
    * (batched) `_propertiesChanged` callback.
    *
-   * For basic usage of this mixin, simply declare attributes to observe via
-   * 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. Last, call `this._enableProperties()` in the element's
-   * `connectedCallback` to enable the accessors.
+   * For basic usage of this mixin:
+   * 
+   * -   Declare attributes to observe via the standard `static get observedAttributes()`. Use
+   *     `dash-case` attribute names to represent `camelCase` property names. 
+   * -   Implement the `_propertiesChanged` callback on the class.
+   * -   Call `MyClass.createPropertiesForAttributes()` **once** on the class to generate 
+   *     property accessors for each observed attribute. This must be called before the first 
+   *     instance is created, for example, by calling it before calling `customElements.define`.
+   *     It can also be called lazily from the element's `constructor`, as long as it's guarded so
+   *     that the call is only made once, when the first instance is created.
+   * -   Call `this._enableProperties()` in the element's `connectedCallback` to enable 
+   *     the accessors.
    *
    * Any `observedAttributes` will automatically be
    * deserialized via `attributeChangedCallback` and set to the associated

types/lib/mixins/property-accessors.d.ts

@@ -21,12 +21,18 @@ declare namespace Polymer {
    * or more property accessors (getter/setter pair) that enqueue an async
    * (batched) `_propertiesChanged` callback.
    *
-   * For basic usage of this mixin, simply declare attributes to observe via
-   * 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. Last, call `this._enableProperties()` in the element's
-   * `connectedCallback` to enable the accessors.
+   * For basic usage of this mixin:
+   *
+   * -   Declare attributes to observe via the standard `static get observedAttributes()`. Use
+   *     `dash-case` attribute names to represent `camelCase` property names. 
+   * -   Implement the `_propertiesChanged` callback on the class.
+   * -   Call `MyClass.createPropertiesForAttributes()` **once** on the class to generate 
+   *     property accessors for each observed attribute. This must be called before the first 
+   *     instance is created, for example, by calling it before calling `customElements.define`.
+   *     It can also be called lazily from the element's `constructor`, as long as it's guarded so
+   *     that the call is only made once, when the first instance is created.
+   * -   Call `this._enableProperties()` in the element's `connectedCallback` to enable 
+   *     the accessors.
    *
    * Any `observedAttributes` will automatically be
    * deserialized via `attributeChangedCallback` and set to the associated