Skip to content

Commit 6dd6aa9

Browse files
author
Steve Orvell
committed
Merge pull request #1614 from Polymer/api-docs-warnings
Update docs. Add warnings.
2 parents 4678a0b + 091f867 commit 6dd6aa9

21 files changed

+741
-327
lines changed

‎index.html

+2-2
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,12 @@
1414
<meta name="viewport" content="width=device-width, initial-scale=1.0">
1515

1616
<script src="../webcomponentsjs/webcomponents-lite.js"></script>
17-
<link rel="import" href="../iron-doc-viewer/iron-doc-viewer.html">
17+
<link rel="import" href="../iron-component-page/iron-component-page.html">
1818

1919
</head>
2020
<body>
2121

22-
<iron-doc-viewer src="polymer.html"></iron-doc-viewer>
22+
<iron-component-page></iron-component-page>
2323

2424
</body>
2525
</html>

‎src/lib/base.html

+1-1
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@
4444

4545
// reserved for canonical behavior
4646
attributeChangedCallback: function(name) {
47-
this.setAttributeToProperty(this, name); // abstract
47+
this._setAttributeToProperty(this, name); // abstract
4848
this._doBehavior('attributeChanged', arguments); // abstract
4949
},
5050

‎src/lib/bind/effects.html

+36-13
Original file line numberDiff line numberDiff line change
@@ -48,33 +48,56 @@
4848
},
4949

5050
_observerEffect: function(source, value, effect, old) {
51-
this[effect.method](value, old);
51+
var fn = this[effect.method];
52+
if (fn) {
53+
fn.call(this, value, old);
54+
} else {
55+
this._warn(this._logf('_observerEffect', 'observer method `' +
56+
effect.method + '` not defined'));
57+
}
5258
},
5359

