From 290596a3d307495abb5d774239c50ee5d633fe6f Mon Sep 17 00:00:00 2001 From: Kevin Schaaf Date: Wed, 22 Feb 2017 00:28:44 -0800 Subject: [PATCH] Add @namespace annotations & "TODOC" todo's --- src/elements/custom-style.html | 3 + src/elements/dom-module.html | 3 + src/legacy/legacy-element-mixin.html | 54 ++++++ src/legacy/polymer-fn.html | 1 - src/legacy/polymer.dom.html | 54 +++++- src/legacy/templatizer-behavior.html | 9 + src/utils/array-splice.html | 13 +- src/utils/async.html | 258 ++++++++++++++++----------- src/utils/boot.html | 3 + src/utils/case-map.html | 22 +++ src/utils/flush.html | 10 ++ src/utils/gestures.html | 127 +++++++++---- src/utils/import-href.html | 1 + src/utils/mixin.html | 9 +- src/utils/path.html | 51 +++++- src/utils/render-status.html | 16 ++ src/utils/resolve-url.html | 34 +++- src/utils/style-gather.html | 48 ++++- src/utils/templatize.html | 26 ++- 19 files changed, 587 insertions(+), 155 deletions(-) diff --git a/src/elements/custom-style.html b/src/elements/custom-style.html index 5e019ae1..217278d7 100644 --- a/src/elements/custom-style.html +++ b/src/elements/custom-style.html @@ -40,6 +40,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN this._style = null; CustomStyleInterface.addCustomStyle(this); } + /** + * TODOC + */ getStyle() { if (this._style) { return this._style; diff --git a/src/elements/dom-module.html b/src/elements/dom-module.html index 73e9c39a..9da5ac56 100644 --- a/src/elements/dom-module.html +++ b/src/elements/dom-module.html @@ -43,6 +43,9 @@ } } + /** + * TODOC + */ get assetpath() { // Don't override existing assetpath. if (!this.__assetpath) { diff --git a/src/legacy/legacy-element-mixin.html b/src/legacy/legacy-element-mixin.html index 88b8370e..a652153e 100644 --- a/src/legacy/legacy-element-mixin.html +++ b/src/legacy/legacy-element-mixin.html @@ -59,6 +59,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN this.created(); } + /** + * TODOC + */ created() {} connectedCallback() { @@ -67,6 +70,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN this.attached(); } + /** + * TODOC + */ attached() {} disconnectedCallback() { @@ -75,6 +81,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN this.detached(); } + /** + * TODOC + */ detached() {} attributeChangedCallback(name, old, value) { @@ -84,8 +93,16 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN } } + /** + * TODOC + */ attributeChanged() {} + /** + * TODOC + * + * @override + */ _initializeProperties() { this._registered(); super._initializeProperties(); @@ -100,6 +117,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN */ _registered() {} + /** + * TODOC + * + * @override + */ ready() { this._ensureAttributes(); this._applyListeners(); @@ -130,18 +152,30 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN */ _applyListeners() {} + /** + * TODOC + */ serialize(value) { return this._serializeValue(value); } + /** + * TODOC + */ deserialize(value, type) { return this._deserializeValue(value, type); } + /** + * TODOC + */ reflectPropertyToAttribute(property, attribute, value) { this._propertyToAttribute(this, property, attribute, value); } + /** + * TODOC + */ serializeValueToAttribute(value, attribute, node) { this._valueToNodeAttribute(node || this, value, attribute); } @@ -185,6 +219,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN return Polymer.mixin(target, source); } + /** + * TODOC + */ chainObject(object, inherited) { if (object && inherited && object !== inherited) { object.__proto__ = inherited; @@ -193,6 +230,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN } /* **** Begin Template **** */ + /** * Calls `importNode` on the `content` of the `template` specified and * returns a document fragment containing the imported content. @@ -767,6 +805,10 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN } // logging + + /** + * TODOC + */ _logger(level, args) { // accept ['foo', 'bar'] and [['foo', 'bar']] if (Array.isArray(args) && args.length === 1) { @@ -780,18 +822,30 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN } } + /** + * TODOC + */ _log(...args) { this._logger('log', args); } + /** + * TODOC + */ _warn(...args) { this._logger('warn', args); } + /** + * TODOC + */ _error(...args) { this._logger('error', args) } + /** + * TODOC + */ _logf(...args) { return ['[%s::%s]', this.is, ...args]; } diff --git a/src/legacy/polymer-fn.html b/src/legacy/polymer-fn.html index a7053213..5b483a0e 100644 --- a/src/legacy/polymer-fn.html +++ b/src/legacy/polymer-fn.html @@ -20,7 +20,6 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * * TODOC * - * @namespace Polymer * @function Polymer * @param {Object} info Object containing Polymer metadata and functions * to become class methods. diff --git a/src/legacy/polymer.dom.html b/src/legacy/polymer.dom.html index 5a466419..4767bebb 100644 --- a/src/legacy/polymer.dom.html +++ b/src/legacy/polymer.dom.html @@ -24,7 +24,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * TODOC * * @function matchesSelector - * @memberof Polymer + * @memberof Polymer.dom * @param {Node} node Node to check selector against * @param {string} selector Selector to match * @return {boolean} True if node matched selector @@ -39,16 +39,28 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN this.node = node; } + /** + * TODOC + */ observeNodes(callback) { return new Polymer.FlattenedNodesObserver(this.node, callback); } + /** + * TODOC + */ unobserveNodes(observerHandle) { observerHandle.disconnect(); } + /** + * TODOC + */ notifyObserver() {} + /** + * TODOC + */ deepContains(node) { if (this.node.contains(node)) { return true; @@ -63,16 +75,25 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN return n === this.node; } + /** + * TODOC + */ getOwnerRoot() { return this.node.getRootNode(); } + /** + * TODOC + */ getDistributedNodes() { return (this.node.localName === 'slot') ? this.node.assignedNodes({flatten: true}) : []; } + /** + * TODOC + */ getDestinationInsertionPoints() { let ip$ = []; let n = this.node.assignedSlot; @@ -83,16 +104,25 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN return ip$; } + /** + * TODOC + */ importNode(externalNode, deep) { let doc = this.node instanceof Document ? this.node : this.node.ownerDocument; return doc.importNode(externalNode, deep); } + /** + * TODOC + */ getEffectiveChildNodes() { return Polymer.FlattenedNodesObserver.getFlattenedNodes(this.node); } + /** + * TODOC + */ queryDistributedElements(selector) { let c$ = this.getEffectiveChildNodes(); let list = []; @@ -105,6 +135,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN return list; } + /** + * TODOC + */ get activeElement() { let node = this.node; return node._activeElement !== undefined ? node._activeElement : node.activeElement; @@ -170,14 +203,23 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN this.event = event; } + /** + * TODOC + */ get rootTarget() { return this.event.composedPath()[0]; } + /** + * TODOC + */ get localTarget() { return this.event.target; } + /** + * TODOC + */ get path() { return this.event.composedPath(); } @@ -208,8 +250,18 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN Polymer.dom.matchesSelector = matchesSelector; + /** + * TODOC (not sure how to alias) + * + * @memberof Polymer.dom + */ Polymer.dom.flush = Polymer.flush; + /** + * TODOC (not sure how to alias) + * + * @memberof Polymer.dom + */ Polymer.dom.addDebouncer = Polymer.enqueueDebouncer; // expose BC settings. diff --git a/src/legacy/templatizer-behavior.html b/src/legacy/templatizer-behavior.html index d7e484fb..e2cac211 100644 --- a/src/legacy/templatizer-behavior.html +++ b/src/legacy/templatizer-behavior.html @@ -77,6 +77,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * @memberof Polymer */ let Templatizer = { + /** + * TODOC + */ templatize(template) { this._templatizerTemplate = template; this.ctor = Polymer.Templatize.templatize(template, this, { @@ -86,9 +89,15 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN notifyInstanceProp: this._notifyInstancePropV2 }); }, + /** + * TODOC + */ stamp(model) { return new this.ctor(model); }, + /** + * TODOC + */ modelForElement(el) { return Polymer.Templatize.modelForElement(this._templatizerTemplate, el); } diff --git a/src/utils/array-splice.html b/src/utils/array-splice.html index 77a366bb..d48af0b0 100644 --- a/src/utils/array-splice.html +++ b/src/utils/array-splice.html @@ -26,7 +26,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN const EDIT_ADD = 2; const EDIT_DELETE = 3; - let ArraySplice = { + const ArraySplice = { // Note: This function is *based* on the computation of the Levenshtein // "edit" distance. The one change is that "updates" are treated as two @@ -258,7 +258,18 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN }; + /** + * TODOC + * + * @namespace + * @memberof Polymer + */ Polymer.ArraySplice = { + /** + * TODOC + * + * @memberof Polymer.ArraySplice + */ calculateSplices(current, previous) { return ArraySplice.calculateSplices(current, previous); } diff --git a/src/utils/async.html b/src/utils/async.html index a605bb0c..ed9fdc7f 100644 --- a/src/utils/async.html +++ b/src/utils/async.html @@ -10,118 +10,172 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN \ No newline at end of file + +} + diff --git a/src/utils/boot.html b/src/utils/boot.html index 3cc306f3..a9658ed6 100644 --- a/src/utils/boot.html +++ b/src/utils/boot.html @@ -9,6 +9,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN --> diff --git a/src/utils/import-href.html b/src/utils/import-href.html index b814ddd8..6694008f 100644 --- a/src/utils/import-href.html +++ b/src/utils/import-href.html @@ -34,6 +34,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * In the `onload` callback, the `import` property of the `link` * element will contain the imported document contents. * + * @memberof Polymer * @method importHref * @param {string} href URL to document to load. * @param {Function=} onload Callback to notify when an import successfully diff --git a/src/utils/mixin.html b/src/utils/mixin.html index 0f6022fe..7ea91c9b 100644 --- a/src/utils/mixin.html +++ b/src/utils/mixin.html @@ -45,6 +45,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN * properties. To ensure only `ownProperties` are copied from source * to target and that accessor implementations are copied, use `extend`. * + * @memberof Polymer * @method mixin * @param {Object} target Target object to copy properties to. * @param {Object} source Source object to copy properties from. @@ -58,8 +59,12 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN }; /** - * Given a mixin producing function, only apply mixin if has not already been applied to base - * Also memoize mixin applications + * Given a mixin producing function, only apply mixin if has not already been + * applied to base. Also memoizes mixin applications. + * + * TODOC + * + * @memberof Polymer */ Polymer.dedupingMixin = function(mixin) { mixin = cachingMixin(mixin); diff --git a/src/utils/path.html b/src/utils/path.html index 0e7c31c8..30758a16 100644 --- a/src/utils/path.html +++ b/src/utils/path.html @@ -13,12 +13,28 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN diff --git a/src/utils/render-status.html b/src/utils/render-status.html index 3ed9091a..625d4ec7 100644 --- a/src/utils/render-status.html +++ b/src/utils/render-status.html @@ -54,8 +54,19 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN } } + /** + * TODOC + * + * @namespace + * @memberof Polymer + */ Polymer.RenderStatus = { + /** + * TODOC + * + * @memberof Polymer.RenderStatus + */ beforeNextRender: function(context, callback, args) { if (!scheduled) { schedule(); @@ -63,6 +74,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN beforeRenderQueue.push([context, callback, args]); }, + /** + * TODOC + * + * @memberof Polymer.RenderStatus + */ afterNextRender: function(context, callback, args) { if (!scheduled) { schedule(); diff --git a/src/utils/resolve-url.html b/src/utils/resolve-url.html index c3fb11d5..91b0babf 100644 --- a/src/utils/resolve-url.html +++ b/src/utils/resolve-url.html @@ -13,8 +13,14 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN (function() { - // path fixup for urls in cssText that's expected to - // come from a given ownerDocument + /** + * path fixup for urls in cssText that's expected to + * come from a given ownerDocument + * + * TODOC + * + * @memberof Polymer.ResolveUrl + */ function resolveCss(cssText, ownerDocument) { return cssText.replace(CSS_URL_RX, function(m, pre, url, post) { return pre + '\'' + @@ -23,8 +29,14 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN }); } - // url fixup for urls in an element's attributes made relative to - // ownerDoc's base url + /** + * url fixup for urls in an element's attributes made relative to + * ownerDoc's base url + * + * TODOC + * + * @memberof Polymer.ResolveUrl + */ function resolveAttrs(element, ownerDocument) { for (var name in URL_ATTRS) { var a$ = URL_ATTRS[name]; @@ -54,6 +66,12 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN var tempDoc; var tempDocBase; + + /** + * TODOC + * + * @memberof Polymer.ResolveUrl + */ function resolveUrl(url, baseUri) { if (!tempDoc) { tempDoc = document.implementation.createHTMLDocument('temp'); @@ -77,8 +95,14 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN var ABS_URL = /(^\/)|(^#)|(^[\w-\d]*:)/; var BINDING_RX = /\{\{|\[\[/; - // exports + /** + * TODOC + * + * @namespace + * @memberof Polymer + */ Polymer.ResolveUrl = { + // exports resolveCss: resolveCss, resolveAttrs: resolveAttrs, resolveUrl: resolveUrl diff --git a/src/utils/style-gather.html b/src/utils/style-gather.html index 6e6f4077..55e927db 100644 --- a/src/utils/style-gather.html +++ b/src/utils/style-gather.html @@ -12,8 +12,13 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN (function() { 'use strict'; +<<<<<<< HEAD let MODULE_STYLE_LINK_SELECTOR = 'link[rel=import][type~=css]'; let INCLUDE_ATTR = 'include'; +======= + const MODULE_STYLES_SELECTOR = 'style, link[rel=import][type~=css], template'; + const INCLUDE_ATTR = 'include'; +>>>>>>> Add @namespace annotations & "TODOC" todo's function importModule(moduleId) { if (!Polymer.DomModule) { @@ -22,12 +27,20 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN return Polymer.DomModule.import(moduleId); } - let StyleGather = { + /** + * TODOC + * + * @namespace + * @memberof Polymer + */ + const StyleGather = { /** + * Returns cssText of styles in a space-separated list of `dom-module`s. + * + * @memberof Polymer.StyleGather * @param {string} moduleIds - * @param {boolean=} warnIfNotFound - * @return {string} + * @return {string} Concatenated CSS content from specified `dom-module`s */ cssFromModules(moduleIds) { let modules = moduleIds.trim().split(' '); @@ -38,8 +51,18 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN return cssText; }, - // returns cssText of styles in a given module; also un-applies any - // styles that apply to the document. + /** + * Returns cssText of styles in a given `dom-module`. CSS in a `dom-module` + * can come either from `