clarify that users of Polymer mixin have to call polymerCreated

pkg/polymer/lib/src/instance.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of polymer;
 
 /**
  * Use this annotation to publish a field as an attribute. For example:
  *
  *     class MyPlaybackElement extends PolymerElement {
  *       // This will be available as an HTML attribute, for example:
  *       //     <my-playback volume="11">
  *       @published double volume;
  *     }
  */
 // TODO(jmesserly): does @published imply @observable or vice versa?
 const published = const PublishedProperty();
 
 /** An annotation used to publish a field as an attribute. See [published]. */
 class PublishedProperty extends ObservableProperty {
   const PublishedProperty();
 }
 
 /**
  * The mixin class for Polymer elements. It provides convenience features on top
  * of the custom elements web standard.
+ *
+ * If this class is used as a mixin,
+ * you must call `polymerCreated()` from the body of your constructor.
  */
 abstract class Polymer implements Element, Observable, NodeBindExtension {
   // Fully ported from revision:
   // https://github.com/Polymer/polymer/blob/b7200854b2441a22ce89f6563963f36c50f5150d
   //
   //   src/boot.js (static APIs on "Polymer" object)
   //   src/instance/attributes.js
   //   src/instance/base.js
   //   src/instance/events.js
   //   src/instance/mdv.js
@@ skipping 80 matching lines @@
    * Gets the shadow root associated with the corresponding custom element.
    *
    * This is identical to [shadowRoot], unless there are multiple levels of
    * inheritance and they each have their own shadow root. For example,
    * this can happen if the base class and subclass both have `<template>` tags
    * in their `<polymer-element>` tags.
    */
   // TODO(jmesserly): Polymer does not have this feature. Reconcile.
   ShadowRoot getShadowRoot(String customTagName) => _shadowRoots[customTagName];
 
+  /**
+   * If this class is used as a mixin, this method must be called from inside
+   * of the `created()` constructor.
+   *
+   * If this class is a superclass, calling `super.created()` is sufficient.
+   */
   void polymerCreated() {
     if (this.ownerDocument.window != null || alwaysPrepare ||
         _preparingElements > 0) {
       prepareElement();
     }
   }
 
   /** Retrieves the custom element name by inspecting the host node. */
   String get _customTagName {
     var isAttr = attributes['is'];
@@ skipping 944 matching lines @@
 
 class _PropertyValue {
   Object oldValue, newValue;
   _PropertyValue(this.oldValue);
 }
 
 class _PolymerExpressionsWithEventDelegate extends PolymerExpressions {
   prepareBinding(String path, name, node) =>
       Polymer.prepareBinding(path, name, node, super.prepareBinding);
 }