Add @namespace annotations & "TODOC" todo's

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;

src/elements/dom-module.html

@@ -43,6 +43,9 @@
       }
     }
 
+    /**
+     * TODOC
+     */
     get assetpath() {
       // Don't override existing assetpath.
       if (!this.__assetpath) {

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];
       }

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.

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.

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);
       }

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);
     }

src/utils/async.html

@@ -10,118 +10,172 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 <link rel="import" href="boot.html">
 
 <script>
-(function () {
+{
-
   'use strict';
 
   /** @typedef {{run: function(function(), number=):number, cancel: function(number)}} */
   let AsyncInterface; // eslint-disable-line no-unused-vars
 
-  /**
+  // Microtask implemented using Mutation Observer
-   * A timer with the async interface.
+  let microtaskCurrHandle = 0;
-   * @implements {AsyncInterface}
+  let microtaskLastHandle = 0;
-   */
+  let microtaskCallbacks = [];
-  let timeOut = {
+  let microtaskNodeContent = 0;
-    run(fn, delay = 0) {
+  let microtaskNode = document.createTextNode('');
-      return window.setTimeout(fn, delay);
+  new window.MutationObserver(microtaskFlush).observe(microtaskNode, {characterData: true});
-    },
-    cancel(handle) {
-      window.clearTimeout(handle);
-    }
-  };
 
-  /**
+  function microtaskFlush() {
-   * @param {number} wait
+    const len = microtaskCallbacks.length;
-   * @return {!AsyncInterface}
+    for (let i = 0; i < len; i++) {
-   */
+      let cb = microtaskCallbacks[i];
-  timeOut.after = function (wait) {
+      if (cb) {
-    let after = {
+        try {
-      run(fn) {
+          cb();
-        return window.setTimeout(fn, wait);
+        } catch (e) {
-      },
+          setTimeout(() => { throw e });
-      cancel: timeOut.cancel
-    }
-    return after;
-  };
-
-  /**
-   * requestAnimationFrame with the async interface.
-   * @implements {AsyncInterface}
-   */
-  let animationFrame = {
-    run(fn) {
-      return window.requestAnimationFrame(fn);
-    },
-    cancel(handle) {
-      return window.cancelAnimationFrame(handle);
-    }
-  };
-
-  /**
-   * requestIdleCallback with the async interface.
-   * @implements {AsyncInterface}
-   */
-  let idlePeriod = window.requestIdleCallback ? {
-    run(fn) {
-      return window.requestIdleCallback(fn);
-    },
-    cancel(handle) {
-      return window.cancelIdleCallback(handle);
-    }
-  } : timeOut.after(16);
-
-  /**
-   * Micro task with the async interface.
-   * @implements {AsyncInterface}
-   */
-  class MicroTask {
-    constructor() {
-      this._currVal = 0;
-      this._lastVal = 0;
-      this._callbacks = [];
-      this._twiddleContent = 0;
-      this._twiddle = document.createTextNode('');
-      new MutationObserver(() => {
-        this._atEndOfMicrotask();
-      }).observe(this._twiddle, { characterData: true });
-    }
-    run(callback) {
-      this._twiddle.textContent = this._twiddleContent++;
-      this._callbacks.push(callback);
-      return this._currVal++;
-    }
-    cancel(handle) {
-      const idx = handle - this._lastVal;
-      if (idx >= 0) {
-        if (!this._callbacks[idx]) {
-          throw `invalid async handle: ${handle}`;
-        }
-        this._callbacks[idx] = null;
-      }
-    }
-    _atEndOfMicrotask() {
-      const len = this._callbacks.length;
-      for (let i = 0; i < len; i++) {
-        let cb = this._callbacks[i];
-        if (cb) {
-          try {
-            cb();
-          } catch (e) {
-            setTimeout(() => { throw e });
-          }
         }
       }
-      this._callbacks.splice(0, len);
-      this._lastVal += len;
     }
+    microtaskCallbacks.splice(0, len);
+    microtaskLastHandle += len;
   }
 
-  /** @type {Object<string, !AsyncInterface>} */
+  /**
+   * TODOC
+   *
+   * @namespace
+   * @memberof Polymer
+   */
   Polymer.Async = {
-    timeOut,
+
-    animationFrame,
+    /**
-    idlePeriod,
+     * A timer with the async interface.
-    microTask: new MicroTask()
+     *
+     * TODOC
+     *
+     * @namespace
+     * @memberof Polymer.Async
+     */
+    timeOut: {
+      /**
+       * TODOC
+       *
+       * @memberof Polymer.Async.timeOut
+       * @param {number} delay Time to wait before calling callbacks in ms
+       * @return {AsyncInterface} An async timeout interface
+       */
+      after(delay) {
+        return  {
+          run(fn) { return setTimeout(fn, delay) },
+          cancel: window.clearTimeout.bind(window)
+        }
+      },
+      /**
+       * TODOC
+       *
+       * @memberof Polymer.Async.timeOut
+       */
+      run: window.setTimeout.bind(window),
+      /**
+       * TODOC
+       *
+       * @memberof Polymer.Async.timeOut
+       */
+      cancel: window.clearTimeout.bind(window)
+    },
+
+    /**
+     * requestAnimationFrame with the async interface.
+     *
+     * TODOC
+     *
+     * @namespace
+     * @memberof Polymer.Async
+     */
+    animationFrame: {
+      /**
+       * TODOC
+       *
+       * @memberof Polymer.Async.timeOut
+       */
+      run: window.requestAnimationFrame.bind(window),
+      /**
+       * TODOC
+       *
+       * @memberof Polymer.Async.timeOut
+       */
+      cancel: window.cancelAnimationFrame.bind(window)
+    },
+
+    /**
+     * requestIdleCallback with the async interface.
+     *
+     * TODOC
+     *
+     * @namespace
+     * @memberof Polymer.Async
+     */
+    idlePeriod: {
+      /**
+       * TODOC
+       *
+       * @memberof Polymer.Async.timeOut
+       */
+      run(fn) {
+        return window.requestIdleCallback ?
+          window.requestIdleCallback(fn) :
+          window.setTimeout(fn, 16);
+      },
+      /**
+       * TODOC
+       *
+       * @memberof Polymer.Async.timeOut
+       */
+      cancel(timer) {
+        return window.cancelIdleCallback ?
+          window.cancelIdleCallback(timer) :
+          window.clearTimeout(timer);
+      }
+    },
+
+    /**
+     * Micro task with the async interface.
+     *
+     * TODOC
+     *
+     * @namespace
+     * @memberof Polymer.Async
+     */
+    microTask: {
+
+      /**
+       * TODOC
+       *
+       * @memberof Polymer.Async.timeOut
+       */
+      run(callback) {
+        microtaskNode.textContent = microtaskNodeContent++;
+        microtaskCallbacks.push(callback);
+        return microtaskCurrHandle++;
+      },
+
+      /**
+       * TODOC
+       *
+       * @memberof Polymer.Async.timeOut
+       */
+      cancel(handle) {
+        const idx = handle - microtaskLastHandle;
+        if (idx >= 0) {
+          if (!microtaskCallbacks[idx]) {
+            throw new Error('invalid async handle: ' + handle);
+          }
+          microtaskCallbacks[idx] = null;
+        }
+      }
+
+    }
   };
-})();
+
+}
 </script>

src/utils/boot.html

@@ -9,6 +9,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 -->
 <script>
 
+  /**
+   * @namespace Polymer
+   */
   window.Polymer = function(info) {
     return window.Polymer._polymerFn(info);
   }

src/utils/case-map.html

@@ -11,14 +11,31 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 <script>
 (function() {
 
+  /**
+   * TODOC
+   *
+   * @namespace
+   * @memberof Polymer
+   */
   const CaseMap = {
 
+    /**
+     * @private
+     */
     _caseMap: {},
+    /**
+     * @private
+     */
     _rx: {
       dashToCamel: /-[a-z]/g,
       camelToDash: /([A-Z])/g
     },
 
+    /**
+     * TODOC
+     *
+     * @memberof Polymer.CaseMap
+     */
     dashToCamelCase: function(dash) {
       return this._caseMap[dash] || (
         this._caseMap[dash] = dash.indexOf('-') < 0 ? dash : dash.replace(this._rx.dashToCamel,
@@ -29,6 +46,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       );
     },
 
+    /**
+     * TODOC
+     *
+     * @memberof Polymer.CaseMap
+     */
     camelToDashCase: function(camel) {
       return this._caseMap[camel] || (
         this._caseMap[camel] = camel.replace(this._rx.camelToDash, '-$1').toLowerCase()

src/utils/flush.html

@@ -13,6 +13,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
   let debouncerQueue = [];
 
+  /**
+   * TODOC
+   *
+   * @memberof Polymer
+   */
   Polymer.enqueueDebouncer = function(debouncer) {
     debouncerQueue.push(debouncer);
   }
@@ -31,6 +36,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     return didFlush;
   }
 
+  /**
+   * TODOC
+   *
+   * @memberof Polymer
+   */
   Polymer.flush = function() {
     let shadyDOM, debouncers;
     do {

src/utils/gestures.html

@@ -144,7 +144,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       // in the worst case, check that the x/y position of the click is within
       // the bounding box of the target of the event
       // Thanks IE 10 >:(
-      let t = gestures._findOriginalTarget(ev);
+      let t = Gestures._findOriginalTarget(ev);
       let bcr = t.getBoundingClientRect();
       // use page x/y to account for scrolling
       let x = ev.pageX, y = ev.pageY;
@@ -196,10 +196,21 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     stateObj.upfn = null;
   }
 
-  let gestures = {
+  /**
+   * TODOC
+   *
+   * @namespace
+   * @memberof Polymer
+   */
+  const Gestures = {
     gestures: {},
     recognizers: [],
 
+    /**
+     * TODOC
+     *
+     * @memberof Polymer.Gestures
+     */
     deepTargetFind: function(x, y) {
       let node = document.elementFromPoint(x, y);
       let next = node;
@@ -215,7 +226,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
       return node;
     },
-    // a cheaper check than ev.composedPath()[0];
+    /**
+     * a cheaper check than ev.composedPath()[0];
+     *
+     * @private
+     */
     _findOriginalTarget: function(ev) {
       // shadowdom
       if (ev.composedPath) {
@@ -224,6 +239,10 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       // shadydom
       return ev.target;
     },
+
+    /**
+     * @private
+     */
     _handleNative: function(ev) {
       let handled;
       let type = ev.type;
@@ -251,7 +270,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
           }
           if (!HAS_NATIVE_TA) {
             if (type === 'touchstart' || type === 'touchmove') {
-              gestures._handleTouchAction(ev);
+              Gestures._handleTouchAction(ev);
             }
           }
           if (type === 'touchend') {
@@ -267,7 +286,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       if (handled.skip) {
         return;
       }
-      let recognizers = gestures.recognizers;
+      let recognizers = Gestures.recognizers;
       // reset recognizer state
       for (let i = 0, r; i < recognizers.length; i++) {
         r = recognizers[i];
@@ -287,6 +306,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
     },
 
+    /**
+     * @private
+     */
     _handleTouchAction: function(ev) {
       let t = ev.changedTouches[0];
       let type = ev.type;
@@ -315,11 +337,16 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
         if (prevent) {
           ev.preventDefault();
         } else {
-          gestures.prevent('track');
+          Gestures.prevent('track');
         }
       }
     },
 
+    /**
+     * TODOC
+     *
+     * @memberof Polymer.Gestures
+     */
     addListener: function(node, evType, handler) {
       if (this.gestures[evType]) {
         this._add(node, evType, handler);
@@ -327,6 +354,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
     },
 
+    /**
+     * TODOC
+     *
+     * @memberof Polymer.Gestures
+     */
     removeListener: function(node, evType, handler) {
       if (this.gestures[evType]) {
         this._remove(node, evType, handler);
@@ -334,7 +366,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
     },
 
-    // automate the event listeners for the native events
+    /**
+     * automate the event listeners for the native events
+     *
+     * @private
+     */
     _add: function(node, evType, handler) {
       let recognizer = this.gestures[evType];
       let deps = recognizer.deps;
@@ -365,7 +401,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
     },
 
-    // automate event listener removal for native events
+    /**
+     * automate event listener removal for native events
+     *
+     * @private
+     */
     _remove: function(node, evType, handler) {
       let recognizer = this.gestures[evType];
       let deps = recognizer.deps;
@@ -387,6 +427,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       node.removeEventListener(evType, handler);
     },
 
+    /**
+     * TODOC
+     *
+     * @memberof Polymer.Gestures
+     */
     register: function(recog) {
       this.recognizers.push(recog);
       for (let i = 0; i < recog.emits.length; i++) {
@@ -394,6 +439,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
     },
 
+    /**
+     * @private
+     */
     _findRecognizerByEvent: function(evName) {
       for (let i = 0, r; i < this.recognizers.length; i++) {
         r = this.recognizers[i];
@@ -407,8 +455,14 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       return null;
     },
 
-    // set scrolling direction on node to check later on first move
+    /**
-    // must call this before adding event listeners!
+     * set scrolling direction on node to check later on first move
+     * must call this before adding event listeners!
+     *
+     * TODOC
+     *
+     * @memberof Polymer.Gestures
+     */
     setTouchAction: function(node, value) {
       if (HAS_NATIVE_TA) {
         node.style.touchAction = value;
@@ -416,6 +470,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       node[TOUCH_ACTION] = value;
     },
 
+    /**
+     * @private
+     */
     _fire: function(target, type, detail) {
       let ev = new Event(type, { bubbles: true, cancelable: true, composed: true });
       ev.detail = detail;
@@ -429,6 +486,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
     },
 
+    /**
+     * TODOC
+     *
+     * @memberof Polymer.Gestures
+     */
     prevent: function(evName) {
       let recognizer = this._findRecognizerByEvent(evName);
       if (recognizer.info) {
@@ -441,9 +503,10 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
      *
      * Touch inputs create synthesized mouse inputs anywhere from 0 to 2000ms after the touch.
      * This method should only be called during testing with simulated touch inputs.
-     * Calling this method in production may cause duplicate taps or other gestures.
+     * Calling this method in production may cause duplicate taps or other Gestures.
      *
      * @method resetMouseCanceller
+     * @memberof Polymer.Gestures
      */
     resetMouseCanceller: function() {
       if (POINTERSTATE.mouse.mouseIgnoreJob) {
@@ -452,7 +515,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     }
   };
 
-  gestures.register({
+  Gestures.register({
     name: 'downup',
     deps: ['mousedown', 'touchstart', 'touchend'],
     flow: {
@@ -474,7 +537,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       if (!hasLeftMouseButton(e)) {
         return;
       }
-      let t = gestures._findOriginalTarget(e);
+      let t = Gestures._findOriginalTarget(e);
       let self = this;
       let movefn = function movefn(e) {
         if (!hasLeftMouseButton(e)) {
@@ -492,25 +555,25 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       this._fire('down', t, e);
     },
     touchstart: function(e) {
-      this._fire('down', gestures._findOriginalTarget(e), e.changedTouches[0], e);
+      this._fire('down', Gestures._findOriginalTarget(e), e.changedTouches[0], e);
     },
     touchend: function(e) {
-      this._fire('up', gestures._findOriginalTarget(e), e.changedTouches[0], e);
+      this._fire('up', Gestures._findOriginalTarget(e), e.changedTouches[0], e);
     },
     _fire: function(type, target, event, preventer) {
-      gestures._fire(target, type, {
+      Gestures._fire(target, type, {
         x: event.clientX,
         y: event.clientY,
         sourceEvent: event,
         preventer: preventer,
         prevent: function(e) {
-          return gestures.prevent(e);
+          return Gestures.prevent(e);
         }
       });
     }
   });
 
-  gestures.register({
+  Gestures.register({
     name: 'track',
     touchAction: 'none',
     deps: ['mousedown', 'touchstart', 'touchmove', 'touchend'],
@@ -563,7 +626,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       if (!hasLeftMouseButton(e)) {
         return;
       }
-      let t = gestures._findOriginalTarget(e);
+      let t = Gestures._findOriginalTarget(e);
       let self = this;
       let movefn = function movefn(e) {
         let x = e.clientX, y = e.clientY;
@@ -572,7 +635,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
           self.info.state = self.info.started ? (e.type === 'mouseup' ? 'end' : 'track') : 'start';
           if (self.info.state === 'start') {
             // if and only if tracking, always prevent tap
-            gestures.prevent('tap');
+            Gestures.prevent('tap');
           }
           self.info.addMove({x: x, y: y});
           if (!hasLeftMouseButton(e)) {
@@ -605,13 +668,13 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     },
 
     touchmove: function(e) {
-      let t = gestures._findOriginalTarget(e);
+      let t = Gestures._findOriginalTarget(e);
       let ct = e.changedTouches[0];
       let x = ct.clientX, y = ct.clientY;
       if (this.hasMovedEnough(x, y)) {
         if (this.info.state === 'start') {
           // if and only if tracking, always prevent tap
-          gestures.prevent('tap');
+          Gestures.prevent('tap');
         }
         this.info.addMove({x: x, y: y});
         this._fire(t, ct);
@@ -621,7 +684,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     },
 
     touchend: function(e) {
-      let t = gestures._findOriginalTarget(e);
+      let t = Gestures._findOriginalTarget(e);
       let ct = e.changedTouches[0];
       // only trackend if track was started and not aborted
       if (this.info.started) {
@@ -642,7 +705,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
         ddx = lastmove.x - secondlast.x;
         ddy = lastmove.y - secondlast.y;
       }
-      return gestures._fire(target, 'track', {
+      return Gestures._fire(target, 'track', {
         state: this.info.state,
         x: touch.clientX,
         y: touch.clientY,
@@ -652,14 +715,14 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
         ddy: ddy,
         sourceEvent: touch,
         hover: function() {
-          return gestures.deepTargetFind(touch.clientX, touch.clientY);
+          return Gestures.deepTargetFind(touch.clientX, touch.clientY);
         }
       });
     }
 
   });
 
-  gestures.register({
+  Gestures.register({
     name: 'tap',
     deps: ['mousedown', 'click', 'touchstart', 'touchend'],
     flow: {
@@ -703,12 +766,12 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     forward: function(e, preventer) {
       let dx = Math.abs(e.clientX - this.info.x);
       let dy = Math.abs(e.clientY - this.info.y);
-      let t = gestures._findOriginalTarget(e);
+      let t = Gestures._findOriginalTarget(e);
       // dx,dy can be NaN if `click` has been simulated and there was no `down` for `start`
       if (isNaN(dx) || isNaN(dy) || (dx <= TAP_DISTANCE && dy <= TAP_DISTANCE) || isSyntheticClick(e)) {
         // prevent taps from being generated if an event has canceled them
         if (!this.info.prevent) {
-          gestures._fire(t, 'tap', {
+          Gestures._fire(t, 'tap', {
             x: e.clientX,
             y: e.clientY,
             sourceEvent: e,
@@ -720,15 +783,15 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
   });
 
   /** @deprecated */
-  gestures.findOriginalTarget = gestures._findOriginalTarget;
+  Gestures.findOriginalTarget = Gestures._findOriginalTarget;
 
   /** @deprecated */
-  gestures.add = gestures.addListener;
+  Gestures.add = Gestures.addListener;
 
   /** @deprecated */
-  gestures.remove = gestures.removeListener;
+  Gestures.remove = Gestures.removeListener;
 
-  Polymer.Gestures = gestures;
+  Polymer.Gestures = Gestures;
 
 })();
 </script>

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

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
+   * Given a mixin producing function, only apply mixin if has not already been
-   * Also memoize mixin applications
+   * applied to base.  Also memoizes mixin applications.
+   *
+   * TODOC
+   *
+   * @memberof Polymer
    */
   Polymer.dedupingMixin = function(mixin) {
     mixin = cachingMixin(mixin);

src/utils/path.html

@@ -13,12 +13,28 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 <script>
 (function() {
 
+  /**
+   * TODOC
+   *
+   * @namespace
+   * @memberof Polymer
+   */
   const Path = {
 
+    /**
+     * TODOC
+     *
+     * @memberof Polymer.Path
+     */
     isPath: function(path) {
       return path.indexOf('.') >= 0;
     },
 
+    /**
+     * TODOC
+     *
+     * @memberof Polymer.Path
+     */
     root: function(path) {
       var dotIndex = path.indexOf('.');
       if (dotIndex === -1) {
@@ -27,20 +43,37 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       return path.slice(0, dotIndex);
     },
 
-    // Given `base` is `foo.bar`, `foo` is an ancestor, `foo.bar` is not
+    /**
+     * Given `base` is `foo.bar`, `foo` is an ancestor, `foo.bar` is not
+     *
+     * TODOC
+     *
+     * @memberof Polymer.Path
+     */
     isAncestor: function(base, path) {
       //     base.startsWith(path + '.');
       return base.indexOf(path + '.') === 0;
     },
 
-    // Given `base` is `foo.bar`, `foo.bar.baz` is an descendant
+    /**
+     * Given `base` is `foo.bar`, `foo.bar.baz` is an descendant
+     *
+     * TODOC
+     *
+     * @memberof Polymer.Path
+     */
     isDescendant: function(base, path) {
       //     path.startsWith(base + '.');
       return path.indexOf(base + '.') === 0;
     },
 
-    // can be read as:  from  to       path
+    /**
+     * TODOC
+     *
+     * @memberof Polymer.Path
+     */
     translate: function(base, newBase, path) {
+    // can be read as:  from  to       path
       // Defense?
       return newBase + path.slice(base.length);
     },
@@ -53,6 +86,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
     /**
      * Converts array-based paths to flattened path
+     *
+     * @memberof Polymer.Path
      * @param {string | !Array<string|number>} path
      * @return {string}
      */
@@ -73,6 +108,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
     /**
      * Split a path into an array
+     *
+     * @memberof Polymer.Path
      * @param {string | !Array<string|number>} path
      * @return {!Array<string>}
      */
@@ -84,6 +121,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     },
 
     /**
+     * TODOC
+     *
+     * @memberof Polymer.Path
      * @param {Object} root
      * @param {string | !Array<string|number>} path
      * @param {Object=} info
@@ -107,6 +147,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     },
 
     /**
+     * TODOC
+     *
+     * @memberof Polymer.Path
      * @param {Object} root
      * @param {string | !Array<string|number>} path
      * @param {*} value

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();

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

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} Concatenated CSS content from specified `dom-module`s
-     * @return {string}
      */
     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 `<style>`s within the first `<template>`, or else
+     * from one or more `<link rel="import" type="css">` links outside the
+     * template.
+     *
+     * Any `<styles>` processed are removed from their original location.
+     *
+     * @memberof Polymer.StyleGather
+     * @param {string} moduleId dom-module id to gather styles from
+     * @return {string} Concatenated CSS content from specified `dom-module`
+     */
     cssFromModule(moduleId) {
       let m = importModule(moduleId);
       if (m && m._cssText === undefined) {
@@ -59,7 +82,15 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       return m && m._cssText || '';
     },
 
-    // support lots of ways to discover css...
+    /**
+     * Returns cssText of `<styles>` within a given template.
+     *
+     * Any `<styles>` processed are removed from their original location.
+     *
+     * @memberof Polymer.StyleGather
+     * @param {HTMLTemplateElement} template Template to gather styles from
+     * @return {string} Concatenated CSS content from specified template
+     */
     cssFromTemplate(template) {
       let cssText = '';
       // if element is a template, get content from its .content
@@ -78,6 +109,11 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
       return cssText;
     },
+
+    /**
+     * Description
+     *
+     */
     cssFromModuleImports(moduleId) {
       let cssText = '';
       let m = importModule(moduleId);

src/utils/templatize.html

@@ -59,6 +59,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
           this._flushProperties();
         }
       }
+      /**
+       * @private
+       */
       _configureProperties(props) {
         let options = this.__templatizeOptions;
         if (props) {
@@ -72,11 +75,17 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
           this._setPendingProperty(hprop, this.__dataHost['_host_' + hprop]);
         }
       }
+      /**
+       * TODOC
+       */
       forwardHostProp(prop, value) {
         if (this._setPendingPropertyOrPath(prop, value, false, true)) {
           this.__dataHost._enqueueClient(this);
         }
       }
+      /**
+       * @override
+       */
       _addEventListenerToNode(node, eventName, handler) {
         if (this._methodHost && this.__templatizeOptions.parentModel) {
           // If this instance should be considered a parent model, decorate
@@ -94,6 +103,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
           }
         }
       }
+      /**
+       * @protected
+       */
       _showHideChildren(hide) {
         let c = this.children;
         for (let i=0; i<c.length; i++) {
@@ -254,8 +266,19 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
     }
 
-    let Templatize = {
+    /**
+     * TODOC
+     *
+     * @namespace
+     * @memberof Polymer
+     */
+    const Templatize = {
 
+      /**
+       * TODOC
+       *
+       * @memberof Polymer.Templatize
+       */
       templatize(template, owner, options) {
         if (template.__templatizeOwner) {
           throw new Error('A <template> can only be templatized once');
@@ -294,6 +317,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
        *     model.set('item.checked', true);
        *   }
        *
+       * @memberof Polymer.Templatize
        * @method modelForElement
        * @param {HTMLElement} el Element for which to return a template model.
        * @return {TemplateInstanceBase} Model representing the binding scope for