5460
_complexObserverEffect: function(source, value, effect) {
55-
var args = Polymer.Bind._marshalArgs(this.__data__, effect, source, value);
56-
if (args) {
57-
this[effect.method].apply(this, args);
61+
var fn = this[effect.method];
62+
if (fn) {
63+
var args = Polymer.Bind._marshalArgs(this.__data__, effect, source, value);
64+
if (args) {
65+
fn.apply(this, args);
66+
}
67+
} else {
68+
this._warn(this._logf('_complexObserverEffect', 'observer method `' +
69+
effect.method + '` not defined'));
5870
}
5971
},
6072

6173
_computeEffect: function(source, value, effect) {
6274
var args = Polymer.Bind._marshalArgs(this.__data__, effect, source, value);
6375
if (args) {
64-
this[effect.property] = this[effect.method].apply(this, args);
76+
var fn = this[effect.method];
77+
if (fn) {
78+
this[effect.property] = fn.apply(this, args);
79+
} else {
80+
this._warn(this._logf('_computeEffect', 'compute method `' +
81+
effect.method + '` not defined'));
82+
}
6583
}
6684
},
6785

6886
_annotatedComputationEffect: function(source, value, effect) {
69-
var args = Polymer.Bind._marshalArgs(this.__data__, effect, source, value);
70-
if (args) {
71-
var computedHost = this._rootDataHost || this;
72-
var computedvalue =
73-
computedHost[effect.method].apply(computedHost, args);
74-
if (effect.negate) {
75-
computedvalue = !computedvalue;
87+
var computedHost = this._rootDataHost || this;
88+
var fn = computedHost[effect.method];
89+
if (fn) {
90+
var args = Polymer.Bind._marshalArgs(this.__data__, effect, source, value);
91+
if (args) {
92+
var computedvalue = fn.apply(computedHost, args);
93+
if (effect.negate) {
94+
computedvalue = !computedvalue;
95+
}
96+
this._applyEffectValue(computedvalue, effect);
7697
}
77-
this._applyEffectValue(computedvalue, effect);
98+
} else {
99+
computedHost._warn(computedHost._logf('_annotatedComputationEffect',
100+
'compute method `' + effect.method + '` not defined'));
78101
}
79102
},
80103

‎src/lib/template/dom-repeat.html

+8-1
Original file line numberDiff line numberDiff line change
@@ -252,7 +252,14 @@
252252

253253
_itemsChanged: function(change) {
254254
if (change.path == 'items') {
255-
this.collection = this.items ? Polymer.Collection.get(this.items) : null;
255+
if (Array.isArray(this.items)) {
256+
this.collection = Polymer.Collection.get(this.items);
257+
} else if (!this.items) {
258+
this.collection = null;
259+
} else {
260+
this._error(this._logf('dom-repeat', 'expected array for `items`,' +
261+
' found', this.items));
262+
}
256263
this._splices = [];
257264
this._fullRefresh = true;
258265
this._debounceTemplate(this._render);

‎src/micro/attributes.html

+58-2
Original file line numberDiff line numberDiff line change
@@ -92,11 +92,11 @@
9292

9393
_takeAttributesToModel: function(model) {
9494
for (var i=0, l=this.attributes.length; i<l; i++) {
95-
this.setAttributeToProperty(model, this.attributes[i].name);
95+
this._setAttributeToProperty(model, this.attributes[i].name);
9696
}
9797
},
9898

99-
setAttributeToProperty: function(model, attrName) {
99+
_setAttributeToProperty: function(model, attrName) {
100100
// Don't deserialize back to property if currently reflecting
101101
if (!this._serializing) {
102102
var propName = Polymer.CaseMap.dashToCamelCase(attrName);
@@ -111,20 +111,65 @@
111111

112112
_serializing: false,
113113

114+
/**
115+
* Serializes a property to its associated attribute.
116+
*
117+
* Generally users should set `reflectToAttribute: true` in the
118+
* `properties` configuration to achieve automatic attribute reflection.
119+
*
120+
* @method reflectPropertyToAttribute
121+
* @param {string} name Property name to reflect.
122+
*/
114123
reflectPropertyToAttribute: function(name) {
115124
this._serializing = true;
116125
this.serializeValueToAttribute(this[name],
117126
Polymer.CaseMap.camelToDashCase(name));
118127
this._serializing = false;
119128
},
120129

130+
/**
131+
* Sets a typed value to an HTML attribute on a node.
132+
*
133+
* This method calls the `serialize` method to convert the typed
134+
* value to a string. If the `serialize` method returns `undefined`,
135+
* the attribute will be removed (this is the default for boolean
136+
* type `false`).
137+
*
138+
* @method serializeValueToAttribute
139+
* @param {*} value Value to serialize.
140+
* @param {string} attribute Attribute name to serialize to.
141+
* @param {Element=} node Element to set attribute to (defaults to this).
142+
*/
121143
serializeValueToAttribute: function(value, attribute, node) {
122144
var str = this.serialize(value);
145+
// TODO(kschaaf): Consider enabling under a flag
146+
// if (str && str.length > 250) {
147+
// this._warn(this._logf('serializeValueToAttribute',
148+
// 'serializing long attribute values can lead to poor performance', this));
149+
// }
123150
(node || this)
124151
[str === undefined ? 'removeAttribute' : 'setAttribute']
125152
(attribute, str);
126153
},
127154

155+
/**
156+
* Converts a string to a typed value.
157+
*
158+
* This method is called by Polymer when reading HTML attribute values to
159+
* JS properties. Users may override this method on Polymer element
160+
* prototypes to provide deserialization for custom `type`s. Note,
161+
* the `type` argument is the value of the `type` field provided in the
162+
* `properties` configuration object for a given property, and is
163+
* by convention the constructor for the type to deserialize.
164+
*
165+
* Note: The return value of `undefined` is used as a sentinel value to
166+
* indicate the attribute should be removed.
167+
*
168+
* @method deserialize
169+
* @param {string} value Attribute value to deserialize.
170+
* @param {*} type Type to deserialize the string to.
171+
* @return {*} Typed value deserialized from the provided string.
172+
*/
128173
deserialize: function(value, type) {
129174
switch (type) {
130175
case Number:
@@ -163,6 +208,17 @@
163208
return value;
164209
},
165210

211+
/**
212+
* Converts a typed value to a string.
213+
*
214+
* This method is called by Polymer when setting JS property values to
215+
* HTML attributes. Users may override this method on Polymer element
216+
* prototypes to provide serialization for custom types.
217+
*
218+
* @method serialize
219+
* @param {*} value Property value to serialize.
220+
* @return {string} String serialized from the provided property value.
221+
*/
166222
serialize: function(value) {
167223
switch (typeof value) {
168224
case 'boolean':

‎src/micro/behaviors.html

+16
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,22 @@
4040

4141
Polymer.Base._addFeature({
4242

43+
/**
44+
* Array of objects to extend this prototype with.
45+
*
46+
* Each entry in the array may specify either a behavior object or array
47+
* of behaviors.
48+
*
49+
* Each behavior object may define lifecycle callbacks, `properties`,
50+
* `hostAttributes`, `observers` and `listeners`.
51+
*
52+
* Lifecycle callbacks will be called for each behavior in the order given
53+
* in the `behaviors` array, followed by the callback on the prototype.
54+
* Additionally, any non-lifecycle functions on the behavior object are
55+
* mixed into the base prototype, such that same-named functions on the
56+
* prototype take precedence, followed by later behaviors over earlier
57+
* behaviors.
58+
*/
4359
behaviors: [],
4460

4561
_prepBehaviors: function() {

‎src/micro/extends.html

+7
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,13 @@
6969
return p;
7070
},
7171

72+
/**
73+
* Returns the native element prototype for the tag specified.
74+
*
75+
* @method getNativePrototype
76+
* @param {string} tag HTML tag name.
77+
* @return {Object} Native prototype for specified tag.
78+
*/
7279
getNativePrototype: function(tag) {
7380
// TODO(sjmiles): sad necessity
7481
return Object.getPrototypeOf(document.createElement(tag));

‎src/micro/properties.html

+39
Original file line numberDiff line numberDiff line change
@@ -58,9 +58,48 @@
5858

5959
Polymer.Base._addFeature({
6060

61+
/*
62+
* Object containing property configuration data, where keys are property
63+
* names and values are descriptor objects that configure Polymer features
64+
* for the property. Valid fields in the property descriptor object are
65+
* as follows:
66+
*
67+
* * `type` - used to determine how to deserialize attribute value strings
68+
* to JS properties. By convention, this field takes a JS constructor
69+
* for the type, such as `String` or `Boolean`.
70+
* * `notify` - when `true`, configures the property to fire a non-bubbling
71+
* event called `<property>-changed` for each change to the property.
72+
* Elements that have enabled two-way binding to the property use this
73+
* event to observe changes.
74+
* * `readOnly` - when `true` configures the property to have a getter, but
75+
* no setter. To set a read-only property, use the private setter method
76+
* `_set_<property>(value)`.
77+
* * `reflectToAttribute` - when `true` configures the property to have a
78+
* getter, but no setter. To set a read-only property, use the private
79+
* setter method `_set_<property>(value)`.
80+
* * `observer` - indicates the name of a funciton that should be called
81+
* each time the property changes. `e.g.: `observer: 'valueChanged'
82+
* * `computed` - configures the property to be computed by a computing
83+
* function each time one or more dependent properties change.
84+
* `e.g.: `computed: 'computeValue(prop1, prop2)'
85+
*
86+
* Note: a shorthand may be used for the object descriptor when only the
87+
* type needs to be specified by using the type as the descriptor directly.
88+
*/
6189
properties: {
6290
},
6391

92+
/**
93+
* Returns a property descriptor object for the property specified.
94+
*
95+
* This method allows introspecting the configuration of a Polymer element's
96+
* properties as configured in its `properties` object. Note, this method
97+
* normalizes shorthand forms of the `properties` object into longhand form.
98+
*
99+
* @method getPropertyInfo
100+
* @param {string} property Name of property to introspect.
101+
* @return {Object} Property descriptor for specified property.
102+
*/
64103
getPropertyInfo: function(property) {
65104
var info = this._getPropertyInfo(property, this.properties);
66105
if (!info) {

‎src/mini/ready.html

+16-2
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,13 @@
3737

3838
_hostStack: [],
3939

40-
// for overriding
40+
/**
41+
* Lifecycle callback invoked when all local DOM children of this element
42+
* have been created and "configured" with data bound from this element,
43+
* attribute values, or defaults.
44+
*
45+
* @method ready
46+
*/
4147
ready: function() {
4248
},
4349

@@ -137,7 +143,15 @@
137143
_afterClientsReady: function() {},
138144
_beforeAttached: function() {},
139145

140-
// normalize lifecycle: ensure attached occurs only after ready.
146+
/**
147+
* Polymer library implementation of the Custom Elements `attachedCallback`.
148+
*
149+
* Note, users should not override `attachedCallback`, and instead should
150+
* implement the `attached` method on Polymer elements to receive
151+
* attached-time callbacks.
152+
*
153+
* @protected
154+
*/
141155
attachedCallback: function() {
142156
if (this._readied) {
143157
this._beforeAttached();

0 commit comments

Comments
 (0)