From 38fa6dd49fbb6b69ed197995d3d09af02c2db638 Mon Sep 17 00:00:00 2001 From: Mark Banner Date: Fri, 23 Aug 2024 08:55:49 +0000 Subject: [PATCH] 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 --- .../content/migration-wizard-constants.mjs | 10 ---------- .../migration/content/migration-wizard.mjs | 16 ++++++++++++++-- browser/components/uitour/UITour-lib.js | 4 ++-- remote/cdp/CDPConnection.sys.mjs | 2 +- remote/cdp/domains/content/Runtime.sys.mjs | 4 ++-- remote/marionette/cookie.sys.mjs | 4 ++-- remote/marionette/driver.sys.mjs | 16 ++++++++-------- remote/marionette/json.sys.mjs | 6 +++++- remote/marionette/message.sys.mjs | 2 +- remote/marionette/reftest.sys.mjs | 2 +- remote/marionette/server.sys.mjs | 2 +- remote/marionette/web-reference.sys.mjs | 4 ++-- remote/shared/Browser.sys.mjs | 2 +- remote/shared/DOM.sys.mjs | 4 ++-- remote/shared/messagehandler/Errors.sys.mjs | 4 ++-- remote/shared/webdriver/Capabilities.sys.mjs | 8 ++++---- remote/shared/webdriver/Errors.sys.mjs | 4 ++-- remote/shared/webdriver/Session.sys.mjs | 2 +- .../shared/webdriver/UserPromptHandler.sys.mjs | 6 +++--- remote/webdriver-bidi/WebDriverBiDi.sys.mjs | 4 ++-- .../WebDriverBiDiConnection.sys.mjs | 2 +- ...test_ext_contentscript_triggeringPrincipal.js | 6 +++--- 22 files changed, 60 insertions(+), 54 deletions(-) diff --git a/browser/components/migration/content/migration-wizard-constants.mjs b/browser/components/migration/content/migration-wizard-constants.mjs index 18673fc5b66f..81d51ecd0a0f 100644 --- a/browser/components/migration/content/migration-wizard-constants.mjs +++ b/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} */ 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} */ 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} */ 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} */ 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} */ EXTENSIONS_IMPORT_RESULT: Object.freeze({ NOT_IMPORTED: "0", diff --git a/browser/components/migration/content/migration-wizard.mjs b/browser/components/migration/content/migration-wizard.mjs index 22b7d818e8bb..3f3a5215aada 100644 --- a/browser/components/migration/content/migration-wizard.mjs +++ b/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} state.progress + * @param {Record} 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} state.progress + * @param {Record} state.progress * An object whose keys match one of DISPLAYED_FILE_RESOURCE_TYPES. * * Any resource type not included in state.progress will be hidden. diff --git a/browser/components/uitour/UITour-lib.js b/browser/components/uitour/UITour-lib.js index a83ec9520057..abf19e252753 100644 --- a/browser/components/uitour/UITour-lib.js +++ b/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} [numDevicesByType] - A count of devices + * @property {Record} [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 `_. * The value is a :js:func:`Mozilla.UITour.Configuration.AccountService` * - * @typedef {Object} Mozilla.UITour.Configuration.AccountServices + * @typedef {Record} Mozilla.UITour.Configuration.AccountServices * @since 71 */ diff --git a/remote/cdp/CDPConnection.sys.mjs b/remote/cdp/CDPConnection.sys.mjs index 78638899a9d4..093aeda944a7 100644 --- a/remote/cdp/CDPConnection.sys.mjs +++ b/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} + * @returns {Record} * Object with the domain ("Browser") and command ("getVersion") * as properties. */ diff --git a/remote/cdp/domains/content/Runtime.sys.mjs b/remote/cdp/domains/content/Runtime.sys.mjs index 44c36914d46e..02e9baf18f65 100644 --- a/remote/cdp/domains/content/Runtime.sys.mjs +++ b/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} + * @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} + * @returns {RemoteObject & { exeptionDetails?: ExceptionDetails }} * The evaluation result, and optionally exception details. */ evaluate(options = {}) { diff --git a/remote/marionette/cookie.sys.mjs b/remote/marionette/cookie.sys.mjs index e6388db3eb33..16d9530bed10 100644 --- a/remote/marionette/cookie.sys.mjs +++ b/remote/marionette/cookie.sys.mjs @@ -26,7 +26,7 @@ export const cookie = { /** * @name Cookie * - * @returns {Object} + * @returns {Record} */ /** @@ -36,7 +36,7 @@ export const cookie = { * will produce the errors expected by WebDriver if the input is * not valid. * - * @param {Object} json + * @param {Record} 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``, diff --git a/remote/marionette/driver.sys.mjs b/remote/marionette/driver.sys.mjs index 91810b3a08a0..c48bc618d608 100644 --- a/remote/marionette/driver.sys.mjs +++ b/remote/marionette/driver.sys.mjs @@ -396,7 +396,7 @@ GeckoDriver.prototype.registerBrowser = function (browserElement) { * Create a new WebDriver session. * * @param {object} cmd - * @param {Object=} cmd.parameters + * @param {Record=} 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} + * @returns {Record} * 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} + * @returns {Record} * 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} cmd.parameters + * @param {Record} 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} + * @returns {Record} * 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} + * @returns {Record} * Window rect and window state. * * @throws {NoSuchWindowError} @@ -2704,7 +2704,7 @@ GeckoDriver.prototype.minimizeWindow = async function () { * * Not supported on Fennec. * - * @returns {Object} + * @returns {Record} * 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} + * @returns {Record} * 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 diff --git a/remote/marionette/json.sys.mjs b/remote/marionette/json.sys.mjs index bae1b99cdd8c..49c5ab6836bd 100644 --- a/remote/marionette/json.sys.mjs +++ b/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, object>>} + * @returns {{ + * seenNodeIds: Map, + * 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 diff --git a/remote/marionette/message.sys.mjs b/remote/marionette/message.sys.mjs index d8b5dd60f9e8..97bde6ccb768 100644 --- a/remote/marionette/message.sys.mjs +++ b/remote/marionette/message.sys.mjs @@ -128,7 +128,7 @@ Message.Origin = { * Message ID unique identifying this message. * @param {string} name * Command name. - * @param {Object} params + * @param {Record} params * Command parameters. */ export class Command extends Message { diff --git a/remote/marionette/reftest.sys.mjs b/remote/marionette/reftest.sys.mjs index 23140fd49f9c..0affac65bd14 100644 --- a/remote/marionette/reftest.sys.mjs +++ b/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} urlCount + * @param {Record} 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. diff --git a/remote/marionette/server.sys.mjs b/remote/marionette/server.sys.mjs index 36e7a9d63982..fb05328295c6 100644 --- a/remote/marionette/server.sys.mjs +++ b/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} payload + * @param {Record} payload * The payload to ship. */ sendRaw(payload) { diff --git a/remote/marionette/web-reference.sys.mjs b/remote/marionette/web-reference.sys.mjs index 07823a64990c..25b63bb96516 100644 --- a/remote/marionette/web-reference.sys.mjs +++ b/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} json + * @param {Record} 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 obj is a {@link WebReference} reference. * - * @param {Object} obj + * @param {Record} obj * Object that represents a {@link WebReference}. * * @returns {boolean} diff --git a/remote/shared/Browser.sys.mjs b/remote/shared/Browser.sys.mjs index c8bff1f55a27..bb1bfaeeed60 100644 --- a/remote/shared/Browser.sys.mjs +++ b/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} + * @returns {Record} * 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 diff --git a/remote/shared/DOM.sys.mjs b/remote/shared/DOM.sys.mjs index 51c92981839a..d90fffee69a8 100644 --- a/remote/shared/DOM.sys.mjs +++ b/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 strategy. * - * @param {Object} container + * @param {Record} 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} + * @returns {Record} * X- and Y coordinates. * * @throws TypeError diff --git a/remote/shared/messagehandler/Errors.sys.mjs b/remote/shared/messagehandler/Errors.sys.mjs index 69c65acd09d5..74be5e47f78f 100644 --- a/remote/shared/messagehandler/Errors.sys.mjs +++ b/remote/shared/messagehandler/Errors.sys.mjs @@ -26,7 +26,7 @@ class MessageHandlerError extends RemoteError { } /** - * @returns {Object} + * @returns {Record} * 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} json + * @param {Record} json * Error object. * * @returns {Error} diff --git a/remote/shared/webdriver/Capabilities.sys.mjs b/remote/shared/webdriver/Capabilities.sys.mjs index 8d5d58722190..d4ce0f69f3a6 100644 --- a/remote/shared/webdriver/Capabilities.sys.mjs +++ b/remote/shared/webdriver/Capabilities.sys.mjs @@ -253,7 +253,7 @@ export class Proxy { } /** - * @param {Object} json + * @param {Record} json * JSON Object to unmarshal. * * @throws {InvalidArgumentError} @@ -398,7 +398,7 @@ export class Proxy { } /** - * @returns {Object} + * @returns {Record} * JSON serialisation of proxy object. */ toJSON() { @@ -510,7 +510,7 @@ export class Capabilities extends Map { /** * JSON serialization of capabilities object. * - * @returns {Object} + * @returns {Record} */ toJSON() { let marshalled = marshal(this); @@ -529,7 +529,7 @@ export class Capabilities extends Map { /** * Unmarshal a JSON object representation of WebDriver capabilities. * - * @param {Object=} json + * @param {Record=} json * WebDriver capabilities. * @param {boolean=} isBidi * Flag indicating that it is a WebDriver BiDi session. Defaults to false. diff --git a/remote/shared/webdriver/Errors.sys.mjs b/remote/shared/webdriver/Errors.sys.mjs index 70601310754b..ddc9a8b0cc0e 100644 --- a/remote/shared/webdriver/Errors.sys.mjs +++ b/remote/shared/webdriver/Errors.sys.mjs @@ -208,7 +208,7 @@ class WebDriverError extends RemoteError { } /** - * @returns {Object} + * @returns {Record} * 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} json + * @param {Record} json * Error object. * * @returns {Error} diff --git a/remote/shared/webdriver/Session.sys.mjs b/remote/shared/webdriver/Session.sys.mjs index 1fa208a3efda..1c1aadca5557 100644 --- a/remote/shared/webdriver/Session.sys.mjs +++ b/remote/shared/webdriver/Session.sys.mjs @@ -191,7 +191,7 @@ export class WebDriverSession { * {"capabilities": {"acceptInsecureCerts": true}} * * - * @param {Object=} capabilities + * @param {Record=} capabilities * JSON Object containing any of the recognized capabilities listed * above. * @param {SessionConfigurationFlags} flags diff --git a/remote/shared/webdriver/UserPromptHandler.sys.mjs b/remote/shared/webdriver/UserPromptHandler.sys.mjs index 92c50cff7e65..bbe5baa8b575 100644 --- a/remote/shared/webdriver/UserPromptHandler.sys.mjs +++ b/remote/shared/webdriver/UserPromptHandler.sys.mjs @@ -111,7 +111,7 @@ export class PromptHandlerConfiguration { /** * JSON serialization of the prompt handler configuration object. * - * @returns {Object} json + * @returns {Record} 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} json + * @param {Record} json * JSON Object to unmarshal. * * @throws {InvalidArgumentError} @@ -274,7 +274,7 @@ export class UserPromptHandler { /** * JSON serialization of the user prompt handler object. * - * @returns {Object} json + * @returns {Record} json * * @see https://w3c.github.io/webdriver/#dfn-serialize-the-user-prompt-handler */ diff --git a/remote/webdriver-bidi/WebDriverBiDi.sys.mjs b/remote/webdriver-bidi/WebDriverBiDi.sys.mjs index bc5e6f3ac85a..639c5f608008 100644 --- a/remote/webdriver-bidi/WebDriverBiDi.sys.mjs +++ b/remote/webdriver-bidi/WebDriverBiDi.sys.mjs @@ -101,7 +101,7 @@ export class WebDriverBiDi { /** * Create a new WebDriver session. * - * @param {Object=} capabilities + * @param {Record=} 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} + * @returns {Record} * Object containing the current session ID, and all its capabilities. * * @throws {SessionNotCreatedError} diff --git a/remote/webdriver-bidi/WebDriverBiDiConnection.sys.mjs b/remote/webdriver-bidi/WebDriverBiDiConnection.sys.mjs index d6fb5c22fa27..5e1bfef80ceb 100644 --- a/remote/webdriver-bidi/WebDriverBiDiConnection.sys.mjs +++ b/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} + * @returns {Record} * Object with the module ("session") and command ("subscribe") * as properties. */ diff --git a/toolkit/components/extensions/test/xpcshell/test_ext_contentscript_triggeringPrincipal.js b/toolkit/components/extensions/test/xpcshell/test_ext_contentscript_triggeringPrincipal.js index ce7f29314237..92afbcca230b 100644 --- a/toolkit/components/extensions/test/xpcshell/test_ext_contentscript_triggeringPrincipal.js +++ b/toolkit/components/extensions/test/xpcshell/test_ext_contentscript_triggeringPrincipal.js @@ -815,12 +815,12 @@ function getOriginBase(origURL) { * * @param {Array} tests * A list of tests, as understood by {@see getElementData}. - * @param {Object} expectedSources + * @param {Record} 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} [forbiddenSources = {}] + * @param {Record} [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} urlsPromise * A promise which resolves to an object containing expected and * forbidden URL sets, as returned by {@see computeBaseURLs}. - * @param {Object} origins + * @param {Record} 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