DevTools: [JSDoc] Fix injected scripts JSDoc and related code

Source/core/inspector/InjectedScriptSource.js

 /*
  * Copyright (C) 2007 Apple Inc.  All rights reserved.
  * Copyright (C) 2013 Google Inc. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  *
  * 1.  Redistributions of source code must retain the above copyright
  *     notice, this list of conditions and the following disclaimer.
@@ skipping 87 matching lines @@
 function toStringDescription(obj)
 {
     if (typeof obj === "number" && obj === 0 && 1 / obj < 0)
         return "-0"; // Negative zero.
     return "" + obj;
 }
 
 /**
  * Please use this bind, not the one from Function.prototype
  * @param {function(...)} func
- * @param {Object} thisObject
+ * @param {?Object} thisObject
  * @param {...} var_args
+ * @return {function(...)}
  */
 function bind(func, thisObject, var_args)
 {
     var args = slice(arguments, 2);
 
     /**
      * @param {...} var_args
      */
     function bound(var_args)
     {
@@ skipping 52 matching lines @@
     return a > b ? a : b;
 }
 
 /**
  * @constructor
  */
 var InjectedScript = function()
 {
     /** @type {number} */
     this._lastBoundObjectId = 1;
-    /** @type {!Object.<number, Object>} */
+    /** @type {!Object.<number, !Object>} */
     this._idToWrappedObject = { __proto__: null };
     /** @type {!Object.<number, string>} */
     this._idToObjectGroupName = { __proto__: null };
-    /** @type {!Object.<string, Array.<number>>} */
+    /** @type {!Object.<string, !Array.<number>>} */
     this._objectGroups = { __proto__: null };
-    /** @type {!Object.<string, Object>} */
+    /** @type {!Object.<string, !Object>} */
     this._modules = { __proto__: null };
 }
 
 /**
  * @type {!Object.<string, boolean>}
  * @const
  */
 InjectedScript.primitiveTypes = {
     "undefined": true,
     "boolean": true,
@@ skipping 37 matching lines @@
         result.type = typeof object;
         if (this.isPrimitiveValue(object))
             result.value = object;
         else
             result.description = toString(object);
         return /** @type {!RuntimeAgent.RemoteObject} */ (result);
     },
 
     /**
      * @param {boolean} canAccessInspectedWindow
-     * @param {Object} table
-     * @param {Array.<string>|string|boolean} columns
+     * @param {!Object} table
+     * @param {!Array.<string>|string|boolean} columns
      * @return {!RuntimeAgent.RemoteObject}
      */
     wrapTable: function(canAccessInspectedWindow, table, columns)
     {
         if (!canAccessInspectedWindow)
             return this._fallbackWrapper(table);
         var columnNames = null;
         if (typeof columns === "string")
             columns = [columns];
         if (InjectedScriptHost.type(columns) == "array") {
@@ skipping 47 matching lines @@
             try {
                 var description = injectedScript._describe(e);
             } catch (ex) {
                 var description = "<failed to convert exception to string>";
             }
             return new InjectedScript.RemoteObject(description);
         }
     },
 
     /**
-     * @param {Object} object
+     * @param {!Object} object
      * @param {string=} objectGroupName
      * @return {string}
      */
     _bind: function(object, objectGroupName)
     {
         var id = this._lastBoundObjectId++;
         this._idToWrappedObject[id] = object;
         var objectId = "{\"injectedScriptId\":" + injectedScriptId + ",\"id\":" + id + "}";
         if (objectGroupName) {
             var group = this._objectGroups[objectGroupName];
@@ skipping 42 matching lines @@
             inspectedWindow.console.error("Web Inspector error: InjectedScript.%s returns undefined", methodName);
             result = null;
         }
         return result;
     },
 
     /**
      * @param {string} objectId
      * @param {boolean} ownProperties
      * @param {boolean} accessorPropertiesOnly
-     * @return {Array.<RuntimeAgent.PropertyDescriptor>|boolean}
+     * @return {!Array.<!RuntimeAgent.PropertyDescriptor>|boolean}
      */
     getProperties: function(objectId, ownProperties, accessorPropertiesOnly)
     {
         var parsedObjectId = this._parseObjectId(objectId);
         var object = this._objectForId(parsedObjectId);
         var objectGroupName = this._idToObjectGroupName[parsedObjectId.id];
 
         if (!this._isDefined(object))
             return false;
         var descriptors = this._propertyDescriptors(object, ownProperties, accessorPropertiesOnly);
@@ skipping 12 matching lines @@
             if (!("enumerable" in descriptor))
                 descriptor.enumerable = false;
             if ("symbol" in descriptor)
                 descriptor.symbol = this._wrapObject(descriptor.symbol, objectGroupName);
         }
         return descriptors;
     },
 
     /**
      * @param {string} objectId
-     * @return {Array.<Object>|boolean}
+     * @return {!Array.<!Object>|boolean}
      */
