[Devtools] Cleanup devtools.js and typecast for jsdoc

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

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 /* eslint-disable indent */
 (function(window) {
 
 // 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
  */
 function DevToolsAPIImpl()
 {
     /**
      * @type {number}
      */
     this._lastCallId = 0;
 
@@ skipping 27 matching lines @@
         if (callback)
             this._callbacks[callId] = callback;
         var message = { "id": callId, "method": method };
         if (args.length)
             message.params = args;
         DevToolsHost.sendMessageToEmbedder(JSON.stringify(message));
     },
 
     /**
      * @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 --------------------------------------------
 
     /**
      * @param {!Array.<!ExtensionDescriptor>} extensions
      */
     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]);
     },
 
     /**
      * @param {string} url
      */
     appendedToURL: function(url)
     {
         this._dispatchOnInspectorFrontendAPI("appendedToURL", [url]);
@@ skipping 190 matching lines @@
     {
         this._dispatchOnInspectorFrontendAPI("searchCompleted", [requestId, fileSystemPath, files]);
     },
 
     /**
      * @param {string} tabId
      */
     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]);
     },
 
     /**
      * @param {boolean} useSoftMenu
      */
     setUseSoftMenu: function(useSoftMenu)
     {
         this._dispatchOnInspectorFrontendAPI("setUseSoftMenu", [useSoftMenu]);
@@ skipping 600 matching lines @@
         this.recordEnumeratedHistogram("DevTools.PanelShown", panelCode, 20);
     }
 };
 
 window.InspectorFrontendHost = new InspectorFrontendHostImpl();
 
 // DevToolsApp ---------------------------------------------------------------
 
 function installObjectObserve()
 {
+    /** @type {!Array<string>} */
     var properties = [
         "advancedSearchConfig", "auditsPanelSplitViewState", "auditsSidebarWidth", "blockedURLs", "breakpoints", "cacheDisabled", "colorFormat", "consoleHistory",
         "consoleTimestampsEnabled", "cpuProfilerView", "cssSourceMapsEnabled", "currentDockState", "customColorPalette", "customDevicePresets", "customEmulatedDeviceList",
         "customFormatters", "customUserAgent", "databaseTableViewVisibleColumns", "dataGrid-cookiesTable", "dataGrid-DOMStorageItemsView", "debuggerSidebarHidden", "disableDataSaverInfobar",
         "disablePausedStateOverlay", "domBreakpoints", "domWordWrap", "elementsPanelSplitViewState", "elementsSidebarWidth", "emulation.deviceHeight", "emulation.deviceModeValue",
         "emulation.deviceOrientationOverride", "emulation.deviceScale", "emulation.deviceScaleFactor", "emulation.deviceUA", "emulation.deviceWidth", "emulation.geolocationOverride",
         "emulation.showDeviceMode", "emulation.showRulers", "enableAsyncStackTraces", "eventListenerBreakpoints", "fileMappingEntries", "fileSystemMapping", "FileSystemViewSidebarWidth",
         "fileSystemViewSplitViewState", "filterBar-consoleView", "filterBar-networkPanel", "filterBar-promisePane", "filterBar-timelinePanel", "frameViewerHideChromeWindow",
         "heapSnapshotRetainersViewSize", "heapSnapshotSplitViewState", "hideCollectedPromises", "hideNetworkMessages", "highlightNodeOnHoverInOverlay", "highResolutionCpuProfiling",
         "inlineVariableValues", "Inspector.drawerSplitView", "Inspector.drawerSplitViewState", "InspectorView.panelOrder", "InspectorView.screencastSplitView",
@@ skipping 18 matching lines @@
         "workspaceExcludedFolders", "workspaceFolderExcludePattern", "workspaceInfobarDisabled", "workspaceMappingInfobarDisabled", "xhrBreakpoints"];
 
     /**
      * @this {!{_storage: Object, _name: string}}
      */
     function settingRemove()
     {
         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) {
                 storage.set(property, object[property]);
                 delete object[property];
             }
 
             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);
                     changedProperties.add(property);
                     scheduleObserver();
                 }
             });
         }
 
         for (var i = 0; i < properties.length; ++i)
             defineProperty(properties[i]);
     }
 
     window.Object.observe = objectObserve;
 }
 
+/** @type {!Map<number, string>} */
 var staticKeyIdentifiers = new Map([
     [0x12, "Alt"],
     [0x11, "Control"],
     [0x10, "Shift"],
     [0x14, "CapsLock"],
     [0x5b, "Win"],
     [0x5c, "Win"],
     [0x0c, "Clear"],
     [0x28, "Down"],
     [0x23, "End"],
@@ skipping 39 matching lines @@
     [0x2e, "U+007F"], // Standard says that DEL becomes U+007F.
     [0xb0, "MediaNextTrack"],
     [0xb1, "MediaPreviousTrack"],
     [0xb2, "MediaStop"],
     [0xb3, "MediaPlayPause"],
     [0xad, "VolumeMute"],
     [0xae, "VolumeDown"],
     [0xaf, "VolumeUp"],
 ]);
 
+/**
+ * @param {number} keyCode
+ * @return {string}
+ */
 function keyCodeToKeyIdentifier(keyCode)
 {
     var result = staticKeyIdentifiers.get(keyCode);
     if (result !== undefined)
         return result;
     result = "U+";
     var hexString = keyCode.toString(16).toUpperCase();
     for (var i = hexString.length; i < 4; ++i)
         result += "0";
     result += hexString;
     return result;
 }
 
-/**
- * @suppressGlobalPropertiesCheck
- * @suppress {checkTypes}
- */
 function installBackwardsCompatibility()
 {
     if (window.location.search.indexOf("remoteFrontend") === -1)
         return;
 
     // 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);
             }
         });
     }
 
     // Support for legacy (<M50) frontends.
     installObjectObserve();
 
     /**
+     * @param {string} property
+     * @return {!CSSValue|null}
      * @this {CSSStyleDeclaration}
      */
     function getValue(property)
     {
         // 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");
     }
 
     // Support for legacy (<M41) frontends.
     window.CSSStyleDeclaration.prototype.getPropertyCSSValue = getValue;
 
     function CSSPrimitiveValue()
     {
     }
     CSSPrimitiveValue.CSS_PX = 5;
     window.CSSPrimitiveValue = CSSPrimitiveValue;
 
     // Support for legacy (<M44) frontends.
     var styleElement = window.document.createElement("style");
     styleElement.type = "text/css";
     styleElement.textContent = "html /deep/ * { min-width: 0; min-height: 0; }";
 
     // Support for quirky border-image behavior (<M51), see:
     // https://bugs.chromium.org/p/chromium/issues/detail?id=559258
     styleElement.textContent += "\nhtml /deep/ .cm-breakpoint .CodeMirror-linenumber { border-style: solid !important; }";
     styleElement.textContent += "\nhtml /deep/ .cm-breakpoint.cm-breakpoint-conditional .CodeMirror-linenumber { border-style: solid !important; }";
     window.document.head.appendChild(styleElement);
 
     // Support for legacy (<M49) frontends.
     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()
 {
     window.removeEventListener("DOMContentLoaded", windowLoaded, false);
     installBackwardsCompatibility();
 }
 
 if (window.document.head && (window.document.readyState === "complete" || window.document.readyState === "interactive"))
     installBackwardsCompatibility();
 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)
             force = !this.contains(token);
         return this.__originalDOMTokenListToggle(token, !!force);
     };
 }
 
 })(window);