From ec831431a2df96867560662f70891a4bdc44fadc Mon Sep 17 00:00:00 2001 From: Kevin Schaaf Date: Mon, 25 May 2015 16:40:38 -0700 Subject: [PATCH 1/8] Update docs. Add warnings. Fixes #1538. Fixes #1206. --- index.html | 4 +-- src/lib/base.html | 2 +- src/lib/bind/effects.html | 28 ++++++++++++++--- src/lib/collection.html | 3 ++ src/micro/attributes.html | 54 ++++++++++++++++++++++++++++++-- src/micro/behaviors.html | 16 ++++++++++ src/micro/extends.html | 7 +++++ src/micro/properties.html | 39 +++++++++++++++++++++++ src/mini/ready.html | 18 +++++++++-- src/mini/shady.html | 32 +++++++++++-------- src/mini/template.html | 23 +++++++++----- src/standard/events.html | 40 +++++++++++++++++++++--- src/standard/notify-path.html | 58 +++++++++++++++++++++++++++++++---- src/standard/resolveUrl.html | 9 ++++++ src/standard/styling.html | 18 ++++++++--- src/standard/utils.html | 51 ++++++++++++++++++++++++++++-- src/standard/x-styling.html | 43 ++++++++++++++++---------- test/smoke/test-elements.html | 18 +++++++++++ test/smoke/test.html | 54 ++++++++++++++++++++++++++++++++ test/unit/base.html | 4 +-- 20 files changed, 455 insertions(+), 66 deletions(-) create mode 100644 test/smoke/test-elements.html create mode 100644 test/smoke/test.html diff --git a/index.html b/index.html index 77a180b286..0e01e8aa27 100644 --- a/index.html +++ b/index.html @@ -14,12 +14,12 @@ - + - + diff --git a/src/lib/base.html b/src/lib/base.html index f21c30bda7..b4ad987c67 100644 --- 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 index c1ca8661da..45322fbaa4 100644 --- a/src/lib/bind/effects.html +++ b/src/lib/bind/effects.html @@ -48,20 +48,38 @@ }, _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')); + } } }, diff --git a/src/lib/collection.html b/src/lib/collection.html index e3cfec83d5..2dfa00a2bc 100644 --- a/src/lib/collection.html +++ b/src/lib/collection.html @@ -15,6 +15,9 @@ Polymer._collections = new WeakMap(); Polymer.Collection = function(userArray) { + if (!Array.isArray(userArray)) { + host._warn(host._logf('Collection', 'expected array, found [%o]', userArray)); + } Polymer._collections.set(userArray, this); this.userArray = userArray; this.store = userArray.slice(); diff --git a/src/micro/attributes.html b/src/micro/attributes.html index 564ff42634..5eb8e1d2d3 100644 --- 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-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_(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_(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 index ea4e66196a..df7c9f9ba1 100644 --- 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(); diff --git a/src/mini/shady.html b/src/mini/shady.html index 71191e99c7..4a0ef45cfe 100644 --- a/src/mini/shady.html +++ b/src/mini/shady.html @@ -41,9 +41,9 @@ _setupRoot: function() { if (this._useContent) { this._createLocalRoot(); - // light elements may not be upgraded if they are light children - // and there is no configuration flow (no dataHost) and they are - // removed from document by shadyDOM distribution + // light elements may not be upgraded if they are light children + // and there is no configuration flow (no dataHost) and they are + // removed from document by shadyDOM distribution // so we ensure this here if (!this.dataHost) { upgradeLightChildren(this._lightChildren); @@ -79,9 +79,9 @@ * Force this element to distribute its children to its local dom. * A user should call `distributeContent` if distribution has been * invalidated due to changes to selectors on child elements that - * effect distribution that were not made via `Polymer.dom`. - * For example, if an element contains an insertion point with - * and a `foo` class is added to a child, + * effect distribution that were not made via `Polymer.dom`. + * For example, if an element contains an insertion point with + * `` and a `foo` class is added to a child, * then `distributeContent` must be called to update * local dom distribution. */ @@ -142,10 +142,18 @@ } }, - // This is a polyfill for Element.prototype.matches, which is sometimes - // still prefixed. Alternatively we could just polyfill it somewhere. - // Note that the arguments are reversed from what you might expect. + /** + * Polyfill for Element.prototype.matches, which is sometimes still + * prefixed. + * + * @method elementMatches + * @param {string} selector Selector to test. + * @param {Element=} node Element to test the selector against. + * @return {boolean} Whether the element matches the selector. + */ elementMatches: function(selector, node) { + // Alternatively we could just polyfill it somewhere. + // Note that the arguments are reversed from what you might expect. node = node || this; return matchesSelector.call(node, selector); }, @@ -197,7 +205,7 @@ for (var i=0, l=p$.length, p; (i` element * corresponding to the current Polymer prototype. - * - * The `