[Devtools] Cleanup devtools.js and typecast for jsdoc

third_party/WebKit/Source/devtools/front_end/devtools.js

Index: third_party/WebKit/Source/devtools/front_end/devtools.js
diff --git a/third_party/WebKit/Source/devtools/front_end/devtools.js b/third_party/WebKit/Source/devtools/front_end/devtools.js
index ea6ac371f9f5ebf8e2036aa6e09e7c96d8412702..afa72f2e67679d3d4be4dfa64e4ba9e50b211294 100644
--- a/third_party/WebKit/Source/devtools/front_end/devtools.js
+++ b/third_party/WebKit/Source/devtools/front_end/devtools.js
@@ -7,6 +7,21 @@
 
 // DevToolsAPI ----------------------------------------------------------------
 
+// These are in place to allow jsDoc to know about types that are not known until runtime.
+/** @type {(!{
+    Setting: ?{

[dgozman, 2016/10/26 22:03:15]

I feel uneasy about this - we are tricking ourselves, since the compiler does
only check that I managed to match the code and this artificial typedef.

[allada, 2016/10/27 16:32:38]

Closure complains about these references in other places if you run it in super
strict mode. The idea is that if these exist they should look like this (like an
optional interface).

+        prototype: {
+            remove: ?function()
+        }
+    },
+    addExtensions: ?function(!Array.<!ExtensionDescriptor>),
+    setInspectedTabId: ?function(string)
+}|undefined)} */
+window.WebInspector;

[lushnikov, 2016/10/26 22:10:43]

this should go to extenrs.js

[allada, 2016/10/26 22:46:46]

If it goes in externs it will override all of it... in this case this file is
always compiled by itself.

[lushnikov, 2016/10/27 02:56:21]

What do you mean by "always compiled by itself"?

[allada, 2016/10/27 16:32:37]

According to dgozman this file may interact with old versions of devtools, so
when this file is compiled it is compiled in closure as a standalone file.

+
+/** @type {!Object<string, (function(!Array<*>)|undefined)>} */
+window.InspectorFrontendAPI;
+
 /**
  * @constructor
  */
