From ae58e88b160b28eef161cccb4bd4da7a53ea0b58 Mon Sep 17 00:00:00 2001 From: Arthur Evans Date: Wed, 1 Nov 2017 15:22:03 -0700 Subject: [PATCH] Clarify API docs for PropertyAccessors mixin --- lib/mixins/property-accessors.html | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/lib/mixins/property-accessors.html b/lib/mixins/property-accessors.html index 15900ab7bc..aad5ee7373 100644 --- a/lib/mixins/property-accessors.html +++ b/lib/mixins/property-accessors.html @@ -75,12 +75,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