Bug 1870226 - Use typescript Record definitions rather than Object<> generic forms for jsdoc. r=zombie,webdriver-reviewers,omc-reviewers,aminomancer,kpatenio

Differential Revision: https://phabricator.services.mozilla.com/D219511

browser/components/migration/content/migration-wizard-constants.mjs

@@ -12,8 +12,6 @@ export const MigrationWizardConstants = Object.freeze({
    * A mapping of a page identification string to the IDs used by the
    * various wizard pages. These are used by MigrationWizard.setState
    * to set the current page.
-   *
-   * @type {Object<string, string>}
    */
   PAGES: Object.freeze({
     LOADING: "loading",
@@ -28,8 +26,6 @@ export const MigrationWizardConstants = Object.freeze({
   /**
    * A mapping of a progress value string. These are used by
    * MigrationWizard.#onShowingProgress to update the UI accordingly.
-   *
-   * @type {Object<string, number>}
    */
   PROGRESS_VALUE: Object.freeze({
     LOADING: 1,
@@ -43,8 +39,6 @@ export const MigrationWizardConstants = Object.freeze({
    * the associated resource group in the wizard via a data-resource-type
    * attribute. The keys are used to set which items should be shown and
    * in what state in #onShowingProgress.
-   *
-   * @type {Object<string, string>}
    */
   DISPLAYED_RESOURCE_TYPES: Object.freeze({
     // The DISPLAYED_RESOURCE_TYPES should have their keys match those
@@ -84,8 +78,6 @@ export const MigrationWizardConstants = Object.freeze({
    * the associated resource group in the wizard via a data-resource-type
    * attribute. The keys are for resource types that are only ever shown
    * for profile resets.
-   *
-   * @type {Object<string, string>}
    */
   PROFILE_RESET_ONLY_RESOURCE_TYPES: Object.freeze({
     COOKIES: "COOKIES",
@@ -112,8 +104,6 @@ export const MigrationWizardConstants = Object.freeze({
    * "3" if all extensions were matched after import. "2" if only some
    * extensions were matched. "1" if none were matched, and "0" if extensions
    * weren't selected for import.
-   *
-   * @type {Object<string, string>}
    */
   EXTENSIONS_IMPORT_RESULT: Object.freeze({
     NOT_IMPORTED: "0",

browser/components/migration/content/migration-wizard.mjs

@@ -712,6 +712,12 @@ export class MigrationWizard extends HTMLElement {
    *  This will only be shown if linkURL is also not-empty.
    */
 
+  /**
+   * @typedef {
+   *   keyof typeof MigrationWizardConstants.DISPLAYED_RESOURCE_TYPES
+   * } DISPLAYED_RESOURCE_TYPES_KEYS
+   */
+
   /**
    * Called when showing the progress / success page of the wizard.
    *
@@ -720,7 +726,7 @@ export class MigrationWizard extends HTMLElement {
    *   used:
    * @param {string} state.key
    *   The key of the migrator being used.
-   * @param {Object<string, ProgressState>} state.progress
+   * @param {Record<DISPLAYED_RESOURCE_TYPES_KEYS, ProgressState>} state.progress
    *   An object whose keys match one of DISPLAYED_RESOURCE_TYPES.
    *
    *   Any resource type not included in state.progress will be hidden.
@@ -886,6 +892,12 @@ export class MigrationWizard extends HTMLElement {
     }
   }
 
+  /**
+   * @typedef {
+   *   keyof typeof MigrationWizardConstants.DISPLAYED_FILE_RESOURCE_TYPES
+   * } DISPLAYED_FILE_RESOURCE_TYPES_KEYS
+   */
+
   /**
    * Called when showing the progress / success page of the wizard for
    * files.
@@ -895,7 +907,7 @@ export class MigrationWizard extends HTMLElement {
    *   used:
    * @param {string} state.title
    *   The string to display in the header.
-   * @param {Object<string, ProgressState>} state.progress
+   * @param {Record<DISPLAYED_FILE_RESOURCE_TYPES_KEYS, ProgressState>} state.progress
    *   An object whose keys match one of DISPLAYED_FILE_RESOURCE_TYPES.
    *
    *   Any resource type not included in state.progress will be hidden.

browser/components/uitour/UITour-lib.js

@@ -494,7 +494,7 @@ if (typeof Mozilla == "undefined") {
    *    no other properties will exist.
    * @property {number} [numOtherDevices] - Number of devices connected to this
    *    account, not counting this device.
-   * @property {Object<string, number>} [numDevicesByType] - A count of devices
+   * @property {Record<string, number>} [numDevicesByType] - A count of devices
    *    connected to the account by device 'type'. Valid values for type are
    *    defined by the FxA server but roughly correspond to form-factor with
    *    values like 'desktop', 'mobile', 'vr', etc.
@@ -514,7 +514,7 @@ if (typeof Mozilla == "undefined") {
    * `on our telemetry documentation site <https://docs.telemetry.mozilla.org/datasets/fxa_metrics/attribution.html#service-attribution>`_.
    * The value is a :js:func:`Mozilla.UITour.Configuration.AccountService`
    *
-   * @typedef {Object<string, Mozilla.UITour.Configuration.AccountService>} Mozilla.UITour.Configuration.AccountServices
+   * @typedef {Record<string, Mozilla.UITour.Configuration.AccountService>} Mozilla.UITour.Configuration.AccountServices
    * @since 71
    */
 

remote/cdp/CDPConnection.sys.mjs

@@ -276,7 +276,7 @@ export class CDPConnection extends WebSocketConnection {
  * @param {string} method
  *     Name of the method to split, e.g. "Browser.getVersion".
  *
- * @returns {Object<string, string>}
+ * @returns {Record<string, string>}
  *     Object with the domain ("Browser") and command ("getVersion")
  *     as properties.
  */

remote/cdp/domains/content/Runtime.sys.mjs

@@ -171,7 +171,7 @@ export class Runtime extends ContentProcessDomain {
    *     Whether the result is expected to be a JSON object
    *     which should be sent by value.
    *
-   * @returns {Object<RemoteObject, ExceptionDetails>}
+   * @returns {RemoteObject & { exeptionDetails?: ExceptionDetails }}
    */
   callFunctionOn(options = {}) {
     if (typeof options.functionDeclaration != "string") {
@@ -251,7 +251,7 @@ export class Runtime extends ContentProcessDomain {
    * @param {boolean=} options.userGesture [unsupported]
    *     Whether execution should be treated as initiated by user in the UI.
    *
-   * @returns {Object<RemoteObject, exceptionDetails>}
+   * @returns {RemoteObject & { exeptionDetails?: ExceptionDetails }}
    *     The evaluation result, and optionally exception details.
    */
   evaluate(options = {}) {

remote/marionette/cookie.sys.mjs

@@ -26,7 +26,7 @@ export const cookie = {
 /**
  * @name Cookie
  *
- * @returns {Object<string, (number|boolean|string)>}
+ * @returns {Record<string, (number|boolean|string)>}
  */
 
 /**
@@ -36,7 +36,7 @@ export const cookie = {
  * will produce the errors expected by WebDriver if the input is
  * not valid.
  *
- * @param {Object<string, (number | boolean | string)>} json
+ * @param {Record<string, (number | boolean | string)>} json
  *     Cookie to be deserialised. ``name`` and ``value`` are required
  *     fields which must be strings.  The ``path`` and ``domain`` fields
  *     are optional, but must be a string if provided.  The ``secure``,

remote/marionette/driver.sys.mjs

@@ -396,7 +396,7 @@ GeckoDriver.prototype.registerBrowser = function (browserElement) {
  * Create a new WebDriver session.
  *
  * @param {object} cmd
- * @param {Object<string, *>=} cmd.parameters
+ * @param {Record<string, *>=} cmd.parameters
  *     JSON Object containing any of the recognised capabilities as listed
  *     on the `WebDriverSession` class.
  *
@@ -1099,7 +1099,7 @@ GeckoDriver.prototype.getWindowHandles = function () {
  * window outerWidth and outerHeight values, which include scroll bars,
  * title bars, etc.
  *
- * @returns {Object<string, number>}
+ * @returns {Record<string, number>}
  *     Object with |x| and |y| coordinates, and |width| and |height|
  *     of browser window.
  *
@@ -1135,7 +1135,7 @@ GeckoDriver.prototype.getWindowRect = async function () {
  * @param {number} cmd.parameters.height
  *     Height to resize the window to.
  *
- * @returns {Object<string, number>}
+ * @returns {Record<string, number>}
  *     Object with `x` and `y` coordinates and `width` and `height`
  *     dimensions.
  *
@@ -1442,7 +1442,7 @@ GeckoDriver.prototype.getTimeouts = function () {
  * Set timeout for page loading, searching, and scripts.
  *
  * @param {object} cmd
- * @param {Object<string, number>} cmd.parameters
+ * @param {Record<string, number>} cmd.parameters
  *     Dictionary of timeout types and their new value, where all timeout
  *     types are optional.
  *
@@ -2324,7 +2324,7 @@ GeckoDriver.prototype.deleteCookie = async function (cmd) {
  *     new top-level browsing context should be a private window.
  *     Defaults to false.
  *
- * @returns {Object<string, string>}
+ * @returns {Record<string, string>}
  *     Handle and type of the new browsing context.
  *
  * @throws {NoSuchWindowError}
@@ -2652,7 +2652,7 @@ GeckoDriver.prototype.setScreenOrientation = async function (cmd) {
  *
  * Not supported on Fennec.
  *
- * @returns {Object<string, number>}
+ * @returns {Record<string, number>}
  *     Window rect and window state.
  *
  * @throws {NoSuchWindowError}
@@ -2704,7 +2704,7 @@ GeckoDriver.prototype.minimizeWindow = async function () {
  *
  * Not supported on Fennec.
  *
- * @returns {Object<string, number>}
+ * @returns {Record<string, number>}
  *     Window rect.
  *
  * @throws {NoSuchWindowError}
@@ -3016,7 +3016,7 @@ GeckoDriver.prototype.acceptConnections = async function (cmd) {
  *     Optional flag to indicate that the application has to
  *     be restarted in safe mode.
  *
- * @returns {Object<string,boolean>}
+ * @returns {Record<string,boolean>}
  *     Dictionary containing information that explains the shutdown reason.
  *     The value for `cause` contains the shutdown kind like "shutdown" or
  *     "restart", while `forced` will indicate if it was a normal or forced

remote/marionette/json.sys.mjs

@@ -98,7 +98,11 @@ function cloneObject(value, seen, cloneAlgorithm) {
  * @param {NodeCache} nodeCache
  *     Node cache that holds already seen WebElement and ShadowRoot references.
  *
- * @returns {Object<Map<BrowsingContext, Array<string>, object>>}
+ * @returns {{
+ *   seenNodeIds: Map<BrowsingContext, string[]>,
+ *   serializedValue: any,
+ *   hasSerializedWindows: boolean
+ * }}
  *     Object that contains a list of browsing contexts each with a list of
  *     shared ids for collected elements and shadow root nodes, and second the
  *     same object as provided by `value` with the WebDriver classic supported

remote/marionette/message.sys.mjs

@@ -128,7 +128,7 @@ Message.Origin = {
  *     Message ID unique identifying this message.
  * @param {string} name
  *     Command name.
- * @param {Object<string, ?>} params
+ * @param {Record<string, ?>} params
  *     Command parameters.
  */
 export class Command extends Message {

remote/marionette/reftest.sys.mjs

@@ -79,7 +79,7 @@ reftest.Runner = class {
    * This will open a non-browser window in which the tests will
    * be loaded, and set up various caches for the reftest run.
    *
-   * @param {Object<number>} urlCount
+   * @param {Record<string, number>} urlCount
    *     Object holding a map of URL: number of times the URL
    *     will be opened during the reftest run, where that's
    *     greater than 1.

remote/marionette/server.sys.mjs

@@ -447,7 +447,7 @@ export class TCPConnection {
    * Send the given payload over the debugger transport socket to the
    * connected client.
    *
-   * @param {Object<string, ?>} payload
+   * @param {Record<string, ?>} payload
    *     The payload to ship.
    */
   sendRaw(payload) {

remote/marionette/web-reference.sys.mjs

@@ -96,7 +96,7 @@ export class WebReference {
    * Unmarshals a JSON Object to one of {@link ShadowRoot}, {@link WebElement},
    * {@link WebFrame}, or {@link WebWindow}.
    *
-   * @param {Object<string, string>} json
+   * @param {Record<string, string>} json
    *     Web reference, which is supposed to be a JSON Object
    *     where the key is one of the {@link WebReference} concrete
    *     classes' UUID identifiers.
@@ -141,7 +141,7 @@ export class WebReference {
   /**
    * Checks if <var>obj<var> is a {@link WebReference} reference.
    *
-   * @param {Object<string, string>} obj
+   * @param {Record<string, string>} obj
    *     Object that represents a {@link WebReference}.
    *
    * @returns {boolean}

remote/shared/Browser.sys.mjs

@@ -30,7 +30,7 @@ ChromeUtils.defineESModuleGetters(lazy, {
  * @param {boolean=} isWindowless
  *     Optional flag to indicate that the browser was started in windowless mode.
  *
- * @returns {Object<string,boolean>}
+ * @returns {Record<string, boolean>}
  *     Dictionary containing information that explains the shutdown reason.
  *     The value for `cause` contains the shutdown kind like "shutdown" or
  *     "restart", while `forced` will indicate if it was a normal or forced

remote/shared/DOM.sys.mjs

@@ -69,7 +69,7 @@ dom.Strategy = {
  * See the {@link dom.Strategy} enum for a full list of supported
  * search strategies that can be passed to <var>strategy</var>.
  *
- * @param {Object<string, WindowProxy>} container
+ * @param {Record<string, WindowProxy>} container
  *     Window object.
  * @param {string} strategy
  *     Search strategy whereby to locate the element(s).
@@ -754,7 +754,7 @@ dom.isEditable = function (el) {
  *     Vertical offset relative to target's top-left corner.  Defaults to
  *     the centre of the target's bounding box.
  *
- * @returns {Object<string, number>}
+ * @returns {Record<string, number>}
  *     X- and Y coordinates.
  *
  * @throws TypeError

remote/shared/messagehandler/Errors.sys.mjs

@@ -26,7 +26,7 @@ class MessageHandlerError extends RemoteError {
   }
 
   /**
-   * @returns {Object<string, string>}
+   * @returns {Record<string, string>}
    *     JSON serialisation of error prototype.
    */
   toJSON() {
@@ -41,7 +41,7 @@ class MessageHandlerError extends RemoteError {
    * Unmarshals a JSON error representation to the appropriate MessageHandler
    * error type.
    *
-   * @param {Object<string, string>} json
+   * @param {Record<string, string>} json
    *     Error object.
    *
    * @returns {Error}

remote/shared/webdriver/Capabilities.sys.mjs

@@ -253,7 +253,7 @@ export class Proxy {
   }
 
   /**
-   * @param {Object<string, ?>} json
+   * @param {Record<string, ?>} json
    *     JSON Object to unmarshal.
    *
    * @throws {InvalidArgumentError}
@@ -398,7 +398,7 @@ export class Proxy {
   }
 
   /**
-   * @returns {Object<string, (number | string)>}
+   * @returns {Record<string, (number | string)>}
    *     JSON serialisation of proxy object.
    */
   toJSON() {
@@ -510,7 +510,7 @@ export class Capabilities extends Map {
   /**
    * JSON serialization of capabilities object.
    *
-   * @returns {Object<string, ?>}
+   * @returns {Record<string, ?>}
    */
   toJSON() {
     let marshalled = marshal(this);
@@ -529,7 +529,7 @@ export class Capabilities extends Map {
   /**
    * Unmarshal a JSON object representation of WebDriver capabilities.
    *
-   * @param {Object<string, *>=} json
+   * @param {Record<string, *>=} json
    *     WebDriver capabilities.
    * @param {boolean=} isBidi
    *     Flag indicating that it is a WebDriver BiDi session. Defaults to false.

remote/shared/webdriver/Errors.sys.mjs

@@ -208,7 +208,7 @@ class WebDriverError extends RemoteError {
   }
 
   /**
-   * @returns {Object<string, string>}
+   * @returns {Record<string, string>}
    *     JSON serialisation of error prototype.
    */
   toJSON() {
@@ -230,7 +230,7 @@ class WebDriverError extends RemoteError {
    * Unmarshals a JSON error representation to the appropriate Marionette
    * error type.
    *
-   * @param {Object<string, string>} json
+   * @param {Record<string, string>} json
    *     Error object.
    *
    * @returns {Error}

remote/shared/webdriver/Session.sys.mjs

@@ -191,7 +191,7 @@ export class WebDriverSession {
    *     {"capabilities": {"acceptInsecureCerts": true}}
    * </code></pre>
    *
-   * @param {Object<string, *>=} capabilities
+   * @param {Record<string, *>=} capabilities
    *     JSON Object containing any of the recognized capabilities listed
    *     above.
    * @param {SessionConfigurationFlags} flags

remote/shared/webdriver/UserPromptHandler.sys.mjs

@@ -111,7 +111,7 @@ export class PromptHandlerConfiguration {
   /**
    * JSON serialization of the prompt handler configuration object.
    *
-   * @returns {Object<string, ?>} json
+   * @returns {Record<string, ?>} json
    *
    * @see https://w3c.github.io/webdriver/#dfn-serialize-a-prompt-handler-configuration
    */
@@ -149,7 +149,7 @@ export class UserPromptHandler {
   /**
    * Unmarshal a JSON object representation of the unhandledPromptBehavior capability.
    *
-   * @param {Object<string, ?>} json
+   * @param {Record<string, ?>} json
    *     JSON Object to unmarshal.
    *
    * @throws {InvalidArgumentError}
@@ -274,7 +274,7 @@ export class UserPromptHandler {
   /**
    * JSON serialization of the user prompt handler object.
    *
-   * @returns {Object<string, ?>} json
+   * @returns {Record<string, ?>} json
    *
    * @see https://w3c.github.io/webdriver/#dfn-serialize-the-user-prompt-handler
    */

remote/webdriver-bidi/WebDriverBiDi.sys.mjs

@@ -101,7 +101,7 @@ export class WebDriverBiDi {
   /**
    * Create a new WebDriver session.
    *
-   * @param {Object<string, *>=} capabilities
+   * @param {Record<string, *>=} capabilities
    *     JSON Object containing any of the recognised capabilities as listed
    *     on the `WebDriverSession` class.
    * @param {Set} flags
@@ -110,7 +110,7 @@ export class WebDriverBiDi {
    *     Optional connection that is not yet associated with a WebDriver
    *     session, and has to be associated with the new WebDriver session.
    *
-   * @returns {Object<string, Capabilities>}
+   * @returns {Record<string, Capabilities>}
    *     Object containing the current session ID, and all its capabilities.
    *
    * @throws {SessionNotCreatedError}

remote/webdriver-bidi/WebDriverBiDiConnection.sys.mjs

@@ -267,7 +267,7 @@ export class WebDriverBiDiConnection extends WebSocketConnection {
  * @param {string} method
  *     Name of the method to split, e.g. "session.subscribe".
  *
- * @returns {Object<string, string>}
+ * @returns {Record<string, string>}
  *     Object with the module ("session") and command ("subscribe")
  *     as properties.
  */

toolkit/components/extensions/test/xpcshell/test_ext_contentscript_triggeringPrincipal.js

@@ -815,12 +815,12 @@ function getOriginBase(origURL) {
  *
  * @param {Array<ElementTestCase>} tests
  *        A list of tests, as understood by {@see getElementData}.
- * @param {Object<string, object>} expectedSources
+ * @param {Record<string, object>} expectedSources
  *        A set of sources for which each of the above tests is expected
  *        to generate one request, if each of the properties in the
  *        value object matches the value of the same property in the
  *        test object.
- * @param {Object<string, object>} [forbiddenSources = {}]
+ * @param {Record<string, object>} [forbiddenSources = {}]
  *        A set of sources for which requests should never be sent. Any
  *        matching requests from these sources will cause the test to
  *        fail.
@@ -939,7 +939,7 @@ function computeExpectedForbiddenURLs(
  * @param {Promise<object>} urlsPromise
  *        A promise which resolves to an object containing expected and
  *        forbidden URL sets, as returned by {@see computeBaseURLs}.
- * @param {Object<string, string>} origins
+ * @param {Record<string, string>} origins
  *        A mapping of origin parameters as they appear in URL query
  *        strings to the origin strings returned by corresponding
  *        principals. These values are used to test requests against