-    getInternalProperties: function(objectId, ownProperties)
+    getInternalProperties: function(objectId)
     {
         var parsedObjectId = this._parseObjectId(objectId);
         var object = this._objectForId(parsedObjectId);
         var objectGroupName = this._idToObjectGroupName[parsedObjectId.id];
         if (!this._isDefined(object))
             return false;
         var descriptors = [];
         var internalProperties = InjectedScriptHost.getInternalProperties(object);
         if (internalProperties) {
             for (var i = 0; i < internalProperties.length; i++) {
@@ skipping 44 matching lines @@
     /**
      * @param {number} id
      */
     _releaseObject: function(id)
     {
         delete this._idToWrappedObject[id];
         delete this._idToObjectGroupName[id];
     },
 
     /**
-     * @param {Object} object
+     * @param {!Object} object
      * @param {boolean=} ownProperties
      * @param {boolean=} accessorPropertiesOnly
-     * @return {Array.<Object>}
+     * @return {!Array.<!Object>}
      */
     _propertyDescriptors: function(object, ownProperties, accessorPropertiesOnly)
     {
         var descriptors = [];
         var propertyProcessed = { __proto__: null };
 
         /**
-         * @param {Object} o
+         * @param {?Object} o
          * @param {!Array.<string|symbol>} properties
          */
         function process(o, properties)
         {
             for (var i = 0; i < properties.length; ++i) {
                 var property = properties[i];
                 if (propertyProcessed[property])
                     continue;
 
                 var name = property;
@@ skipping 64 matching lines @@
      * @return {*}
      */
     evaluate: function(expression, objectGroup, injectCommandLineAPI, returnByValue, generatePreview)
     {
         return this._evaluateAndWrap(InjectedScriptHost.evaluate, InjectedScriptHost, expression, objectGroup, false, injectCommandLineAPI, returnByValue, generatePreview);
     },
 
     /**
      * @param {string} objectId
      * @param {string} expression
+     * @param {string} args
      * @param {boolean} returnByValue
      * @return {!Object|string}
      */
     callFunctionOn: function(objectId, expression, args, returnByValue)
     {
         var parsedObjectId = this._parseObjectId(objectId);
         var object = this._objectForId(parsedObjectId);
         if (!this._isDefined(object))
             return "Could not find object with given id";
 
@@ skipping 18 matching lines @@
             return { wasThrown: false,
                      result: this._wrapObject(func.apply(object, resolvedArgs), objectGroup, returnByValue),
                      __proto__: null };
         } catch (e) {
             return this._createThrownValue(e, objectGroup);
         }
     },
 
     /**
      * Resolves a value from CallArgument description.
-     * @param {RuntimeAgent.CallArgument} callArgumentJson
+     * @param {!RuntimeAgent.CallArgument} callArgumentJson
      * @return {*} resolved value
      * @throws {string} error message
      */
     _resolveCallArgument: function(callArgumentJson)
     {
         callArgumentJson = nullifyObjectProto(callArgumentJson);
         var objectId = callArgumentJson.objectId;
         if (objectId) {
             var parsedArgId = this._parseObjectId(objectId);
             if (!parsedArgId || parsedArgId["injectedScriptId"] !== injectedScriptId)
                 throw "Arguments should belong to the same JavaScript world as the target object.";
 
             var resolvedArg = this._objectForId(parsedArgId);
             if (!this._isDefined(resolvedArg))
                 throw "Could not find object with given id";
 
             return resolvedArg;
         } else if ("value" in callArgumentJson) {
             var value = callArgumentJson.value;
             if (callArgumentJson.type === "number" && typeof value !== "number")
                 value = Number(value);
             return value;
         }
         return undefined;
     },
 
     /**
-     * @param {Function} evalFunction
-     * @param {Object} object
+     * @param {!Function} evalFunction
+     * @param {!Object} object
+     * @param {string} expression
      * @param {string} objectGroup
      * @param {boolean} isEvalOnCallFrame
      * @param {boolean} injectCommandLineAPI
      * @param {boolean} returnByValue
      * @param {boolean} generatePreview
      * @param {!Array.<!Object>=} scopeChain
      * @return {!Object}
      */
     _evaluateAndWrap: function(evalFunction, object, expression, objectGroup, isEvalOnCallFrame, injectCommandLineAPI, returnByValue, generatePreview, scopeChain)
     {
@@ skipping 14 matching lines @@
     _createThrownValue: function(value, objectGroup)
     {
         var remoteObject = this._wrapObject(value, objectGroup);
         try {
             remoteObject.description = toStringDescription(value);
         } catch (e) {}
         return { wasThrown: true, result: remoteObject, __proto__: null };
     },
 
     /**
-     * @param {Function} evalFunction
-     * @param {Object} object
+     * @param {!Function} evalFunction
+     * @param {!Object} object
      * @param {string} objectGroup
      * @param {string} expression
      * @param {boolean} isEvalOnCallFrame
      * @param {boolean} injectCommandLineAPI
      * @param {!Array.<!Object>=} scopeChain
      * @return {*}
      */
     _evaluateOn: function(evalFunction, object, objectGroup, expression, isEvalOnCallFrame, injectCommandLineAPI, scopeChain)
     {
         // Only install command line api object for the time of evaluation.
@@ skipping 178 matching lines @@
         if (asyncOrdinal)
             topCallFrame = asyncCallStacks[asyncOrdinal - 1];
         var ordinal = parsedCallFrameId["ordinal"];
         var callFrame = topCallFrame;
         while (--ordinal >= 0 && callFrame)
             callFrame = callFrame.caller;
         return callFrame;
     },
 
     /**
-     * @param {Object} objectId
-     * @return {Object}
+     * @param {!Object} objectId
+     * @return {!Object}
      */
     _objectForId: function(objectId)
     {
         return this._idToWrappedObject[objectId.id];
     },
 
     /**
      * @param {string} objectId
-     * @return {Object}
+     * @return {!Object}
      */
     findObjectById: function(objectId)
     {
         var parsedObjectId = this._parseObjectId(objectId);
         return this._objectForId(parsedObjectId);
     },
 
     /**
      * @param {string} objectId
-     * @return {Node}
+     * @return {?Node}
      */
     nodeForObjectId: function(objectId)
     {
         var object = this.findObjectById(objectId);
         if (!object || this._subtype(object) !== "node")
             return null;
-        return /** @type {Node} */ (object);
+        return /** @type {!Node} */ (object);
     },
 
     /**
      * @param {string} name
-     * @return {Object}
+     * @return {!Object}
      */
     module: function(name)
     {
         return this._modules[name];
     },
 
     /**
      * @param {string} name
      * @param {string} source
-     * @return {Object}
+     * @return {?Object}
      */
     injectModule: function(name, source)
     {
         delete this._modules[name];
         var moduleFunction = InjectedScriptHost.evaluate("(" + source + ")");
         if (typeof moduleFunction !== "function") {
             inspectedWindow.console.error("Web Inspector error: A function was expected for module %s evaluation", name);
             return null;
         }
         var module = moduleFunction.call(inspectedWindow, InjectedScriptHost, inspectedWindow, injectedScriptId, this);
@@ skipping 15 matching lines @@
      * @return {boolean}
      */
     _isHTMLAllCollection: function(object)
     {
         // document.all is reported as undefined, but we still want to process it.
         return (typeof object === "undefined") && InjectedScriptHost.isHTMLAllCollection(object);
     },
 
     /**
      * @param {*} obj
-     * @return {string?}
+     * @return {?string}
      */
     _subtype: function(obj)
     {
         if (obj === null)
             return "null";
 
         if (this.isPrimitiveValue(obj))
             return null;
 
         if (this._isHTMLAllCollection(obj))
             return "array";
 
         var preciseType = InjectedScriptHost.type(obj);
         if (preciseType)
             return preciseType;
 
         if (isArrayLike(obj))
             return "array";
 
         // If owning frame has navigated to somewhere else window properties will be undefined.
         return null;
     },
 
     /**
      * @param {*} obj
-     * @return {string?}
+     * @return {?string}
      */
     _describe: function(obj)
     {
         if (this.isPrimitiveValue(obj))
             return null;
 
         var type = typeof obj;
         var subtype = this._subtype(obj);
 
         if (subtype === "regexp")
@@ skipping 84 matching lines @@
             case "-Infinity":
             case "-0":
                 this.value = this.description;
                 break;
             }
         }
 
         return;
     }
 
-    object = /** @type {Object} */ (object);
+    object = /** @type {!Object} */ (object);
 
     this.objectId = injectedScript._bind(object, objectGroupName);
     var subtype = injectedScript._subtype(object);
     if (subtype)
         this.subtype = subtype;
     var className = InjectedScriptHost.internalConstructorName(object);
     if (className)
         this.className = className;
     this.description = injectedScript._describe(object);
 
     if (generatePreview && (this.type === "object" || injectedScript._isHTMLAllCollection(object)))
         this.preview = this._generatePreview(object, undefined, columnNames, isTable, false);
 }
 
 InjectedScript.RemoteObject.prototype = {
     /**
-     * @param {Object} object
-     * @param {Array.<string>=} firstLevelKeys
+     * @param {!Object} object
+     * @param {?Array.<string>=} firstLevelKeys
      * @param {?Array.<string>=} secondLevelKeys
      * @param {boolean=} isTable
      * @param {boolean=} isTableRow
      * @return {!RuntimeAgent.ObjectPreview} preview
      */
     _generatePreview: function(object, firstLevelKeys, secondLevelKeys, isTable, isTableRow)
     {
         var preview = { __proto__: null };
         preview.lossless = true;
         preview.overflow = false;
@@ skipping 149 matching lines @@
     this.functionName = (callFrame.type === "function" ? callFrame.functionName : "");
     this.location = { scriptId: toString(callFrame.sourceID), lineNumber: callFrame.line, columnNumber: callFrame.column, __proto__: null };
     this.scopeChain = this._wrapScopeChain(callFrame);
     this.this = injectedScript._wrapObject(callFrame.thisObject, "backtrace");
     if (callFrame.isAtReturn)
         this.returnValue = injectedScript._wrapObject(callFrame.returnValue, "backtrace");
 }
 
 InjectedScript.CallFrameProxy.prototype = {
     /**
-     * @param {Object} callFrame
-     * @return {!Array.<DebuggerAgent.Scope>}
+     * @param {!Object} callFrame
+     * @return {!Array.<!DebuggerAgent.Scope>}
      */
     _wrapScopeChain: function(callFrame)
     {
         var scopeChain = callFrame.scopeChain;
         var scopeChainProxy = [];
         for (var i = 0; i < scopeChain.length; ++i)
             scopeChainProxy[i] = InjectedScript.CallFrameProxy._createScopeJson(callFrame.scopeType(i), scopeChain[i], "backtrace");
         return scopeChainProxy;
     },
 
@@ skipping 17 matching lines @@
     /** @type {!Object.<number, string>} */
     var scopeTypeNames = { __proto__: null };
     scopeTypeNames[GLOBAL_SCOPE] = "global";
     scopeTypeNames[LOCAL_SCOPE] = "local";
     scopeTypeNames[WITH_SCOPE] = "with";
     scopeTypeNames[CLOSURE_SCOPE] = "closure";
     scopeTypeNames[CATCH_SCOPE] = "catch";
 
     return {
         object: injectedScript._wrapObject(scopeObject, groupId),
-        type: /** @type {DebuggerAgent.ScopeType} */ (scopeTypeNames[scopeTypeCode]),
+        type: /** @type {!DebuggerAgent.ScopeType} */ (scopeTypeNames[scopeTypeCode]),
         __proto__: null
     };
 }
 
 /**
  * @constructor
- * @param {CommandLineAPIImpl} commandLineAPIImpl
- * @param {Object} callFrame
+ * @param {!CommandLineAPIImpl} commandLineAPIImpl
+ * @param {?Object} callFrame
  */
 function CommandLineAPI(commandLineAPIImpl, callFrame)
 {
     /**
      * @param {string} member
      * @return {boolean}
      */
     function inScopeVariables(member)
     {
         if (!callFrame)
@@ skipping 47 matching lines @@
     }
 
     this.$_ = injectedScript._lastResult;
 
     this.__proto__ = null;
 }
 
 // NOTE: Please keep the list of API methods below snchronized to that in WebInspector.RuntimeModel!
 // NOTE: Argument names of these methods will be printed in the console, so use pretty names!
 /**
- * @type {Array.<string>}
+ * @type {!Array.<string>}
  * @const
  */
 CommandLineAPI.members_ = [
     "$", "$$", "$x", "dir", "dirxml", "keys", "values", "profile", "profileEnd",
     "monitorEvents", "unmonitorEvents", "inspect", "copy", "clear", "getEventListeners",
     "debug", "undebug", "monitor", "unmonitor", "table"
 ];
 
 /**
  * @constructor
  */
 function CommandLineAPIImpl()
 {
 }
 
 CommandLineAPIImpl.prototype = {
     /**
      * @param {string} selector
-     * @param {Node=} opt_startNode
+     * @param {!Node=} opt_startNode
+     * @return {*}
      */
     $: function (selector, opt_startNode)
     {
         if (this._canQuerySelectorOnNode(opt_startNode))
             return opt_startNode.querySelector(selector);
 
         return inspectedWindow.document.querySelector(selector);
     },
 
     /**
      * @param {string} selector
-     * @param {Node=} opt_startNode
+     * @param {!Node=} opt_startNode
+     * @return {*}
      */
     $$: function (selector, opt_startNode)
     {
         if (this._canQuerySelectorOnNode(opt_startNode))
             return opt_startNode.querySelectorAll(selector);
         return inspectedWindow.document.querySelectorAll(selector);
     },
 
     /**
-     * @param {Node=} node
+     * @param {!Node=} node
      * @return {boolean}
      */
     _canQuerySelectorOnNode: function(node)
     {
         return !!node && InjectedScriptHost.type(node) === "node" && (node.nodeType === Node.ELEMENT_NODE || node.nodeType === Node.DOCUMENT_NODE || node.nodeType === Node.DOCUMENT_FRAGMENT_NODE);
     },
 
     /**
      * @param {string} xpath
-     * @param {Node=} opt_startNode
+     * @param {!Node=} opt_startNode
+     * @return {*}
      */
     $x: function(xpath, opt_startNode)
     {
         var doc = (opt_startNode && opt_startNode.ownerDocument) || inspectedWindow.document;
         var result = doc.evaluate(xpath, opt_startNode || doc, null, XPathResult.ANY_TYPE, null);
         switch (result.resultType) {
         case XPathResult.NUMBER_TYPE:
             return result.numberValue;
         case XPathResult.STRING_TYPE:
             return result.stringValue;
         case XPathResult.BOOLEAN_TYPE:
             return result.booleanValue;
         default:
             var nodes = [];
             var node;
             while (node = result.iterateNext())
                 push(nodes, node);
             return nodes;
         }
     },
 
+    /**
+     * @return {*}
+     */
     dir: function(var_args)
     {
         return inspectedWindow.console.dir.apply(inspectedWindow.console, arguments)
     },
 
+    /**
+     * @return {*}
+     */
     dirxml: function(var_args)
     {
         return inspectedWindow.console.dirxml.apply(inspectedWindow.console, arguments)
     },
 
+    /**
+     * @return {!Array.<string>}
+     */
     keys: function(object)
     {
         return Object.keys(object);
     },
 
+    /**
+     * @return {!Array.<*>}
+     */
     values: function(object)
     {
         var result = [];
         for (var key in object)
             push(result, object[key]);
         return result;
     },
 
+    /**
+     * @return {*}
+     */
     profile: function(opt_title)
     {
         return inspectedWindow.console.profile.apply(inspectedWindow.console, arguments)
     },
 
+    /**
+     * @return {*}
+     */
     profileEnd: function(opt_title)
     {
         return inspectedWindow.console.profileEnd.apply(inspectedWindow.console, arguments)
     },
 
     /**
-     * @param {Object} object
-     * @param {Array.<string>|string=} opt_types
+     * @param {!Object} object
+     * @param {!Array.<string>|string=} opt_types
      */
     monitorEvents: function(object, opt_types)
     {
         if (!object || !object.addEventListener || !object.removeEventListener)
             return;
         var types = this._normalizeEventTypes(opt_types);
         for (var i = 0; i < types.length; ++i) {
             object.removeEventListener(types[i], this._logEvent, false);
             object.addEventListener(types[i], this._logEvent, false);
         }
     },
 
     /**
-     * @param {Object} object
-     * @param {Array.<string>|string=} opt_types
+     * @param {!Object} object
+     * @param {!Array.<string>|string=} opt_types
      */
     unmonitorEvents: function(object, opt_types)
     {
         if (!object || !object.addEventListener || !object.removeEventListener)
             return;
         var types = this._normalizeEventTypes(opt_types);
         for (var i = 0; i < types.length; ++i)
             object.removeEventListener(types[i], this._logEvent, false);
     },
 
@@ skipping 25 matching lines @@
         var remoteObject = injectedScript._wrapObject(string, "")
         InjectedScriptHost.inspect(remoteObject, hints);
     },
 
     clear: function()
     {
         InjectedScriptHost.clearConsoleMessages();
     },
 
     /**
-     * @param {Node} node
-     * @return {{type: string, listener: function(), useCapture: boolean, remove: function()}|undefined}
+     * @param {!Node} node
+     * @return {!{type: string, listener: function(), useCapture: boolean, remove: function()}|undefined}
      */
     getEventListeners: function(node)
     {
         var result = nullifyObjectProto(InjectedScriptHost.getEventListeners(node));
         if (!result)
             return result;
         /** @this {{type: string, listener: function(), useCapture: boolean}} */
         var removeFunc = function()
         {
             node.removeEventListener(this.type, this.listener, this.useCapture);
@@ skipping 35 matching lines @@
 
     /**
      * @param {number} num
      */
     _inspectedObject: function(num)
     {
         return InjectedScriptHost.inspectedObject(num);
     },
 
     /**
-     * @param {Array.<string>|string=} types
-     * @return {Array.<string>}
+     * @param {!Array.<string>|string=} types
+     * @return {!Array.<string>}
      */
     _normalizeEventTypes: function(types)
     {
         if (typeof types === "undefined")
             types = ["mouse", "key", "touch", "control", "load", "unload", "abort", "error", "select", "change", "submit", "reset", "focus", "blur", "resize", "scroll", "search", "devicemotion", "deviceorientation"];
         else if (typeof types === "string")
             types = [types];
 
         var result = [];
         for (var i = 0; i < types.length; ++i) {
             if (types[i] === "mouse")
                 push(result, "mousedown", "mouseup", "click", "dblclick", "mousemove", "mouseover", "mouseout", "mousewheel");
             else if (types[i] === "key")
                 push(result, "keydown", "keyup", "keypress", "textInput");
             else if (types[i] === "touch")
                 push(result, "touchstart", "touchmove", "touchend", "touchcancel");
             else if (types[i] === "control")
                 push(result, "resize", "scroll", "zoom", "focus", "blur", "select", "change", "submit", "reset");
             else
                 push(result, types[i]);
         }
         return result;
     },
 
     /**
-     * @param {Event} event
+     * @param {!Event} event
      */
     _logEvent: function(event)
     {
         inspectedWindow.console.log(event.type, event);
     }
 }
 
 injectedScript._commandLineAPIImpl = new CommandLineAPIImpl();
 return injectedScript;
 })