Skip to content

Commit 8a11c8c

Browse files
kevinpschaafkevinpschaaf
committed
Fix jsdoc issues.
1 parent 72a454e commit 8a11c8c

4 files changed

Lines changed: 97 additions & 51 deletions

File tree

‎lib/mixins/element-mixin.html‎

Lines changed: 53 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,9 @@
126126
* (1) super chain mixes togther to make `propertiesForClass` which is
127127
* then used to make `observedAttributes`.
128128
* (2) properties effects and observers are created from it at `finalize` time.
129-
* @param {HTMLElement} klass
129+
*
130+
* @param {HTMLElement} klass Element class
131+
* @return {Object} Object containing own properties for this class
130132
* @private
131133
*/
132134
function ownPropertiesForClass(klass) {
@@ -142,7 +144,9 @@
142144
/**
143145
* Returns the `observers` array specifically on `klass`. Use for
144146
* setting up observers.
145-
* @param {HTMLElement} klass
147+
*
148+
* @param {HTMLElement} klass Element class
149+
* @return {Array} Array containing own observers for this class
146150
* @private
147151
*/
148152
function ownObserversForClass(klass) {
@@ -158,8 +162,10 @@
158162
/**
159163
* Mixes `props` into `flattenedProps` but upgrades shorthand type
160164
* syntax to { type: Type}.
161-
* @param {Object} flattenedProps
162-
* @param {Object} props
165+
*
166+
* @param {Object} flattenedProps Bag to collect flattened properties into
167+
* @param {Object} props Bag of properties to add to `flattenedProps`
168+
* @return {Objecg} The input `flattenedProps` bag
163169
* @private
164170
*/
165171
function flattenProperties(flattenedProps, props) {
@@ -178,8 +184,9 @@
178184
* constructor's `config.properties`. This list is used to create
179185
* (1) observedAttributes,
180186
* (2) class property default values
181-
* @param {HTMLElement} klass
182-
* @return {PolymerElementProperties}
187+
*
188+
* @param {HTMLElement} klass Element class
189+
* @return {PolymerElementProperties} Flattened properties for this class
183190
* @private
184191
*/
185192
function propertiesForClass(klass) {
@@ -202,8 +209,10 @@
202209
* This list is created as an optimization since it is a subset of
203210
* the list returned from `propertiesForClass`.
204211
* This list is used in `_initializeProperties` to set property defaults.
205-
* @param {HTMLElement} klass
206-
* @return {PolymerElementProperties}
212+
*
213+
* @param {HTMLElement} klass Element class
214+
* @return {PolymerElementProperties} Flattened properties for this class
215+
* that have default values
207216
* @private
208217
*/
209218
function propertyDefaultsForClass(klass) {
@@ -224,7 +233,9 @@
224233

225234
/**
226235
* Returns true if a `klass` has finalized. Called in `ElementClass.finalize()`
227-
* @param {HTMLElement} klass
236+
* @param {HTMLElement} klass Element class
237+
* @return {boolean} True if all metaprogramming for this class has been
238+
* completed
228239
* @private
229240
*/
230241
function hasClassFinalized(klass) {
@@ -235,7 +246,8 @@
235246
* Called by `ElementClass.finalize()`. Ensures this `klass` and
236247
* *all superclasses* are finalized by traversing the prototype chain
237248
* and calling `klass.finalize()`.
238-
* @param {HTMLElement} klass
249+
*
250+
* @param {HTMLElement} klass Element class
239251
* @private
240252
*/
241253
function finalizeClassAndSuper(klass) {
@@ -252,6 +264,9 @@
252264
* a `template`. This includes creating accessors and effects
253265
* for properties in `config` and the `template` as well as preparing the
254266
* `template` for stamping.
267+
*
268+
* @param {HTMLElement} klass Element class
269+
* @private
255270
*/
256271
function finalizeClass(klass) {
257272
klass.__finalized = true;
@@ -287,8 +302,10 @@
287302
* Leverages `PropertyEffects` to create property accessors and effects
288303
* supporting, observers, reflecting to attributes, change notification,
289304
* computed properties, and read only properties.
290-
* @param {HTMLElement} proto
291-
* @param {Object} properties
305+
* @param {HTMLElement} proto Element class prototype to add accessors
306+
* and effects to
307+
* @param {Object} properties Flattened bag of property descriptors for
308+
* this class
292309
* @private
293310
*/
294311
function finalizeProperties(proto, properties) {
@@ -300,13 +317,18 @@
300317
/**
301318
* Configures a `proto` based on a `observers` array.
302319
* Leverages `PropertyEffects` to create observers.
303-
* @param {HTMLElement} proto
304-
* @param {Array} observers
320+
* @param {HTMLElement} proto Element class prototype to add accessors
321+
* and effects to
322+
* @param {Object} observers Flattened array of observer descriptors for
323+
* this class
324+
* @param {Object} dynamicFns Object containing keys for any properties
325+
* that are functions and should trigger the effect when the function
326+
* reference is changed
305327
* @private
306328
*/
307-
function finalizeObservers(proto, observers, dynamicProperties) {
329+
function finalizeObservers(proto, observers, dynamicFns) {
308330
for (let i=0; i < observers.length; i++) {
309-
proto._createMethodObserver(observers[i], dynamicProperties);
331+
proto._createMethodObserver(observers[i], dynamicFns);
310332
}
311333
}
312334

@@ -359,7 +381,8 @@
359381
* and/or provide an advanced api for manipulating them.
360382
* Also consider adding warnings when an effect cannot be changed.
361383
*
362-
* @param {HTMLElement} proto
384+
* @param {HTMLElement} proto Element class prototype to add accessors
385+
* and effects to
363386
* @param {string} name Name of the property.
364387
* @param {object} info Info object from which to create property effects.
365388
* Supported keys:
@@ -399,12 +422,14 @@
399422
* Configures an element `proto` to function with a given `template`.
400423
* The element name `is` and extends `ext` must be specified for ShadyCSS
401424
* style scoping.
402-
* @param {HTMLElement} proto
403-
* @param {HTMLTemplateElement} template
425+
*
426+
* @param {HTMLElement} proto Element class prototype to add accessors
427+
* and effects to
428+
* @param {HTMLTemplateElement} template Template to process and bind
404429
* @param {string} baseURI URL against which to resolve urls in
405-
* style element cssText.
406-
* @param {string} is
407-
* @param {string} ext
430+
* style element cssText
431+
* @param {string} is Tag name (or type extension name) for this element
432+
* @param {string=} ext For type extensions, the tag name that was extended
408433
* @private
409434
*/
410435
function finalizeTemplate(proto, template, baseURI, is, ext) {
@@ -470,7 +495,7 @@
470495
}
471496

472497
/**
473-
* Returns the template stamped into this element's shadow root.
498+
* Returns the template that will be stamped into this element's shadow root.
474499
*
475500
* If a `static get is()` getter is defined, the default implementation
476501
* will return the first `<template>` in a `dom-module` whose `id`
@@ -504,7 +529,7 @@
504529
* }
505530
* }
506531
*
507-
* @returns {HTMLTemplateElement|string}
532+
* @returns {HTMLTemplateElement|string} Template to be stamped
508533
*/
509534
static get template() {
510535
if (!this.hasOwnProperty(goog.reflect.objectProperty('_template', this))) {
@@ -526,7 +551,7 @@
526551
* matching this element's static `is` property.
527552
* Note, this path should contain a trailing `/`.
528553
*
529-
* @returns {string}
554+
* @returns {string} The import path for this element class
530555
*/
531556
static get importPath() {
532557
if (!this.hasOwnProperty(goog.reflect.objectProperty('_importPath', this))) {
@@ -833,13 +858,15 @@
833858
*/
834859
registrations: [],
835860
/**
861+
* @param {HTMLElement} prototype Element prototype to log
836862
* @private
837863
*/
838864
_regLog: function(prototype) {
839865
console.log('[' + prototype.is + ']: registered')
840866
},
841867
/**
842868
* Registers a class prototype for telemetry purposes.
869+
* @param {HTMLElement} prototype Element prototype to register
843870
* @protected
844871
*/
845872
register: function(prototype) {
@@ -868,7 +895,7 @@
868895
*
869896
* These properties are retained unless a value of `null` is set.
870897
*
871-
* @param {Object=} properties Bag of custom property key/values to
898+
* @param {Object=} props Bag of custom property key/values to
872899
* apply to the document.
873900
*/
874901
Polymer.updateStyles = function(props) {

‎lib/mixins/property-accessors.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -427,6 +427,7 @@
427427
*
428428
* @param {string} property Name of the property
429429
* @param {*} value Value to set
430+
* @return {boolean} Returns true if the property changed
430431
* @protected
431432
*/
432433
_setPendingProperty(property, value) {

0 commit comments

Comments
 (0)