Update various Polymer annotations to constrain generated types.

Author: aomarks

lib/elements/array-selector.html

@@ -211,7 +211,7 @@
 
       /**
        * Clears the selection state.
-       *
+       * @returns {void}
        */
       clearSelection() {
         // Unbind previous selection

lib/elements/dom-bind.html

@@ -61,16 +61,19 @@
         this.__children = null;
       }
 
-      // assumes only one observed attribute
+      /** @returns {void} */
       attributeChangedCallback() {
+        // assumes only one observed attribute
         this.mutableData = true;
       }
 
+      /** @returns {void} */
       connectedCallback() {
         this.style.display = 'none';
         this.render();
       }
 
+      /** @returns {void} */
       disconnectedCallback() {
         this.__removeChildren();
       }

lib/elements/dom-module.html

@@ -74,6 +74,10 @@
       return null;
     }
 
+    /**
+     * @param {string} name
+     * @returns {void}
+     */
     attributeChangedCallback(name, old, value) {
       if (old !== value) {
         this.register();

lib/legacy/legacy-element-mixin.html

@@ -129,6 +129,7 @@
        * @param {string} name Name of attribute.
        * @param {?string} old Old value of attribute.
        * @param {?string} value Current value of attribute.
+       * @returns {void}
        * @override
        */
       attributeChangedCallback(name, old, value) {
@@ -484,7 +485,7 @@
        * any `<content>` elements are replaced with the list of nodes distributed
        * to the `<content>`, the result of its `getDistributedNodes` method.
        * @this {Element}
-       * @return {Array<Node>} List of effective child nodes.
+       * @return {!Array<!Node>} List of effective child nodes.
        */
       getEffectiveChildNodes() {
         const domApi = /** @type {Polymer.DomApi} */(Polymer.dom(this));
@@ -497,7 +498,7 @@
        * children that are insertion points.
        * @param {string} selector Selector to run.
        * @this {Element}
-       * @return {Array<Node>} List of distributed elements that match selector.
+       * @return {!Array<!Node>} List of distributed elements that match selector.
        */
       queryDistributedElements(selector) {
         const domApi = /** @type {Polymer.DomApi} */(Polymer.dom(this));
@@ -510,7 +511,7 @@
        * any `<content>` elements are replaced with the list of elements
        * distributed to the `<content>`.
        *
-       * @return {Array<Node>} List of effective children.
+       * @return {!Array<!Node>} List of effective children.
        */
       getEffectiveChildren() {
         let list = this.getEffectiveChildNodes();
@@ -554,7 +555,7 @@
        * match `selector`. These can be dom child nodes or elements distributed
        * to children that are insertion points.
        * @param {string} selector Selector to run.
-       * @return {Array<Node>} List of effective child nodes that match selector.
+       * @return {!Array<!Node>} List of effective child nodes that match selector.
        */
       queryAllEffectiveChildren(selector) {
         return this.queryDistributedElements(selector);
@@ -568,7 +569,7 @@
        *
        * @param {string=} slctr CSS selector to choose the desired
        *   `<slot>`.  Defaults to `content`.
-       * @return {Array<Node>} List of distributed nodes for the `<slot>`.
+       * @return {!Array<!Node>} List of distributed nodes for the `<slot>`.
        */
       getContentChildNodes(slctr) {
         let content = this.root.querySelector(slctr || 'slot');
@@ -586,12 +587,12 @@
        *
        * @param {string=} slctr CSS selector to choose the desired
        *   `<content>`.  Defaults to `content`.
-       * @return {Array<HTMLElement>} List of distributed nodes for the
+       * @return {!Array<!HTMLElement>} List of distributed nodes for the
        *   `<slot>`.
        * @suppress {invalidCasts}
        */
       getContentChildren(slctr) {
-        let children = /** @type {Array<HTMLElement>} */(this.getContentChildNodes(slctr).filter(function(n) {
+        let children = /** @type {!Array<!HTMLElement>} */(this.getContentChildNodes(slctr).filter(function(n) {
           return (n.nodeType === Node.ELEMENT_NODE);
         }));
         return children;
@@ -649,7 +650,7 @@
        *     }
        *
        * @param {string} jobName String to identify the debounce job.
-       * @param {function()} callback Function that is called (with `this`
+       * @param {function():void} callback Function that is called (with `this`
        *   context) when the wait time elapses.
        * @param {number} wait Optional wait time in milliseconds (ms) after the
        *   last signal that must elapse before invoking `callback`
@@ -713,7 +714,7 @@
        * By default (if no waitTime is specified), async callbacks are run at
        * microtask timing, which will occur before paint.
        *
-       * @param {Function} callback The callback function to run, bound to `this`.
+       * @param {!Function} callback The callback function to run, bound to `this`.
        * @param {number=} waitTime Time to wait before calling the
        *   `callback`.  If unspecified or 0, the callback will be run at microtask
        *   timing (before paint).
@@ -769,13 +770,13 @@
        * element will contain the imported document contents.
        *
        * @param {string} href URL to document to load.
-       * @param {Function} onload Callback to notify when an import successfully
+       * @param {!Function=} onload Callback to notify when an import successfully
        *   loaded.
-       * @param {Function} onerror Callback to notify when an import
+       * @param {!Function=} onerror Callback to notify when an import
        *   unsuccessfully loaded.
-       * @param {boolean} optAsync True if the import should be loaded `async`.
+       * @param {boolean=} optAsync True if the import should be loaded `async`.
        *   Defaults to `false`.
-       * @return {HTMLLinkElement} The link element for the URL to be loaded.
+       * @return {!HTMLLinkElement} The link element for the URL to be loaded.
        */
       importHref(href, onload, onerror, optAsync) { // eslint-disable-line no-unused-vars
         let loadFn = onload ? onload.bind(this) : null;
@@ -788,7 +789,7 @@
        * prefixed.
        *
        * @param {string} selector Selector to test.
-       * @param {Element=} node Element to test the selector against.
+       * @param {!Element=} node Element to test the selector against.
        * @return {boolean} Whether the element matches the selector.
        */
       elementMatches(selector, node) {

lib/legacy/polymer-fn.html

@@ -29,7 +29,7 @@
      * @function Polymer
      * @param {!PolymerInit} info Object containing Polymer metadata and functions
      *   to become class methods.
-     * @return {!HTMLElement} Generated class
+     * @return {function(new: HTMLElement)} Generated class
      * @suppress {duplicate, invalidCasts, checkTypes}
      */
     window.Polymer._polymerFn = function(info) {

lib/legacy/polymer.dom.html

@@ -157,8 +157,8 @@
     }
 
     /**
-     * @return {Array} Returns a flattened list of all child nodes and nodes assigned
-     * to child slots.
+     * @return {!Array<!Node>} Returns a flattened list of all child nodes and
+     * nodes assigned to child slots.
      */
     getEffectiveChildNodes() {
       return Polymer.FlattenedNodesObserver.getFlattenedNodes(this.node);

lib/utils/async.html

@@ -68,7 +68,7 @@
        *
        * @memberof Polymer.Async.timeOut
        * @param {number} delay Time to wait before calling callbacks in ms
-       * @return {AsyncInterface} An async timeout interface
+       * @return {!AsyncInterface} An async timeout interface
        */
       after(delay) {
         return  {
@@ -81,7 +81,7 @@
        *
        * @function
        * @memberof Polymer.Async.timeOut
-       * @param {Function} fn Callback to run
+       * @param {!Function} fn Callback to run
        * @return {number} Handle used for canceling task
        */
       run: window.setTimeout.bind(window),
@@ -109,7 +109,7 @@
        *
        * @function
        * @memberof Polymer.Async.animationFrame
-       * @param {Function} fn Callback to run
+       * @param {!Function} fn Callback to run
        * @return {number} Handle used for canceling task
        */
       run: window.requestAnimationFrame.bind(window),
@@ -137,7 +137,7 @@
        * Enqueues a function called at `requestIdleCallback` timing.
        *
        * @memberof Polymer.Async.idlePeriod
-       * @param {function(IdleDeadline)} fn Callback to run
+       * @param {function(!IdleDeadline):void} fn Callback to run
        * @return {number} Handle used for canceling task
        */
       run(fn) {
@@ -179,7 +179,7 @@
        * Enqueues a function called at microtask timing.
        *
        * @memberof Polymer.Async.microTask
-       * @param {Function} callback Callback to run
+       * @param {!Function=} callback Callback to run
        * @return {number} Handle used for canceling task
        */
       run(callback) {

lib/utils/flush.html

@@ -18,7 +18,7 @@
    * Adds a `Polymer.Debouncer` to a list of globally flushable tasks.
    *
    * @memberof Polymer
-   * @param {Polymer.Debouncer} debouncer Debouncer to enqueue
+   * @param {!Polymer.Debouncer} debouncer Debouncer to enqueue
    * @return {void}
    */
   Polymer.enqueueDebouncer = function(debouncer) {

lib/utils/gestures.html

@@ -427,9 +427,9 @@
      * Adds an event listener to a node for the given gesture type.
      *
      * @memberof Polymer.Gestures
-     * @param {Node} node Node to add listener on
+     * @param {!Node} node Node to add listener on
      * @param {string} evType Gesture type: `down`, `up`, `track`, or `tap`
-     * @param {Function} handler Event listener function to call
+     * @param {!Function} handler Event listener function to call
      * @return {boolean} Returns true if a gesture event listener was added.
      * @this {Gestures}
      */
@@ -445,9 +445,9 @@
      * Removes an event listener from a node for the given gesture type.
      *
      * @memberof Polymer.Gestures
-     * @param {Node} node Node to remove listener from
+     * @param {!Node} node Node to remove listener from
      * @param {string} evType Gesture type: `down`, `up`, `track`, or `tap`
-     * @param {Function} handler Event listener function previously passed to
+     * @param {!Function} handler Event listener function previously passed to
      *  `addListener`.
      * @return {boolean} Returns true if a gesture event listener was removed.
      * @this {Gestures}
@@ -464,7 +464,7 @@
      * automate the event listeners for the native events
      *
      * @private
-     * @param {HTMLElement} node Node on which to add the event.
+     * @param {!HTMLElement} node Node on which to add the event.
      * @param {string} evType Event type to add.
      * @param {function(Event?)} handler Event handler function.
      * @return {void}
@@ -504,7 +504,7 @@
      * automate event listener removal for native events
      *
      * @private
-     * @param {HTMLElement} node Node on which to remove the event.
+     * @param {!HTMLElement} node Node on which to remove the event.
      * @param {string} evType Event type to remove.
      * @param {function(Event?)} handler Event handler function.
      * @return {void}
@@ -536,7 +536,7 @@
      * gesture event types.
      *
      * @memberof Polymer.Gestures
-     * @param {GestureRecognizer} recog Gesture recognizer descriptor
+     * @param {!GestureRecognizer} recog Gesture recognizer descriptor
      * @return {void}
      * @this {Gestures}
      */
@@ -573,7 +573,7 @@
      * adding event listeners.
      *
      * @memberof Polymer.Gestures
-     * @param {Element} node Node to set touch action setting on
+     * @param {!Element} node Node to set touch action setting on
      * @param {string} value Touch action value
      * @return {void}
      */
@@ -588,9 +588,9 @@
      * Dispatches an event on the `target` element of `type` with the given
      * `detail`.
      * @private
-     * @param {EventTarget} target The element on which to fire an event.
+     * @param {!EventTarget} target The element on which to fire an event.
      * @param {string} type The type of event to fire.
-     * @param {Object=} detail The detail object to populate on the event.
+     * @param {!Object=} detail The detail object to populate on the event.
      * @return {void}
      */
     _fire: function(target, type, detail) {

lib/utils/import-href.html

@@ -36,13 +36,13 @@
    *
    * @memberof Polymer
    * @param {string} href URL to document to load.
-   * @param {Function=} onload Callback to notify when an import successfully
+   * @param {!Function=} onload Callback to notify when an import successfully
    *   loaded.
-   * @param {Function=} onerror Callback to notify when an import
+   * @param {!Function=} onerror Callback to notify when an import
    *   unsuccessfully loaded.
    * @param {boolean=} optAsync True if the import should be loaded `async`.
    *   Defaults to `false`.
-   * @return {HTMLLinkElement} The link element for the URL to be loaded.
+   * @return {!HTMLLinkElement} The link element for the URL to be loaded.
    */
   Polymer.importHref = function(href, onload, onerror, optAsync) {
     let link = /** @type {HTMLLinkElement} */

lib/utils/settings.html

@@ -16,11 +16,6 @@
 (function() {
   'use strict';
 
-  /**
-   * Legacy settings.
-   * @namespace
-   * @memberof Polymer
-   */
   const settings = Polymer.Settings || {};
   settings.useShadow = !(window.ShadyDOM);
   settings.useNativeCSSProperties =
@@ -32,6 +27,7 @@
    * Sets the global, legacy settings.
    *
    * @deprecated
+   * @namespace
    * @memberof Polymer
    */
   Polymer.Settings = settings;

types/lib/elements/array-selector.d.ts

@@ -68,7 +68,7 @@ declare namespace Polymer {
     /**
      * Clears the selection state.
      */
-    clearSelection(): any;
+    clearSelection(): void;
 
     /**
      * Returns whether the item is currently selected.

types/lib/elements/dom-bind.d.ts

@@ -30,13 +30,9 @@ declare namespace Polymer {
     Polymer.OptionalMutableData(
     Polymer.GestureEventListeners(
     Polymer.Element))) {
-
-    /**
-     * assumes only one observed attribute
-     */
-    attributeChangedCallback(): any;
-    connectedCallback(): any;
-    disconnectedCallback(): any;
+    attributeChangedCallback(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
 
     /**
      * Forces the element to render its content. This is typically only

types/lib/elements/dom-module.d.ts

@@ -33,7 +33,7 @@ declare namespace Polymer {
    *     let img = customElements.get('dom-module').import('foo', 'img');
    */
   class DomModule extends HTMLElement {
-    attributeChangedCallback(name: any, old: any, value: any): any;
+    attributeChangedCallback(name: string, old: any, value: any): void;
 
     /**
      * Registers the dom-module at a given id. This method should only be called