Merge pull request #1614 from Polymer/api-docs-warnings

Update docs. Add warnings.
Polymer · May 26, 2015 · 6dd6aa9 · 6dd6aa9
2 parents 4678a0b + 091f867
commit 6dd6aa9
Show file tree

Hide file tree

Showing 21 changed files with 741 additions and 327 deletions.
diff --git a/index.html b/index.html
@@ -14,12 +14,12 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
   <script src="../webcomponentsjs/webcomponents-lite.js"></script>
-  <link rel="import" href="../iron-doc-viewer/iron-doc-viewer.html">
+  <link rel="import" href="../iron-component-page/iron-component-page.html">
 
 </head>
 <body>
 
-  <iron-doc-viewer src="polymer.html"></iron-doc-viewer>
+  <iron-component-page></iron-component-page>
 
 </body>
 </html>
diff --git a/src/lib/base.html b/src/lib/base.html
@@ -44,7 +44,7 @@
 
     // reserved for canonical behavior
     attributeChangedCallback: function(name) {
-      this.setAttributeToProperty(this, name); // abstract
+      this._setAttributeToProperty(this, name); // abstract
       this._doBehavior('attributeChanged', arguments); // abstract
     },
 

diff --git a/src/lib/bind/effects.html b/src/lib/bind/effects.html
@@ -48,33 +48,56 @@
     },
 
     _observerEffect: function(source, value, effect, old) {
-      this[effect.method](value, old);
+      var fn = this[effect.method];
+      if (fn) {
+        fn.call(this, value, old);
+      } else {
+        this._warn(this._logf('_observerEffect', 'observer method `' +
+          effect.method + '` not defined'));
+      }
     },
 
     _complexObserverEffect: function(source, value, effect) {
-      var args = Polymer.Bind._marshalArgs(this.__data__, effect, source, value);
-      if (args) {
-        this[effect.method].apply(this, args);
+      var fn = this[effect.method];
+      if (fn) {
+        var args = Polymer.Bind._marshalArgs(this.__data__, effect, source, value);
+        if (args) {
+          fn.apply(this, args);
+        }
+      } else {
+        this._warn(this._logf('_complexObserverEffect', 'observer method `' +
+          effect.method + '` not defined'));
       }
     },
 
     _computeEffect: function(source, value, effect) {
       var args = Polymer.Bind._marshalArgs(this.__data__, effect, source, value);
       if (args) {
-        this[effect.property] = this[effect.method].apply(this, args);
+        var fn = this[effect.method];
+        if (fn) {
+          this[effect.property] = fn.apply(this, args);
+        } else {
+          this._warn(this._logf('_computeEffect', 'compute method `' +
+            effect.method + '` not defined'));
+        }
       }
     },
 
     _annotatedComputationEffect: function(source, value, effect) {
-      var args = Polymer.Bind._marshalArgs(this.__data__, effect, source, value);
-      if (args) {
-        var computedHost = this._rootDataHost || this;
-        var computedvalue =
-          computedHost[effect.method].apply(computedHost, args);
-        if (effect.negate) {
-          computedvalue = !computedvalue;
+      var computedHost = this._rootDataHost || this;
+      var fn = computedHost[effect.method];
+      if (fn) {
+        var args = Polymer.Bind._marshalArgs(this.__data__, effect, source, value);
+        if (args) {
+          var computedvalue = fn.apply(computedHost, args);
+          if (effect.negate) {
+            computedvalue = !computedvalue;
+          }
+          this._applyEffectValue(computedvalue, effect);
         }
-        this._applyEffectValue(computedvalue, effect);
+      } else {
+        computedHost._warn(computedHost._logf('_annotatedComputationEffect',
+          'compute method `' + effect.method + '` not defined'));
       }
     },
 

diff --git a/src/lib/template/dom-repeat.html b/src/lib/template/dom-repeat.html
@@ -252,7 +252,14 @@
 
     _itemsChanged: function(change) {
       if (change.path == 'items') {
-        this.collection = this.items ? Polymer.Collection.get(this.items) : null;
+        if (Array.isArray(this.items)) {
+          this.collection = Polymer.Collection.get(this.items);
+        } else if (!this.items) {
+          this.collection = null;
+        } else {
+          this._error(this._logf('dom-repeat', 'expected array for `items`,' +
+            ' found', this.items));
+        }
         this._splices = [];
         this._fullRefresh = true;
         this._debounceTemplate(this._render);

diff --git a/src/micro/attributes.html b/src/micro/attributes.html
@@ -92,11 +92,11 @@
 
     _takeAttributesToModel: function(model) {
       for (var i=0, l=this.attributes.length; i<l; i++) {
-        this.setAttributeToProperty(model, this.attributes[i].name);
+        this._setAttributeToProperty(model, this.attributes[i].name);
       }
     },
 
-    setAttributeToProperty: function(model, attrName) {
+    _setAttributeToProperty: function(model, attrName) {
       // Don't deserialize back to property if currently reflecting
       if (!this._serializing) {
         var propName = Polymer.CaseMap.dashToCamelCase(attrName);
@@ -111,20 +111,65 @@
 
     _serializing: false,
 
+    /**
+     * Serializes a property to its associated attribute.
+     *
+     * Generally users should set `reflectToAttribute: true` in the
+     * `properties` configuration to achieve automatic attribute reflection.
+     *
+     * @method reflectPropertyToAttribute
+     * @param {string} name Property name to reflect.
+     */
     reflectPropertyToAttribute: function(name) {
       this._serializing = true;
       this.serializeValueToAttribute(this[name],
         Polymer.CaseMap.camelToDashCase(name));
       this._serializing = false;
     },
 
+    /**
+     * Sets a typed value to an HTML attribute on a node.
+     *
+     * This method calls the `serialize` method to convert the typed
+     * value to a string.  If the `serialize` method returns `undefined`,
+     * the attribute will be removed (this is the default for boolean
+     * type `false`).
+     *
+     * @method serializeValueToAttribute
+     * @param {*} value Value to serialize.
+     * @param {string} attribute Attribute name to serialize to.
+     * @param {Element=} node Element to set attribute to (defaults to this).
+     */
     serializeValueToAttribute: function(value, attribute, node) {
       var str = this.serialize(value);
+      // TODO(kschaaf): Consider enabling under a flag
+      // if (str && str.length > 250) {
+      //   this._warn(this._logf('serializeValueToAttribute',
+      //     'serializing long attribute values can lead to poor performance', this));
+      // }
       (node || this)
         [str === undefined ? 'removeAttribute' : 'setAttribute']
           (attribute, str);
     },
 
+    /**
+     * Converts a string to a typed value.
+     *
+     * This method is called by Polymer when reading HTML attribute values to
+     * JS properties.  Users may override this method on Polymer element
+     * prototypes to provide deserialization for custom `type`s.  Note,
+     * the `type` argument is the value of the `type` field provided in the
+     * `properties` configuration object for a given property, and is
+     * by convention the constructor for the type to deserialize.
+     *
+     * Note: The return value of `undefined` is used as a sentinel value to
+     * indicate the attribute should be removed.
+     *
+     * @method deserialize
+     * @param {string} value Attribute value to deserialize.
+     * @param {*} type Type to deserialize the string to.
+     * @return {*} Typed value deserialized from the provided string.
+     */
     deserialize: function(value, type) {
       switch (type) {
         case Number:
@@ -163,6 +208,17 @@
       return value;
     },
 
+    /**
+     * Converts a typed value to a string.
+     *
+     * This method is called by Polymer when setting JS property values to
+     * HTML attributes.  Users may override this method on Polymer element
+     * prototypes to provide serialization for custom types.
+     *
+     * @method serialize
+     * @param {*} value Property value to serialize.
+     * @return {string} String serialized from the provided property value.
+     */
     serialize: function(value) {
       switch (typeof value) {
         case 'boolean':

diff --git a/src/micro/behaviors.html b/src/micro/behaviors.html
@@ -40,6 +40,22 @@
 
   Polymer.Base._addFeature({
 
+    /**
+     * Array of objects to extend this prototype with.
+     *
+     * Each entry in the array may specify either a behavior object or array
+     * of behaviors.
+     *
+     * Each behavior object may define lifecycle callbacks, `properties`,
+     * `hostAttributes`, `observers` and `listeners`.
+     *
+     * Lifecycle callbacks will be called for each behavior in the order given
+     * in the `behaviors` array, followed by the callback on the prototype.
+     * Additionally, any non-lifecycle functions on the behavior object are
+     * mixed into the base prototype, such that same-named functions on the
+     * prototype take precedence, followed by later behaviors over earlier
+     * behaviors.
+     */
     behaviors: [],
 
     _prepBehaviors: function() {

diff --git a/src/micro/extends.html b/src/micro/extends.html
@@ -69,6 +69,13 @@
       return p;
     },
 
+    /**
+     * Returns the native element prototype for the tag specified.
+     *
+     * @method getNativePrototype
+     * @param {string} tag  HTML tag name.
+     * @return {Object} Native prototype for specified tag.
+    */
     getNativePrototype: function(tag) {
       // TODO(sjmiles): sad necessity
       return Object.getPrototypeOf(document.createElement(tag));

diff --git a/src/micro/properties.html b/src/micro/properties.html
@@ -58,9 +58,48 @@
 
   Polymer.Base._addFeature({
 
+    /*
+     * Object containing property configuration data, where keys are property
+     * names and values are descriptor objects that configure Polymer features
+     * for the property.  Valid fields in the property descriptor object are
+     * as follows:
+     *
+     * * `type` - used to determine how to deserialize attribute value strings
+     *    to JS properties.  By convention, this field takes a JS constructor
+     *    for the type, such as `String` or `Boolean`.
+     * * `notify` - when `true`, configures the property to fire a non-bubbling
+     *    event called `<property>-changed` for each change to the property.
+     *    Elements that have enabled two-way binding to the property use this
+     *    event to observe changes.
+     * * `readOnly` - when `true` configures the property to have a getter, but
+     *    no setter. To set a read-only property, use the private setter method
+     *    `_set_<property>(value)`.
+     * * `reflectToAttribute` - when `true` configures the property to have a
+     *    getter, but no setter. To set a read-only property, use the private
+     *    setter method `_set_<property>(value)`.
+     * * `observer` - indicates the name of a funciton that should be called
+     *    each time the property changes. `e.g.: `observer: 'valueChanged'
+     * * `computed` - configures the property to be computed by a computing
+     *    function each time one or more dependent properties change.
+     *    `e.g.: `computed: 'computeValue(prop1, prop2)'
+     *
+     * Note: a shorthand may be used for the object descriptor when only the
+     * type needs to be specified by using the type as the descriptor directly.
+     */
     properties: {
     },
 
+    /**
+     * Returns a property descriptor object for the property specified.
+     *
+     * This method allows introspecting the configuration of a Polymer element's
+     * properties as configured in its `properties` object.  Note, this method
+     * normalizes shorthand forms of the `properties` object into longhand form.
+     *
+     * @method getPropertyInfo
+     * @param {string} property Name of property to introspect.
+     * @return {Object} Property descriptor for specified property.
+    */
     getPropertyInfo: function(property) {
       var info = this._getPropertyInfo(property, this.properties);
       if (!info) {

diff --git a/src/mini/ready.html b/src/mini/ready.html
@@ -37,7 +37,13 @@
 
     _hostStack: [],
 
-    // for overriding
+    /**
+     * Lifecycle callback invoked when all local DOM children of this element
+     * have been created and "configured" with data bound from this element,
+     * attribute values, or defaults.
+     *
+     * @method ready
+     */
     ready: function() {
     },
 
@@ -137,7 +143,15 @@
     _afterClientsReady: function() {},
     _beforeAttached: function() {},
 
-    // normalize lifecycle: ensure attached occurs only after ready.
+    /**
+     * Polymer library implementation of the Custom Elements `attachedCallback`.
+     *
+     * Note, users should not override `attachedCallback`, and instead should
+     * implement the `attached` method on Polymer elements to receive
+     * attached-time callbacks.
+     *
+     * @protected
+     */
     attachedCallback: function() {
       if (this._readied) {
         this._beforeAttached();