Tighten Closure type annotations. (#4997)

externs/closure-types.js

@@ -1145,7 +1145,7 @@ Polymer_LegacyElementMixin.prototype.flushDebouncer = function(jobName){};
 */
 Polymer_LegacyElementMixin.prototype.cancelDebouncer = function(jobName){};
 /**
-* @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).
@@ -1167,18 +1167,18 @@ Polymer_LegacyElementMixin.prototype.cancelAsync = function(handle){};
 Polymer_LegacyElementMixin.prototype.create = function(tag, props){};
 /**
 * @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}
 */
 Polymer_LegacyElementMixin.prototype.importHref = function(href, onload, onerror, optAsync){};
 /**
 * @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}
 */
 Polymer_LegacyElementMixin.prototype.elementMatches = function(selector, node){};
@@ -1320,4 +1320,4 @@ Polymer_ArraySelectorMixin.prototype.select = function(item){};
 * @param {number} idx Index from `items` array to select
 * @return {void}
 */
-Polymer_ArraySelectorMixin.prototype.selectIndex = function(idx){};
+Polymer_ArraySelectorMixin.prototype.selectIndex = function(idx){};

lib/elements/array-selector.html

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

lib/elements/dom-bind.html

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

lib/elements/dom-module.html

@@ -74,6 +74,12 @@
       return null;
     }
 
+    /**
+     * @param {string} name Name of attribute.
+     * @param {?string} old Old value of attribute.
+     * @param {?string} value Current value of attribute.
+     * @return {void}
+     */
     attributeChangedCallback(name, old, value) {
       if (old !== value) {
         this.register();

lib/legacy/legacy-element-mixin.html

@@ -134,6 +134,7 @@
        * @param {string} name Name of attribute.
        * @param {?string} old Old value of attribute.
        * @param {?string} value Current value of attribute.
+       * @return {void}
        * @override
        */
       attributeChangedCallback(name, old, value) {
@@ -487,7 +488,7 @@
        * childNodes list is the same as the element's childNodes except that
        * any `<content>` elements are replaced with the list of nodes distributed
        * to the `<content>`, the result of its `getDistributedNodes` method.
-       * @return {Array<Node>} List of effective child nodes.
+       * @return {!Array<!Node>} List of effective child nodes.
        * @suppress {invalidCasts} LegacyElementMixin must be applied to an HTMLElement
        */
       getEffectiveChildNodes() {
@@ -501,7 +502,7 @@
        * `selector`. These can be dom children or elements distributed to
        * children that are insertion points.
        * @param {string} selector Selector to run.
-       * @return {Array<Node>} List of distributed elements that match selector.
+       * @return {!Array<!Node>} List of distributed elements that match selector.
        * @suppress {invalidCasts} LegacyElementMixin must be applied to an HTMLElement
        */
       queryDistributedElements(selector) {
@@ -516,11 +517,11 @@
        * 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();
-        return list.filter(function(/** @type {Node} */ n) {
+        return list.filter(function(/** @type {!Node} */ n) {
           return (n.nodeType === Node.ELEMENT_NODE);
         });
       }
@@ -560,7 +561,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);
@@ -574,7 +575,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');
@@ -592,12 +593,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;
@@ -657,7 +658,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`
@@ -721,7 +722,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).
@@ -777,13 +778,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;
@@ -796,7 +797,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

@@ -17,7 +17,7 @@
 
   const p = Element.prototype;
   /**
-   * @const {function(this:Element, string): boolean}
+   * @const {function(this:Node, string): boolean}
    */
   const normalizedMatchesSelector = p.matches || p.matchesSelector ||
     p.mozMatchesSelector || p.msMatchesSelector ||
@@ -28,7 +28,7 @@
    *
    * @function matchesSelector
    * @memberof Polymer.dom
-   * @param {!Element} node Node to check selector against
+   * @param {!Node} node Node to check selector against
    * @param {string} selector Selector to match
    * @return {boolean} True if node matched selector
    */
@@ -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

@@ -80,7 +80,7 @@
        *
        * @function
        * @memberof Polymer.Async.timeOut
-       * @param {Function} fn Callback to run
+       * @param {!Function} fn Callback to run
        * @param {number=} delay Delay in milliseconds
        * @return {number} Handle used for canceling task
        */
@@ -145,7 +145,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) {
@@ -187,7 +187,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/flattened-nodes-observer.html

@@ -102,17 +102,26 @@
      * or removals from the target's list of flattened nodes.
     */
     constructor(target, callback) {
-      /** @type {MutationObserver} */
+      /**
+       * @type {MutationObserver}
+       * @private
+       */
       this._shadyChildrenObserver = null;
-      /** @type {MutationObserver} */
+      /**
+       * @type {MutationObserver}
+       * @private
+       */
       this._nativeChildrenObserver = null;
       this._connected = false;
       this._target = target;
       this.callback = callback;
       this._effectiveNodes = [];
       this._observer = null;
       this._scheduled = false;
-      /** @type {function()} */
+      /**
+       * @type {function()}
+       * @private
+       */
       this._boundSchedule = () => {
         this._schedule();
       };

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) {