Tighten more types for TypeScript and Closure (#4998)

externs/polymer-internal-shared-types.js

@@ -161,5 +161,5 @@ let TemplatizeOptions;
 function AsyncInterface(){}
 /** @type {function(!Function, number=): number} */
 AsyncInterface.prototype.run;
-/** @type {function(number)} */
-AsyncInterface.prototype.cancel;
+/** @type {function(number): void} */
+AsyncInterface.prototype.cancel;

gulpfile.js

@@ -113,7 +113,7 @@ class AddClosureTypeImport extends Transform {
 
 gulp.task('clean', () => del([DIST_DIR, 'closure.log']));
 
-gulp.task('closure', ['clean'], () => {
+gulp.task('closure', ['generate-externs'], () => {
 
   let entry, splitRx, joinRx, addClosureTypes;
 

lib/elements/dom-if.html

@@ -117,6 +117,9 @@
       Polymer.enqueueDebouncer(this.__renderDebouncer);
     }
 
+    /**
+     * @return {void}
+     */
     disconnectedCallback() {
       super.disconnectedCallback();
       if (!this.parentNode ||
@@ -126,6 +129,9 @@
       }
     }
 
+    /**
+     * @return {void}
+     */
     connectedCallback() {
       super.connectedCallback();
       this.style.display = 'none';
@@ -258,6 +264,13 @@
       }
     }
 
+    /**
+     * Shows or hides the template instance top level child elements. For
+     * text nodes, `textContent` is removed while "hidden" and replaced when
+     * "shown."
+     * @return {void}
+     * @protected
+     */
     _showHideChildren() {
       let hidden = this.__hideTemplateChildren__ || !this.if;
       if (this.__instance) {

lib/elements/dom-repeat.html

@@ -296,6 +296,9 @@
       this.template = null;
     }
 
+    /**
+     * @return {void}
+     */
     disconnectedCallback() {
       super.disconnectedCallback();
       this.__isDetached = true;
@@ -304,6 +307,9 @@
       }
     }
 
+    /**
+     * @return {void}
+     */
     connectedCallback() {
       super.connectedCallback();
       this.style.display = 'none';
@@ -617,6 +623,15 @@
     }
 
     // Implements extension point from Templatize mixin
+    /**
+     * Shows or hides the template instance top level child elements. For
+     * text nodes, `textContent` is removed while "hidden" and replaced when
+     * "shown."
+     * @param {boolean} hidden Set to true to hide the children;
+     * set to false to show them.
+     * @return {void}
+     * @protected
+     */
     _showHideChildren(hidden) {
       for (let i=0; i<this.__instances.length; i++) {
         this.__instances[i]._showHideChildren(hidden);

lib/legacy/class.html

@@ -167,13 +167,19 @@
             null;
         }
 
+        /**
+         * @return {void}
+         */
         created() {
           super.created();
           if (info.created) {
             info.created.call(this);
           }
         }
 
+        /**
+         * @return {void}
+         */
         _registered() {
           super._registered();
           /* NOTE: `beforeRegister` is called here for bc, but the behavior
@@ -191,6 +197,9 @@
           }
         }
 
+        /**
+         * @return {void}
+         */
         _applyListeners() {
           super._applyListeners();
           if (info.listeners) {
@@ -203,6 +212,9 @@
         // note: exception to "super then me" rule;
         // do work before calling super so that super attributes
         // only apply if not already set.
+        /**
+         * @return {void}
+         */
         _ensureAttributes() {
           if (info.hostAttributes) {
             for (let a in info.hostAttributes) {
@@ -212,27 +224,45 @@
           super._ensureAttributes();
         }
 
+        /**
+         * @return {void}
+         */
         ready() {
           super.ready();
           if (info.ready) {
             info.ready.call(this);
           }
         }
 
+        /**
+         * @return {void}
+         */
         attached() {
           super.attached();
           if (info.attached) {
             info.attached.call(this);
           }
         }
 
+        /**
+         * @return {void}
+         */
         detached() {
           super.detached();
           if (info.detached) {
             info.detached.call(this);
           }
         }
 
+        /**
+         * Implements native Custom Elements `attributeChangedCallback` to
+         * set an attribute value to a property via `_attributeToProperty`.
+         *
+         * @param {string} name Name of attribute that changed
+         * @param {?string} old Old attribute value
+         * @param {?string} value New attribute value
+         * @return {void}
+         */
         attributeChanged(name, old, value) {
           super.attributeChanged(name, old, value);
           if (info.attributeChanged) {

lib/legacy/legacy-element-mixin.html

@@ -91,12 +91,14 @@
       /**
        * Legacy callback called during the `constructor`, for overriding
        * by the user.
+       * @return {void}
        */
       created() {}
 
       /**
        * Provides an implementation of `connectedCallback`
        * which adds Polymer legacy API's `attached` method.
+       * @return {void}
        * @override
        */
       connectedCallback() {
@@ -108,12 +110,14 @@
       /**
        * Legacy callback called during `connectedCallback`, for overriding
        * by the user.
+       * @return {void}
        */
       attached() {}
 
       /**
        * Provides an implementation of `disconnectedCallback`
        * which adds Polymer legacy API's `detached` method.
+       * @return {void}
        * @override
        */
       disconnectedCallback() {
@@ -125,6 +129,7 @@
       /**
        * Legacy callback called during `disconnectedCallback`, for overriding
        * by the user.
+       * @return {void}
        */
       detached() {}
 
@@ -150,6 +155,7 @@
        * @param {string} name Name of attribute.
        * @param {?string} old Old value of attribute.
        * @param {?string} value Current value of attribute.
+       * @return {void}
        */
       attributeChanged(name, old, value) {} // eslint-disable-line no-unused-vars
 
@@ -158,6 +164,7 @@
        * add support for class initialization via the `_registered` callback.
        * This is called only when the first instance of the element is created.
        *
+       * @return {void}
        * @override
        */
       _initializeProperties() {
@@ -175,13 +182,15 @@
        * work. The implementation should ensure the work is performed
        * only once for the class.
        * @protected
+       * @return {void}
        */
       _registered() {}
 
       /**
        * Overrides the default `Polymer.PropertyEffects` implementation to
        * add support for installing `hostAttributes` and `listeners`.
        *
+       * @return {void}
        * @override
        */
       ready() {
@@ -198,6 +207,7 @@
        * to the element user and not done here; reasonable exceptions include
        * setting aria roles and focusability.
        * @protected
+       * @return {void}
        */
       _ensureAttributes() {}
 
@@ -210,6 +220,7 @@
        * these elements, consider adding listeners asynchronously so as not to
        * block render.
        * @protected
+       * @return {void}
        */
       _applyListeners() {}
 
@@ -627,7 +638,13 @@
         return this.root === node.getRootNode();
       }
 
-      // NOTE: should now be handled by ShadyCss library.
+      /**
+       * No-op for backwards compatibility. This should now be handled by
+       * ShadyCss library.
+       * @param  {*} container Unused
+       * @param  {*} shouldObserve Unused
+       * @return {void}
+       */
       scopeSubtree(container, shouldObserve) { // eslint-disable-line no-unused-vars
       }
 
@@ -811,6 +828,7 @@
        * @param {boolean=} bool Boolean to force the attribute on or off.
        *    When unspecified, the state of the attribute will be reversed.
        * @param {Element=} node Node to target.  Defaults to `this`.
+       * @return {void}
        */
       toggleAttribute(name, bool, node) {
         node = /** @type {Element} */ (node || this);
@@ -832,6 +850,7 @@
        * @param {boolean=} bool Boolean to force the class on or off.
        *    When unspecified, the state of the class will be reversed.
        * @param {Element=} node Node to target.  Defaults to `this`.
+       * @return {void}
        */
       toggleClass(name, bool, node) {
         node = /** @type {Element} */ (node || this);
@@ -914,6 +933,7 @@
        *
        * @param {string} level One of 'log', 'warn', 'error'
        * @param {Array} args Array of strings or objects to log
+       * @return {void}
        */
       _logger(level, args) {
         // accept ['foo', 'bar'] and [['foo', 'bar']]
@@ -932,6 +952,7 @@
        * Facades `console.log` as an override point.
        *
        * @param {...*} args Array of strings or objects to log
+       * @return {void}
        */
       _log(...args) {
         this._logger('log', args);
@@ -941,6 +962,7 @@
        * Facades `console.warn` as an override point.
        *
        * @param {...*} args Array of strings or objects to log
+       * @return {void}
        */
       _warn(...args) {
         this._logger('warn', args);
@@ -950,6 +972,7 @@
        * Facades `console.error` as an override point.
        *
        * @param {...*} args Array of strings or objects to log
+       * @return {void}
        */
       _error(...args) {
         this._logger('error', args);

lib/mixins/dir-mixin.html

@@ -134,13 +134,17 @@
 
         /**
          * @suppress {invalidCasts} Closure doesn't understand that `this` is an HTMLElement
+         * @return {void}
          */
         ready() {
           super.ready();
           this.__autoDirOptOut = /** @type {!HTMLElement} */(this).hasAttribute('dir');
         }
 
-        /** @suppress {missingProperties} If it exists on elementBase, it can be super'd */
+        /**
+         * @suppress {missingProperties} If it exists on elementBase, it can be super'd
+         * @return {void}
+         */
         connectedCallback() {
           if (elementBase.prototype.connectedCallback) {
             super.connectedCallback();
@@ -152,7 +156,10 @@
           }
         }
 
-        /** @suppress {missingProperties} If it exists on elementBase, it can be super'd */
+        /**
+         * @suppress {missingProperties} If it exists on elementBase, it can be super'd
+         * @return {void}
+         */
         disconnectedCallback() {
           if (elementBase.prototype.disconnectedCallback) {
             super.disconnectedCallback();
@@ -171,4 +178,4 @@
       return Dir;
     });
   })();
-</script>
+</script>

lib/mixins/element-mixin.html

@@ -443,6 +443,7 @@
        * It also initializes any property defaults provided via `value` in
        * `properties` metadata.
        *
+       * @return {void}
        * @override
        * @suppress {invalidCasts}
        */
@@ -525,6 +526,7 @@
        * when using the ShadyCSS scoping/custom properties polyfill.
        *
        * @suppress {missingProperties, invalidCasts} Super may or may not implement the callback
+       * @return {void}
        */
       connectedCallback() {
         if (window.ShadyCSS && this._template) {
@@ -536,6 +538,7 @@
       /**
        * Stamps the element template.
        *
+       * @return {void}
        * @override
        */
       ready() {
@@ -553,6 +556,7 @@
        * client dom to be attached to the element prior to any observers
        * running.
        *
+       * @return {void}
        * @override
        */
       _readyClients() {