@@ -54,12 +69,11 @@ DevToolsAPIImpl.prototype = {
 
     /**
      * @param {string} method
-     * @param {!Array.<*>} args
+     * @param {!Array<*>} args
      */
     _dispatchOnInspectorFrontendAPI: function(method, args)
     {
-        var api = window["InspectorFrontendAPI"];
-        api[method].apply(api, args);
+        window.InspectorFrontendAPI[method].apply(window.InspectorFrontendAPI, args);
     },
 
     // API methods below this line --------------------------------------------
@@ -70,8 +84,8 @@ DevToolsAPIImpl.prototype = {
     addExtensions: function(extensions)
     {
         // Support for legacy front-ends (<M41).
-        if (window["WebInspector"].addExtensions)
-            window["WebInspector"].addExtensions(extensions);
+        if (window.WebInspector.addExtensions)
+            window.WebInspector.addExtensions(extensions);
         else
             this._dispatchOnInspectorFrontendAPI("addExtensions", [extensions]);
     },
@@ -282,8 +296,8 @@ DevToolsAPIImpl.prototype = {
     setInspectedTabId: function(tabId)
     {
         // Support for legacy front-ends (<M41).
-        if (window["WebInspector"].setInspectedTabId)
-            window["WebInspector"].setInspectedTabId(tabId);
+        if (window.WebInspector.setInspectedTabId)
+            window.WebInspector.setInspectedTabId(tabId);
         else
             this._dispatchOnInspectorFrontendAPI("setInspectedTabId", [tabId]);
     },
@@ -904,6 +918,7 @@ window.InspectorFrontendHost = new InspectorFrontendHostImpl();
 
 function installObjectObserve()
 {
+    /** @type {!Array<string>} */
     var properties = [
         "advancedSearchConfig", "auditsPanelSplitViewState", "auditsSidebarWidth", "blockedURLs", "breakpoints", "cacheDisabled", "colorFormat", "consoleHistory",
         "consoleTimestampsEnabled", "cpuProfilerView", "cssSourceMapsEnabled", "currentDockState", "customColorPalette", "customDevicePresets", "customEmulatedDeviceList",
@@ -942,36 +957,44 @@ function installObjectObserve()
         this._storage[this._name] = undefined;
     }
 
+    /**
+     * @param {!Object} object
+     * @param {function(!Array<!{name: string}>)} observer
+     */
     function objectObserve(object, observer)
     {
-        if (window["WebInspector"]) {
-            var settingPrototype = window["WebInspector"]["Setting"]["prototype"];
-            if (typeof settingPrototype["remove"] === "function")
-                settingPrototype["remove"] = settingRemove;
+        if (window.WebInspector) {
+            var settingPrototype = window.WebInspector.Setting.prototype;
+            if (typeof settingPrototype.remove === "function")
+                settingPrototype.remove = settingRemove;
         }
-
+        /** @type {!Set<string>} */
         var changedProperties = new Set();
         var scheduled = false;
 
         function scheduleObserver()
         {
-            if (!scheduled) {
-                scheduled = true;
-                setImmediate(callObserver);
-            }
+            if (scheduled)
+                return;
+            scheduled = true;
+            setImmediate(callObserver);
         }
 
         function callObserver()
         {
             scheduled = false;
-            var changes = [];
+            var changes = /** @type {!Array<!{name: string}>} */ ([]);
             changedProperties.forEach(function(name) { changes.push({name: name}); });
             changedProperties.clear();
             observer.call(null, changes);
         }
 
+        /** @type {!Map<string, *>} */
         var storage = new Map();
 
+        /**
+         * @param {string} property
+         */
         function defineProperty(property)
         {
             if (property in object) {
@@ -980,11 +1003,17 @@ function installObjectObserve()
             }
 
             Object.defineProperty(object, property, {
+                /**
+                 * @return {*}

[lushnikov, 2016/10/26 22:10:43]

does typing something with "*" make sense?

[allada, 2016/10/26 22:46:46]

We are overriding something that we do not know what can be put here. So in this
case yes, * means any data type. "?" means unknown data type... we have many
cases where we already use "*".

[lushnikov, 2016/10/27 02:56:21]

AFAIU the * is the default type in closure's type inference system. So why would
you want to declare it explicitly? 

[allada, 2016/10/27 16:32:38]

Because my goals it get closure 100% typed.

+                 */
                 get: function()
                 {
                     return storage.get(property);
                 },
 
+                /**
+                 * @param {*} value
+                 */
                 set: function(value)
                 {
                     storage.set(property, value);
@@ -1001,6 +1030,7 @@ function installObjectObserve()
     window.Object.observe = objectObserve;
 }
 
+/** @type {!Map<number, string>} */
 var staticKeyIdentifiers = new Map([
     [0x12, "Alt"],
     [0x11, "Control"],
@@ -1060,6 +1090,10 @@ var staticKeyIdentifiers = new Map([
     [0xaf, "VolumeUp"],
 ]);
 
+/**
+ * @param {number} keyCode
+ * @return {string}
+ */
 function keyCodeToKeyIdentifier(keyCode)
 {
     var result = staticKeyIdentifiers.get(keyCode);
@@ -1073,10 +1107,6 @@ function keyCodeToKeyIdentifier(keyCode)
     return result;
 }
 
-/**
- * @suppressGlobalPropertiesCheck
- * @suppress {checkTypes}
- */
 function installBackwardsCompatibility()
 {
     if (window.location.search.indexOf("remoteFrontend") === -1)
@@ -1085,6 +1115,10 @@ function installBackwardsCompatibility()
     // Support for legacy (<M53) frontends.
     if (!window.KeyboardEvent.prototype.hasOwnProperty("keyIdentifier")) {
         Object.defineProperty(window.KeyboardEvent.prototype, "keyIdentifier", {
+            /**
+             * @return {string}
+             * @this {KeyboardEvent}
+             */
             get: function()
             {
                 return keyCodeToKeyIdentifier(this.keyCode);
@@ -1096,6 +1130,8 @@ function installBackwardsCompatibility()
     installObjectObserve();
 
     /**
+     * @param {string} property
+     * @return {!CSSValue|null}
      * @this {CSSStyleDeclaration}
      */
     function getValue(property)
@@ -1103,14 +1139,14 @@ function installBackwardsCompatibility()
         // Note that |property| comes from another context, so we can't use === here.
         // eslint-disable-next-line eqeqeq
         if (property == "padding-left") {
-            return {
+            return /** @type {!CSSValue} */ ({
                 /**
-                 * @suppressReceiverCheck
-                 * @this {Object}
+                 * @return {number}
+                 * @this {!{__paddingLeft: number}}
                  */
-                getFloatValue: function() { return this.__paddingLeft; },
+                getFloatValue: function() { return /** @type {number} */ (this.__paddingLeft); },

[dgozman, 2016/10/26 22:03:15]

These annotations looks strange: why do we have to repeat paddingLeft 3 times?
Looks like not worth it.

[allada, 2016/10/26 22:46:47]

Done.

                 __paddingLeft: parseFloat(this.paddingLeft)
-            };
+            });
         }
         throw new Error("getPropertyCSSValue is undefined");
     }
@@ -1139,12 +1175,12 @@ function installBackwardsCompatibility()
     Event.prototype.deepPath = undefined;
 
     // Support for legacy (<53) frontends.
-    window.FileError = {
+    window.FileError = /** @type {!function (new: FileError) : ?} */ ({

[dgozman, 2016/10/26 22:03:15]

Why this?

[allada, 2016/10/26 22:46:47]

Yes, I was surprised too, but this is how JSDoc has FileError defined.

         NOT_FOUND_ERR: DOMException.NOT_FOUND_ERR,
         ABORT_ERR: DOMException.ABORT_ERR,
         INVALID_MODIFICATION_ERR: DOMException.INVALID_MODIFICATION_ERR,
         NOT_READABLE_ERR: 0  // No matching DOMException, so code will be 0.
-    };
+    });
 }
 
 function windowLoaded()
@@ -1158,8 +1194,16 @@ if (window.document.head && (window.document.readyState === "complete" || window
 else
     window.addEventListener("DOMContentLoaded", windowLoaded, false);
 
+/** @type {(!function(string, boolean=):boolean)|undefined} */
+DOMTokenList.prototype.__originalDOMTokenListToggle;
+
 if (!DOMTokenList.prototype.__originalDOMTokenListToggle) {
     DOMTokenList.prototype.__originalDOMTokenListToggle = DOMTokenList.prototype.toggle;
+    /**
+     * @param {string} token
+     * @param {boolean=} force
+     * @return {boolean}
+     */
     DOMTokenList.prototype.toggle = function(token, force)
     {
         if (arguments.length === 1)