commit 2542790f53de7406f117a15653f25c66a810d1bd parent 93b92e2659bab89629620161d016b6e18a9ef923 Author: Mark Banner <standard8@mozilla.com> Date: Mon, 10 Nov 2025 18:32:42 +0000 Bug 1998787 - Automatic fixes for enabling ESLint jsdoc/tag-line rule everywhere. r=frontend-codestyle-reviewers,mtigley,perftest-reviewers,nchevobbe,home-newtab-reviewers,Gijs,mconley,sparky Differential Revision: https://phabricator.services.mozilla.com/D271745 Diffstat:
659 files changed, 2213 insertions(+), 72 deletions(-)
diff --git a/accessible/tests/browser/Common.sys.mjs b/accessible/tests/browser/Common.sys.mjs @@ -130,6 +130,7 @@ export const CommonUtils = { * on the accessible, but it catches exceptions which might occur if the * accessible has died or was constructed from a pseudoelement * like ::details-content. + * * @param {nsIAccessible} accessible accessible * @return {String?} DOMNode id if available */ diff --git a/accessible/tests/browser/caching_granularity/head.js b/accessible/tests/browser/caching_granularity/head.js @@ -24,6 +24,7 @@ loadScripts( /** * Verifies that the given attribute is cached on the given acc. Retries until * a timeout via untilCacheOk. + * * @param {nsIAccessible} accessible the accessible where the attribute to query * should be cached * @param {String} attribute the attribute to query in the cache @@ -43,6 +44,7 @@ async function verifyAttributeCached(accessible, attribute) { /** * Verifies that the given attribute is cached on the given acc. Doesn't retry * until a timeout. + * * @param {nsIAccessible} accessible the accessible where the attribute to query * should be cached * @param {String} attribute the attribute to query in the cache @@ -66,6 +68,7 @@ function verifyAttributeCachedNoRetry(accessible, attribute) { * accessibility service to activate those cache domains by running the provided * query function, which queries the attribute. Finally, verifies that the * attribute is present in the cache. + * * @param {nsIAccessible} accessible the accessible where the attribute to * query should be cached * @param {String} attribute the attribute to query in the cache @@ -95,6 +98,7 @@ async function testAttributeCachePresence(accessible, attribute, queryCb) { * Verify that the given attribute is properly cached, taking into account * platform considerations which may affect what is testable. Ideally, test * attribute absence and presence, but only presence may be possible. + * * @param {nsIAccessible} accessible the accessible where the attribute to * query should be cached * @param {String} attribute the attribute to query in the cache diff --git a/accessible/tests/browser/e10s/browser_caching_name.js b/accessible/tests/browser/e10s/browser_caching_name.js @@ -371,6 +371,7 @@ const markupTests = [ * results in a reorder or text inserted event - wait for it. If accessible * becomes defunct, update its reference using the one that is attached to one * of the above events. + * * @param {Object} browser current "tabbrowser" element * @param {Object} target { acc, id } structure that contains an * accessible and its content element @@ -399,6 +400,7 @@ async function testAttrRule(browser, target, rule, expected) { * element before proceeding to the next name test. If element removal results * in a reorder event - wait for it. If accessible becomes defunct, update its * reference using the one that is attached to a possible reorder event. + * * @param {Object} browser current "tabbrowser" element * @param {Object} target { acc, id } structure that contains an * accessible and its content element @@ -427,6 +429,7 @@ async function testElmRule(browser, target, rule, expected) { * and wait for a reorder event before proceeding to the next name test. If * accessible becomes defunct, update its reference using the one that is * attached to a reorder event. + * * @param {Object} browser current "tabbrowser" element * @param {Object} target { acc, id } structure that contains an * accessible and its content element @@ -455,6 +458,7 @@ async function testSubtreeRule(browser, target, rule, expected) { /** * Iterate over a list of rules and test accessible names for each one of the * rules. + * * @param {Object} browser current "tabbrowser" element * @param {Object} target { acc, id } structure that contains an * accessible and its content element diff --git a/accessible/tests/browser/relations/head.js b/accessible/tests/browser/relations/head.js @@ -90,6 +90,7 @@ async function testCachedRelation( /** * Asynchronously set or remove content element's reflected elements attribute * (in content process if e10s is enabled). + * * @param {Object} browser current "tabbrowser" element * @param {String} id content element id * @param {String} attr attribute name diff --git a/accessible/tests/browser/shared-head.js b/accessible/tests/browser/shared-head.js @@ -143,6 +143,7 @@ let Logger = { /** * Asynchronously set or remove content element's attribute (in content process * if e10s is enabled). + * * @param {Object} browser current "tabbrowser" element * @param {String} id content element id * @param {String} attr attribute name @@ -175,6 +176,7 @@ function invokeSetAttribute(browser, id, attr, value = null) { * Asynchronously set or remove content element's style (in content process if * e10s is enabled, or in fission process if fission is enabled and a fission * frame is present). + * * @param {Object} browser current "tabbrowser" element * @param {String} id content element id * @param {String} aStyle style property name @@ -207,6 +209,7 @@ function invokeSetStyle(browser, id, style, value) { * Asynchronously set focus on a content element (in content process if e10s is * enabled, or in fission process if fission is enabled and a fission frame is * present). + * * @param {Object} browser current "tabbrowser" element * @param {String} id content element id * @return {Promise} promise indicating that focus is set @@ -226,13 +229,13 @@ function invokeFocus(browser, id) { /** * Get DPR for a specific content window. + * * @param browser * Browser for which we want its content window's DPR reported. * * @return {Promise} * Promise with the value that resolves to the devicePixelRatio of the * content window of a given browser. - * */ function getContentDPR(browser) { return invokeContentTask(browser, [], () => content.window.devicePixelRatio); @@ -242,6 +245,7 @@ function getContentDPR(browser) { * Asynchronously perform a task in content (in content process if e10s is * enabled, or in fission process if fission is enabled and a fission frame is * present). + * * @param {Object} browser current "tabbrowser" element * @param {Array} args arguments for the content task * @param {Function} task content task function @@ -270,6 +274,7 @@ function invokeContentTask(browser, args, task) { /** * Compare process ID's between the top level content process and possible * remote/local iframe proccess. + * * @param {Object} browser * Top level browser object for a tab. * @param {Boolean} isRemote @@ -293,6 +298,7 @@ async function comparePIDs(browser, isRemote) { /** * Load a list of scripts into the test + * * @param {Array} scripts a list of scripts to load */ function loadScripts(...scripts) { @@ -307,6 +313,7 @@ function loadScripts(...scripts) { /** * Load a list of scripts into target's content. + * * @param {Object} target * target for loading scripts into * @param {Array} scripts @@ -410,6 +417,7 @@ function wrapWithIFrame(doc, options = {}) { /** * Takes an HTML snippet or HTML doc url and returns an encoded URI for a full * document with the snippet or the URL as a source for the IFRAME. + * * @param {String} doc * a markup snippet or url. * @param {Object} options (see options in addAccessibleTask). @@ -676,6 +684,7 @@ function accessibleTask(doc, task, options = {}) { /** * A wrapper around browser test add_task that triggers an accessible test task * as a new browser test task with given document, data URL or markup snippet. + * * @param {String} doc * URL (relative to current directory) or data URL or markup snippet * that is used to test content with @@ -786,6 +795,7 @@ function addAccessibleTask(doc, task, options = {}) { /** * Check if an accessible object has a defunct test. + * * @param {nsIAccessible} accessible object to test defunct state for * @return {Boolean} flag indicating defunct state */ @@ -807,6 +817,7 @@ function isDefunct(accessible) { /** * Get the DOM tag name for a given accessible. + * * @param {nsIAccessible} accessible accessible * @return {String?} tag name of associated DOM node, or null. */ @@ -821,6 +832,7 @@ function getAccessibleTagName(acc) { /** * Traverses the accessible tree starting from a given accessible as a root and * looks for an accessible that matches based on its DOMNode id. + * * @param {nsIAccessible} accessible root accessible * @param {String} id id to look up accessible for * @param {Array?} interfaces the interface or an array interfaces diff --git a/accessible/tests/mochitest/common.js b/accessible/tests/mochitest/common.js @@ -871,6 +871,7 @@ function getTextFromClipboard() { * Obtain DOMNode id from an accessible. This simply queries the .id property * on the accessible, but it catches exceptions which might occur if the * accessible has died. + * * @param {nsIAccessible} accessible accessible * @return {String?} DOMNode id if available */ @@ -957,6 +958,7 @@ function prettyName(aIdentifier) { /** * Shorten a long string if it exceeds MAX_TRIM_LENGTH. + * * @param aString the string to shorten. * @returns the shortened string. */ diff --git a/accessible/tests/mochitest/promisified-events.js b/accessible/tests/mochitest/promisified-events.js @@ -70,6 +70,7 @@ const EventsLogger = { /** * Describe an event in string format. + * * @param {nsIAccessibleEvent} event event to strigify */ function eventToString(event) { @@ -135,6 +136,7 @@ function matchEvent(event, matchCriteria) { * A helper function that returns a promise that resolves when an accessible * event of the given type with the given target (defined by its id or * accessible) is observed. + * * @param {Number} eventType expected accessible event * type * @param {String|nsIAccessible|Function} matchCriteria expected content @@ -218,6 +220,7 @@ class UnexpectedEvents { /** * A helper function that waits for a sequence of accessible events in * specified order. + * * @param {Array} events a list of events to wait (same format as * waitForEvent arguments) * @param {String} message Message to prepend to logging. @@ -322,6 +325,7 @@ function waitForStateChange(id, state, isEnabled, isExtra = false) { * before setting focus to it. This simulates behavio with the keyboard when * tabbing to the element. This does explicitly what synthFocus did implicitly. * This should be called only if you really want this behavior. + * * @param {string} id The element ID to focus */ function selectAllTextAndFocus(id) { diff --git a/browser/actors/ContentSearchParent.sys.mjs b/browser/actors/ContentSearchParent.sys.mjs @@ -168,6 +168,7 @@ export let ContentSearch = { /** * Observes changes in prefs tracked by UrlbarPrefs. + * * @param {string} pref * The name of the pref, relative to `browser.urlbar.` if the pref is * in that branch. diff --git a/browser/actors/ContextMenuChild.sys.mjs b/browser/actors/ContextMenuChild.sys.mjs @@ -311,6 +311,7 @@ export class ContextMenuChild extends JSWindowActorChild { * Returns the event target of the context menu, using a locally stored * reference if possible. If not, and aMessage.objects is defined, * aMessage.objects[aKey] is returned. Otherwise null. + * * @param {Object} aMessage Message with a objects property * @param {String} aKey Key for the target on aMessage.objects * @return {Object} Context menu target diff --git a/browser/actors/EncryptedMediaChild.sys.mjs b/browser/actors/EncryptedMediaChild.sys.mjs @@ -29,6 +29,7 @@ class GlobalCaptureListener { /** * Handle changes in shared data that may alter the capture state. + * * @param event a notification that sharedData has changed. If this includes * changes to screen or window sharing state then we'll update the capture * state. @@ -45,6 +46,7 @@ class GlobalCaptureListener { /** * Updates the capture state and notifies the state to observers if the * state has changed since last update, or if forced. + * * @param forceNotify if true then the capture state will be sent to * observers even if it didn't change since the last update. */ diff --git a/browser/actors/PageStyleParent.sys.mjs b/browser/actors/PageStyleParent.sys.mjs @@ -50,6 +50,7 @@ export class PageStyleParent extends JSWindowActorParent { /** * Add/append styleSheets to the _pageStyleSheets weakmap. + * * @param newSheetData * The stylesheet data, including new stylesheets to add, * and the preferred stylesheet set for this document. diff --git a/browser/actors/PluginChild.sys.mjs b/browser/actors/PluginChild.sys.mjs @@ -20,6 +20,7 @@ export class PluginChild extends JSWindowActorChild { /** * Determines whether or not the crashed plugin is contained within current * full screen DOM element. + * * @param fullScreenElement (DOM element) * The DOM element that is currently full screen, or null. * @param domElement @@ -31,6 +32,7 @@ export class PluginChild extends JSWindowActorChild { isWithinFullScreenElement(fullScreenElement, domElement) { /** * Traverses down iframes until it find a non-iframe full screen DOM element. + * * @param fullScreenIframe * Target iframe to begin searching from. * @returns DOM element diff --git a/browser/actors/ScreenshotsComponentChild.sys.mjs b/browser/actors/ScreenshotsComponentChild.sys.mjs @@ -176,6 +176,7 @@ export class ScreenshotsComponentChild extends JSWindowActorChild { /** * Send a request to copy the screenshots + * * @param {Object} region The region dimensions of the screenshot to be copied */ requestCopyScreenshot(region) { @@ -186,6 +187,7 @@ export class ScreenshotsComponentChild extends JSWindowActorChild { /** * Send a request to download the screenshots + * * @param {Object} region The region dimensions of the screenshot to be downloaded */ requestDownloadScreenshot(region) { diff --git a/browser/actors/SearchSERPTelemetryChild.sys.mjs b/browser/actors/SearchSERPTelemetryChild.sys.mjs @@ -751,7 +751,6 @@ class SearchAdImpression { * count because the parent used `countChildren` completed the calculation in a * previous step. * - * * @param {HTMLAnchorElement} anchor * The anchor to be inspected. * @returns {object | null} diff --git a/browser/actors/WebRTCParent.sys.mjs b/browser/actors/WebRTCParent.sys.mjs @@ -826,6 +826,7 @@ function prompt(aActor, aBrowser, aRequest) { /** * Prepare the device selector for one kind of device. + * * @param {Object[]} devices - available devices of this kind. * @param {string} IDPrefix - indicating kind of device and so * associated UI elements. @@ -1469,6 +1470,7 @@ function getPromptMessageId( /** * Checks whether we have a microphone/camera in use by checking the activePerms map * or if we have an allow permission for a microphone/camera in sitePermissions + * * @param {Browser} browser - Browser to find all active and allowed microphone and camera devices for * @return true if one of the above conditions is met */ @@ -1522,6 +1524,7 @@ function removePrompt(aBrowser, aCallId) { /** * Clears temporary permission grants used for WebRTC device grace periods. + * * @param browser - Browser element to clear permissions for. * @param {boolean} clearCamera - Clear camera grants. * @param {boolean} clearMicrophone - Clear microphone grants. @@ -1581,6 +1584,7 @@ function persistGrantOrPromptPermission(principal, permissionName, remember) { /** * Clears any persisted PROMPT (aka Always Ask) permission. + * * @param principal - Principal to remove permission from. * @param {string} permissionName - name of permission. * @param browser - Browser element to clear permission for. @@ -1602,6 +1606,7 @@ function maybeClearAlwaysAsk(principal, permissionName, browser) { /** * Helper for lazily creating the webrtc-preview element. + * * @param {Document} chromeDoc - The chrome document to create the webrtc-preview element in. * @returns {HTMLElement} The webrtc-preview element which has been inserted into the DOM. */ diff --git a/browser/base/content/aboutTabCrashed.js b/browser/base/content/aboutTabCrashed.js @@ -144,7 +144,6 @@ var AboutTabCrashed = { * requestAutoSubmit (bool): * Whether or not we should ask the user to automatically * submit backlogged crash reports. - * */ onSetCrashReportAvailable(message) { let data = message.data; diff --git a/browser/base/content/browser-a11yUtils.js b/browser/base/content/browser-a11yUtils.js @@ -18,6 +18,7 @@ var A11yUtils = { * can thus hinder rather than help users if used incorrectly. * Please only use this after consultation with the Mozilla accessibility * team. + * * @param {object} [options] * @param {string} [options.id] The Fluent id of the message to announce. The * ftl file must already be included in browser.xhtml. This must be diff --git a/browser/base/content/browser-addons.js b/browser/base/content/browser-addons.js @@ -1910,6 +1910,7 @@ var BrowserAddonUI = { /** * Open about:addons page by given view id. + * * @param {String} aView * View id of page that will open. * e.g. "addons://discover/" diff --git a/browser/base/content/browser-fullScreenAndPointerLock.js b/browser/base/content/browser-fullScreenAndPointerLock.js @@ -129,6 +129,7 @@ var PointerlockFsWarning = { /** * Close the full screen or pointerlock warning. + * * @param {('fullscreen-warning'|'pointerlock-warning')} elementId - Id of the * warning element to close. If the id does not match the currently shown * warning this is a no-op. @@ -408,6 +409,7 @@ var FullScreen = { /** * Shifts the browser toolbar down when it is moused over on macOS in * fullscreen. + * * @param {number} shiftSize * A distance, in pixels, by which to shift the browser toolbar down. */ @@ -686,7 +688,6 @@ var FullScreen = { * If found, that ancestor actor and the browsing context for its child which * was in process are returned. Otherwise [request origin, null]. * - * * @param {JSWindowActorParent} aActor * The actor that called this function. * @param {bool} aUseCache diff --git a/browser/base/content/browser-pagestyle.js b/browser/base/content/browser-pagestyle.js @@ -79,6 +79,7 @@ var gPageStyleMenu = { /** * Send a message to all PageStyleParents by walking the BrowsingContext tree. + * * @param message * The string message to send to each PageStyleChild. * @param data @@ -103,6 +104,7 @@ var gPageStyleMenu = { /** * Switch the stylesheet of all documents in the current browser. + * * @param title The title of the stylesheet to switch to. */ switchStyleSheet(title) { diff --git a/browser/base/content/browser-places.js b/browser/base/content/browser-places.js @@ -462,6 +462,7 @@ var PlacesCommandHook = { /** * Adds a bookmark to the page targeted by a link. + * * @param url (string) * the address of the link target * @param title @@ -497,6 +498,7 @@ var PlacesCommandHook = { /** * Bookmarks the given tabs loaded in the current browser. + * * @param {Array} tabs * If no given tabs, bookmark all current tabs. */ @@ -533,6 +535,7 @@ var PlacesCommandHook = { /** * Opens the Places Organizer. + * * @param {String} item The item to select in the organizer window, * options are (case sensitive): * BookmarksMenu, BookmarksToolbar, UnfiledBookmarks, @@ -735,6 +738,7 @@ var BookmarksEventHandler = { * Left-click is handled in the onCommand function. * When items are middle-clicked (or clicked with modifier), open in tabs. * If the click came through a menu, close the menu. + * * @param aEvent * DOMEvent for the click * @param aView @@ -817,6 +821,7 @@ var BookmarksEventHandler = { * Handler for command event for an item in the bookmarks toolbar. * Menus and submenus from the folder buttons bubble up to this handler. * Opens the item. + * * @param aEvent * DOMEvent for the command */ @@ -905,6 +910,7 @@ var PlacesMenuDNDHandler = { /** * Called when the user enters the <menu> element during a drag. + * * @param event * The DragEnter event that spawned the opening. */ @@ -995,6 +1001,7 @@ var PlacesMenuDNDHandler = { /** * Determines if a XUL element represents a static container. + * * @returns true if the element is a container element (menu or *` menu-toolbarbutton), false otherwise. */ @@ -1013,6 +1020,7 @@ var PlacesMenuDNDHandler = { /** * Called when the user drags over the <menu> element. + * * @param event * The DragOver event. */ @@ -1030,6 +1038,7 @@ var PlacesMenuDNDHandler = { /** * Called when the user drops on the <menu> element. + * * @param event * The Drop event. */ @@ -1837,6 +1846,7 @@ var BookmarkingUI = { /** * Update the "Bookmark Page…" menuitems on the menubar, panels, context * menu and page actions. + * * @param {boolean} [forceReset] passed when we're destroyed and the label * should go back to the default (Bookmark Page), for MacOS. */ diff --git a/browser/base/content/browser-sitePermissionPanel.js b/browser/base/content/browser-sitePermissionPanel.js @@ -205,6 +205,7 @@ var gPermissionPanel = { /** * Shows the permission popup. + * * @param {Event} event - Event which caused the popup to show. */ openPopup(event) { @@ -980,6 +981,7 @@ var gPermissionPanel = { /** * Create a permission item for a WebRTC permission. May return null if there * already is a suitable permission item for this device type. + * * @param {Object} permission - Permission object. * @param {string} id - Permission ID without suffix. * @param {string} [key] - Secondary permission key. @@ -1138,6 +1140,7 @@ var gPermissionPanel = { * Returns an object containing two booleans: {camGrace, micGrace}, * whether permission grace periods are found for camera/microphone AND * persistent permissions do not exist for said permissions. + * * @param browser - Browser element to get permissions for. */ function hasMicCamGracePeriodsSolely(browser) { diff --git a/browser/base/content/browser-siteProtections.js b/browser/base/content/browser-siteProtections.js @@ -26,6 +26,7 @@ XPCOMUtils.defineLazyServiceGetter( class ProtectionCategory { /** * Creates a protection category. + * * @param {string} id - Identifier of the category. Used to query the category * UI elements in the DOM. * @param {Object} options - Category options. @@ -110,6 +111,7 @@ class ProtectionCategory { /** * Get the category item associated with this protection from the main * protections panel. + * * @returns {xul:toolbarbutton|undefined} - Item or undefined if the panel is * not yet initialized. */ @@ -126,6 +128,7 @@ class ProtectionCategory { /** * Defaults to enabled state. May be overridden by child classes. + * * @returns {boolean} - Whether the protection is set to block trackers. */ get blockingEnabled() { @@ -135,6 +138,7 @@ class ProtectionCategory { /** * Update the category item state in the main view of the protections panel. * Determines whether the category is set to block trackers. + * * @returns {boolean} - true if the state has been updated, false if the * protections popup has not been initialized yet. */ @@ -188,6 +192,7 @@ class ProtectionCategory { /** * Create a list of items, each representing a tracker. + * * @returns {Object} result - An object containing the results. * @returns {HTMLDivElement[]} result.items - Generated tracker items. May be * empty. @@ -217,6 +222,7 @@ class ProtectionCategory { /** * Return the number items blocked by this blocker. + * * @returns {Integer} count - The number of items blocked. */ async getBlockerCount() { @@ -226,6 +232,7 @@ class ProtectionCategory { /** * Create a DOM item representing a tracker. + * * @param {string} origin - Origin of the tracker. * @param {Array} actions - Array of actions from the content blocking log * associated with the tracking origin. @@ -277,6 +284,7 @@ class ProtectionCategory { /** * Create an indicator icon for marking origins that have been allowed by a * shim script. + * * @returns {HTMLImageElement} - Created element. */ _getShimAllowIndicator() { diff --git a/browser/base/content/browser-sync.js b/browser/base/content/browser-sync.js @@ -916,6 +916,7 @@ var gSync = { /** * Potential network call. Fetch the list of OAuth clients attached to the current Mozilla account. + * * @returns {Promise<boolean>} - Resolves to true if successful, false otherwise. */ async fetchListOfOAuthClients() { @@ -2421,6 +2422,7 @@ var gSync = { /** * Checks if the current list of attached clients to the Mozilla account * has a service associated with the passed in Id + * * @param {string} clientId * A known static Id from FxA that identifies the service it's associated with * @returns {boolean} diff --git a/browser/base/content/browser.js b/browser/base/content/browser.js @@ -1965,6 +1965,7 @@ var XULBrowserWindow = { /** * Encode bidirectional formatting characters. + * * @see https://url.spec.whatwg.org/#url-rendering-i18n * @see https://www.unicode.org/reports/tr9/#Directional_Formatting_Characters */ @@ -2381,6 +2382,7 @@ var XULBrowserWindow = { * Updates macOS platform code with the current URI and page title. * From there, we update the current NSUserActivity, enabling Handoff to other * Apple devices. + * * @param {Window} window * The window in which the navigation occurred. * @param {nsIURI} uri @@ -2412,6 +2414,7 @@ var XULBrowserWindow = { * identity panel. For browsers whose content does not have a principal, * this tries the precursor. If this is null, we should not override the * browser's currentURI. + * * @param {MozBrowser} browser * The browser that we need a URI to show the user in the * identity panel. @@ -4292,6 +4295,7 @@ class TabDialogBox { /** * Open a dialog on tab or content level. + * * @param {String} aURL - URL of the dialog to load in the tab box. * @param {Object} [aOptions] * @param {String} [aOptions.features] - Comma separated list of window diff --git a/browser/base/content/contentTheme.js b/browser/base/content/contentTheme.js @@ -147,6 +147,7 @@ /** * Handle theme updates from the LightweightThemeChild actor or due to * changes to the prefers-color-scheme media query. + * * @param {Object} event object containing the theme or query update. */ handleEvent(event) { @@ -164,6 +165,7 @@ /** * Set a CSS variable to a given value + * * @param {Element} elem The element where the CSS variable should be added. * @param {string} variableName The CSS variable to set. * @param {string} value The new value of the CSS variable. @@ -178,6 +180,7 @@ /** * Apply theme data to an element + * * @param {Object} themeData The theme data. */ _setProperties(themeData) { diff --git a/browser/base/content/nsContextMenu.sys.mjs b/browser/base/content/nsContextMenu.sys.mjs @@ -106,6 +106,7 @@ export class nsContextMenu { * A promise to retrieve the translations language pair * if the context menu was opened in a context relevant to * open the SelectTranslationsPanel. + * * @type {Promise<{sourceLanguage: string, targetLanguage: string}>} */ #translationsLangPairPromise; @@ -113,6 +114,7 @@ export class nsContextMenu { /** * The value of the `main-context-menu-new-feature-badge` l10n string. Fetched * lazily. + * * @type {string} */ #newFeatureBadgeL10nString; @@ -2399,9 +2401,9 @@ export class nsContextMenu { /** * Strips any known query params from the link URI. + * * @returns {nsIURI|null} - the stripped version of the URI, * or the original URI if we could not strip any query parameter. - * */ getStrippedLink(uri = this.linkURI) { if (!uri) { diff --git a/browser/base/content/test/contextMenu/browser_contextmenu.js b/browser/base/content/test/contextMenu/browser_contextmenu.js @@ -2616,6 +2616,7 @@ async function selectText(selector) { /** * Not all platforms support text recognition. + * * @returns {string[]} */ function getTextRecognitionItems() { diff --git a/browser/base/content/test/fullscreen/DOMFullscreenTestUtils.sys.mjs b/browser/base/content/test/fullscreen/DOMFullscreenTestUtils.sys.mjs @@ -60,6 +60,7 @@ export var DOMFullscreenTestUtils = { /** * Spawns content task in browser to enter / leave fullscreen + * * @param browser - Browser to use for JS fullscreen requests * @param {Boolean} fullscreenState - true to enter fullscreen, false to leave * @returns {Promise} - Resolves once fullscreen change is applied diff --git a/browser/base/content/test/general/browser_datachoices_notification.js b/browser/base/content/test/general/browser_datachoices_notification.js @@ -53,6 +53,7 @@ function promiseNextTick() { /** * Wait for a notification to be shown in a notification box. + * * @param {Object} aNotificationBox The notification box. * @return {Promise} Resolved when the notification is displayed. */ @@ -70,6 +71,7 @@ function promiseWaitForAlertActive(aNotificationBox) { /** * Wait for a notification to be closed. + * * @param {Object} aNotification The notification. * @return {Promise} Resolved when the notification is closed. */ diff --git a/browser/base/content/test/performance/browser_window_resize.js b/browser/base/content/test/performance/browser_window_resize.js @@ -42,6 +42,7 @@ async function toggleBookmarksToolbar(visible) { * Resizes a browser window to a particular width and height, and * waits for it to reach a "steady state" with respect to its overflowing * toolbars. + * * @param win (browser window) * The window to resize. * @param width (int) diff --git a/browser/base/content/test/permissions/browser_temporary_permissions_expiry.js b/browser/base/content/test/permissions/browser_temporary_permissions_expiry.js @@ -114,6 +114,7 @@ add_task(async function testTempPermissionRequestAfterExpiry() { /** * Test whether the identity UI shows the permission granted state. + * * @param {boolean} state - true = Shows permission granted, false otherwise. */ async function testIdentityPermissionGrantedState(state) { diff --git a/browser/base/content/test/plugins/head.js b/browser/base/content/test/plugins/head.js @@ -177,6 +177,7 @@ function promiseForNotificationBar(notificationID, browser) { /** * Reshow a notification and call a callback when it is reshown. + * * @param notification * The notification to reshow * @param callback diff --git a/browser/base/content/test/protectionsUI/browser_protectionsUI_cookie_banner.js b/browser/base/content/test/protectionsUI/browser_protectionsUI_cookie_banner.js @@ -32,6 +32,7 @@ const exampleRules = JSON.stringify([ /** * Determines whether the cookie banner section in the protections panel should * be visible with the given configuration. + * * @param {*} options - Configuration to test. * @param {Number} options.featureMode - nsICookieBannerService::Modes value for * normal browsing. @@ -66,6 +67,7 @@ function cookieBannerSectionIsVisible({ /** * Runs a visibility test of the cookie banner section in the protections panel. + * * @param {*} options - Test options. * @param {Window} options.win - Browser window to use for testing. It's * browsing mode should match the testPBM variable. @@ -220,6 +222,7 @@ add_task(async function test_section_visibility_pref() { /** * Test the state of the per-site exception switch in the cookie banner section * and whether a matching per-site exception is set. + * * @param {*} options * @param {Window} options.win - Chrome window to test exception for (selected * tab). @@ -318,6 +321,7 @@ function assertSwitchAndPrefState({ win, isPBM, expectedSwitchState }) { /** * Test the telemetry associated with the cookie banner toggle. To be called * after interacting with the toggle. + * * @param {*} options * @param {boolean|null} - Expected telemetry state matching the button state. * button on = true = cookieb_toggle_on event. Pass null to expect no event diff --git a/browser/base/content/test/protectionsUI/browser_protectionsUI_subview_shim.js b/browser/base/content/test/protectionsUI/browser_protectionsUI_subview_shim.js @@ -247,6 +247,7 @@ async function runTestForCategoryAndState(category, action) { /** * Test mixed allow/block/replace states for the tracking protection category. + * * @param {Object} options - States to test. * @param {boolean} options.block - Test tracker block state. * @param {boolean} options.allow - Test tracker allow state. diff --git a/browser/base/content/test/referrer/head.js b/browser/base/content/test/referrer/head.js @@ -72,6 +72,7 @@ var _referrerTests = [ /** * Returns the test object for a given test number. + * * @param aTestNumber The test number - 0, 1, 2, ... * @return The test object, or undefined if the number is out of range. */ @@ -98,6 +99,7 @@ function getRemovedReferrerTest(aTestNumber) { /** * Returns a brief summary of the test, for logging. + * * @param aTestNumber The test number - 0, 1, 2... * @return The test description. */ @@ -118,6 +120,7 @@ function getReferrerTestDescription(aTestNumber) { /** * Clicks the link. + * * @param aWindow The window to click the link in. * @param aLinkId The id of the link element. * @param aOptions The options for synthesizeMouseAtCenter. @@ -132,6 +135,7 @@ function clickTheLink(aWindow, aLinkId, aOptions) { /** * Extracts the referrer result from the target window. + * * @param aWindow The window where the referrer target has loaded. * @return {Promise} * @resolves When extacted, with the text of the (trimmed) referrer. @@ -144,6 +148,7 @@ function referrerResultExtracted(aWindow) { /** * Waits for browser delayed startup to finish. + * * @param aWindow The window to wait for. * @return {Promise} * @resolves When the window is loaded. @@ -161,6 +166,7 @@ function delayedStartupFinished(aWindow) { /** * Waits for some (any) tab to load. The caller triggers the load. + * * @param aWindow The window where to wait for a tab to load. * @return {Promise} * @resolves With the tab once it's loaded. @@ -171,6 +177,7 @@ function someTabLoaded() { /** * Waits for a new window to open and load. The caller triggers the open. + * * @return {Promise} * @resolves With the new window once it's open and loaded. */ @@ -182,6 +189,7 @@ function newWindowOpened() { /** * Opens the context menu. + * * @param aWindow The window to open the context menu in. * @param aLinkId The id of the link to open the context menu on. * @return {Promise} @@ -199,6 +207,7 @@ function contextMenuOpened(aWindow, aLinkId) { /** * Performs a context menu command. + * * @param aWindow The window with the already open context menu. * @param aMenu The menu popup to hide. * @param aItemId The id of the menu item to activate. @@ -211,6 +220,7 @@ function doContextMenuCommand(aWindow, aMenu, aItemId) { /** * Loads a single test case, i.e., a source url into gTestWindow. + * * @param aTestNumber The test case number - 0, 1, 2... * @return {Promise} * @resolves When the source url for this test case is loaded. @@ -245,6 +255,7 @@ function referrerTestCaseLoaded(aTestNumber, aParams) { /** * Checks the result of the referrer test, and moves on to the next test. + * * @param aTestNumber The test number - 0, 1, 2, ... * @param aNewWindow The new window where the referrer target opened, or null. * @param aNewTab The new tab where the referrer target opened, or null. @@ -289,6 +300,7 @@ function checkReferrerAndStartNextTest( /** * Fires up the complete referrer test. + * * @param aStartTestCase The callback to start a single test case, called with * the test number - 0, 1, 2... Needs to trigger the navigation from the source * page, and call checkReferrerAndStartNextTest() when the target is loaded. diff --git a/browser/base/content/test/sanitize/head.js b/browser/base/content/test/sanitize/head.js @@ -516,7 +516,6 @@ function promiseSanitizationComplete() { * "browser" by default * checkingDataSizes: boolean check if we should wait for the data sizes * to load - * */ function ClearHistoryDialogHelper({ mode = "browser", diff --git a/browser/base/content/test/sidebar/browser_sidebar_switcher.js b/browser/base/content/test/sidebar/browser_sidebar_switcher.js @@ -17,6 +17,7 @@ registerCleanupFunction(() => { /** * Helper function that opens a sidebar switcher panel popup menu + * * @returns Promise that resolves when the switcher panel popup is shown * without any action from a user/test */ @@ -35,6 +36,7 @@ function showSwitcherPanelPromise() { /** * Helper function that waits for a sidebar switcher panel's "popupshown" event + * * @returns Promise which resolves when the popup menu is opened */ async function waitForSwitcherPopupShown() { @@ -48,6 +50,7 @@ async function waitForSwitcherPopupShown() { * Helper function that sends a mouse click to a specific menu item or a key * event to a active menu item of the sidebar switcher menu popup. Provide a * querySelector parameter when a click behavior is needed. + * * @param {String} [querySelector=null] An HTML attribute of the menu item * to be clicked * @returns Promise that resolves when both the menu popup is hidden and @@ -70,6 +73,7 @@ function pickSwitcherMenuitem(querySelector = null) { /** * Helper function to test a key handling of sidebar menu popup items used to * access a specific sidebar + * * @param {String} key Event.key to open the switcher menu popup * @param {String} sidebarTitle Title of the sidebar that is to be activated * during the test (capitalized one word versions), diff --git a/browser/base/content/test/siteIdentity/browser_secure_transport_insecure_scheme.js b/browser/base/content/test/siteIdentity/browser_secure_transport_insecure_scheme.js @@ -16,6 +16,7 @@ const NOT_SECURE_LABEL = Services.prefs.getBoolPref( /** * Tests that the page info dialog "security" section labels a * connection as unencrypted and does not show certificate. + * * @param {string} uri - URI of the page to test with. */ async function testPageInfoNotEncrypted(uri) { diff --git a/browser/base/content/test/tabPrompts/browser_confirmFolderUpload.js b/browser/base/content/test/tabPrompts/browser_confirmFolderUpload.js @@ -9,6 +9,7 @@ const { PromptTestUtils } = ChromeUtils.importESModule( /** * Create a temporary test directory that will be cleaned up on test shutdown. + * * @returns {String} - absolute directory path. */ function getTestDirectory() { @@ -49,6 +50,7 @@ add_setup(async function () { /** * Create a file input, select a folder and wait for the upload confirmation * prompt to open. + * * @param {boolean} confirmUpload - Whether to accept (true) or cancel the * prompt (false). * @returns {Promise} - Resolves once the prompt has been closed. diff --git a/browser/base/content/test/tabPrompts/browser_promptFocus.js b/browser/base/content/test/tabPrompts/browser_promptFocus.js @@ -104,6 +104,7 @@ add_task(async function test_tabdialogbox_tab_switch_focus() { /** * Tests that an alert prompt has focus on the default element. + * * @param {CommonDialog} prompt - Prompt to test focus for. * @param {number} index - Index of the prompt to log. */ diff --git a/browser/base/content/test/webrtc/browser_devices_get_user_media_camera_preview.js b/browser/base/content/test/webrtc/browser_devices_get_user_media_camera_preview.js @@ -11,6 +11,7 @@ const TEST_PAGE = TEST_ROOT + "get_user_media.html"; /** * Run a preview test with the given options. + * * @param {Object} options * @param {boolean} options.requestCamera - Whether to request camera * @param {boolean} options.requestMicrophone - Whether to request microphone diff --git a/browser/base/content/test/webrtc/browser_devices_get_user_media_screen_tab_close.js b/browser/base/content/test/webrtc/browser_devices_get_user_media_screen_tab_close.js @@ -11,6 +11,7 @@ const TEST_PAGE = TEST_ROOT + "get_user_media.html"; /** * Tests that the given tab is the currently selected tab. + * * @param {Element} aTab - Tab to test. */ function testSelected(aTab) { diff --git a/browser/base/content/test/webrtc/get_user_media.html b/browser/base/content/test/webrtc/get_user_media.html @@ -30,6 +30,7 @@ var gAudioEvents = []; /** * Queue a getUserMedia request to be triggered by a button click. * The button click needs to be handled by the caller. + * * @param {boolean} aAudio - Whether to request audio. * @param {boolean} aVideo - Whether to request video. * @param {number} aShare - The type of screen sharing. diff --git a/browser/base/content/test/webrtc/head.js b/browser/base/content/test/webrtc/head.js @@ -667,6 +667,7 @@ async function getBrowsingContextsAndFrameIdsForSubFrames( /** * Test helper for getUserMedia calls. + * * @param {boolean} aRequestAudio - Whether to request audio * @param {boolean} aRequestVideo - Whether to request video * @param {string} aFrameId - The ID of the frame @@ -934,6 +935,7 @@ function checkDeviceSelectors(aExpectedTypes, aWindow = window) { /** * Tests the siteIdentity icons, the permission panel and the global indicator * UI state. + * * @param {Object} aExpected - Expected state for the current tab. * @param {window} [aWin] - Top level chrome window to test state of. * @param {Object} [aExpectedGlobal] - Expected state for all tabs. diff --git a/browser/components/BrowserContentHandler.sys.mjs b/browser/components/BrowserContentHandler.sys.mjs @@ -107,6 +107,7 @@ const OVERRIDE_NEW_MSTONE = 2; const OVERRIDE_NEW_BUILD_ID = 3; /** * Determines whether a home page override is needed. + * * @param {boolean} [updateMilestones=true] * True if we should update the milestone prefs after comparing those prefs * with the current platform version and build ID. @@ -186,6 +187,7 @@ function needHomepageOverride(updateMilestones = true) { /** * Gets the override page for the first run after the application has been * updated. + * * @param update * The nsIUpdate for the update that has been applied. * @param defaultOverridePage @@ -832,6 +834,7 @@ nsBrowserContentHandler.prototype = { * or equal to the maxVersion set by the experiment, we'll try to use * the experiment override URL instead of the default or the * update-provided URL. Additional policy checks are done in + * * @see getPostUpdateOverridePage */ const nimbusOverrideUrl = Services.urlFormatter.formatURLPref( diff --git a/browser/components/aboutlogins/AboutLoginsChild.sys.mjs b/browser/components/aboutlogins/AboutLoginsChild.sys.mjs @@ -118,6 +118,7 @@ export class AboutLoginsChild extends JSWindowActorChild { /** * Shows the Primary Password prompt if enabled, or the * OS auth dialog otherwise. + * * @param resolve Callback that is called with result of authentication. * @param messageId The string ID that corresponds to a string stored in aboutLogins.ftl. * This string will be displayed only when the OS auth dialog is used. diff --git a/browser/components/aboutlogins/LoginBreaches.sys.mjs b/browser/components/aboutlogins/LoginBreaches.sys.mjs @@ -127,6 +127,7 @@ export const LoginBreaches = { /** * Return information about logins using passwords that were potentially in a * breach. + * * @see the caveats in the documentation for `getPotentialBreachesByLoginGUID`. * * @param {nsILoginInfo[]} logins to check the passwords of. diff --git a/browser/components/aboutlogins/content/aboutLoginsUtils.mjs b/browser/components/aboutlogins/content/aboutLoginsUtils.mjs @@ -7,6 +7,7 @@ export const CONCEALED_PASSWORD_TEXT = " ".repeat(8); /** * Dispatches a custom event to the AboutLoginsChild.sys.mjs script which * will record the event. + * * @param {object} event.method The telemety event method * @param {object} event.object The telemety event object * @param {object} event.value [optional] The telemety event value @@ -63,6 +64,7 @@ export function promptForPrimaryPassword(messageId, reason) { /** * Initializes a dialog based on a template using shadow dom. + * * @param {HTMLElement} element The element to attach the shadow dom to. * @param {string} templateSelector The selector of the template to be used. * @returns {object} The shadow dom that is attached. diff --git a/browser/components/aboutlogins/content/components/login-item.mjs b/browser/components/aboutlogins/content/components/login-item.mjs @@ -667,6 +667,7 @@ export default class LoginItem extends HTMLElement { /** * Helper to show the "Discard changes" confirmation dialog and delay the * received event after confirmation. + * * @param {object} event The event to be delayed. * @param {object} login The login to be shown on confirmation. */ @@ -691,6 +692,7 @@ export default class LoginItem extends HTMLElement { /** * Shows a confirmation dialog. + * * @param {string} type The type of confirmation dialog to display. * @param {boolean} onConfirm Optional, the function to execute when the confirm button is clicked. */ diff --git a/browser/components/aboutlogins/tests/browser/head.js b/browser/components/aboutlogins/tests/browser/head.js @@ -200,6 +200,7 @@ add_setup(async function setup_head() { /** * Waits for the primary password prompt and performs an action. + * * @param {string} action Set to "authenticate" to log in or "cancel" to * close the dialog without logging in. */ diff --git a/browser/components/aboutlogins/tests/chrome/aboutlogins_common.js b/browser/components/aboutlogins/tests/chrome/aboutlogins_common.js @@ -5,6 +5,7 @@ /** * A helper to await on while waiting for an asynchronous rendering of a Custom * Element. + * * @returns {Promise} */ function asyncElementRendered() { @@ -13,6 +14,7 @@ function asyncElementRendered() { /** * Import the templates from the real page to avoid duplication in the tests. + * * @param {HTMLIFrameElement} templateFrame - Frame to copy the resources from * @param {HTMLElement} destinationEl - Where to append the copied resources */ diff --git a/browser/components/asrouter/modules/ASRouter.sys.mjs b/browser/components/asrouter/modules/ASRouter.sys.mjs @@ -856,6 +856,7 @@ export class _ASRouter { /** * Check all provided groups are enabled. + * * @param groups Set of groups to verify * @returns bool */ @@ -867,6 +868,7 @@ export class _ASRouter { /** * Verify that the provider block the message through the `exclude` field + * * @param message Message to verify * @returns bool */ @@ -2114,6 +2116,7 @@ export class _ASRouter { /** * Edit the ASRouter state directly. For use by the ASRouter devtools. * Requires browser.newtabpage.activity-stream.asrouter.devtoolsEnabled + * * @param {string} key Key of the property to edit, one of: * | "groupImpressions" * | "messageImpressions" @@ -2196,6 +2199,7 @@ export class _ASRouter { * It forces the browser attribution to be set to something specified in asrouter admin * tools, and reloads the providers in order to get messages that are dependant on this * attribution data (see Return to AMO flow in bug 1475354 for example). Note - OSX and Windows only + * * @param {data} Object an object containing the attribtion data that came from asrouter admin page */ async forceAttribution(data) { @@ -2307,6 +2311,7 @@ export class _ASRouter { /** * Fire a trigger, look for a matching message, and route it to the * appropriate message handler/messaging surface. + * * @param {object} trigger * @param {string} trigger.id the name of the trigger, e.g. "openURL" * @param {object} [trigger.param] an object with host, url, type, etc. keys diff --git a/browser/components/asrouter/modules/ASRouterStorage.sys.mjs b/browser/components/asrouter/modules/ASRouterStorage.sys.mjs @@ -131,6 +131,7 @@ export class ASRouterStorage { /** * Gets all of the message impression data + * * @returns {object|null} All multiprofile message impressions or null if error occurs */ async getSharedMessageImpressions() { @@ -173,6 +174,7 @@ export class ASRouterStorage { /** * Gets the message blocklist + * * @returns {Array|null} The message blocklist, or null if error occurred */ async getSharedMessageBlocklist() { @@ -202,6 +204,7 @@ export class ASRouterStorage { /** * Set the message impressions for a given message ID + * * @param {string} messageId - The message ID to set the impressions for * @param {Array|null} impressions - The new value of "impressions" (an array of * impression data or an emtpy array, or null to delete) @@ -274,6 +277,7 @@ export class ASRouterStorage { * Adds a message ID to the blocklist and removes impressions * for that message ID from the impressions table when isBlocked is true * and deletes message ID from the blocklist when isBlocked is false + * * @param {string} messageId - The message ID to set the blocked status for * @param {boolean} [isBlocked=true] - If the message should be blocked (true) or unblocked (false) * @returns {boolean} Success status diff --git a/browser/components/asrouter/modules/ASRouterTargeting.sys.mjs b/browser/components/asrouter/modules/ASRouterTargeting.sys.mjs @@ -237,6 +237,7 @@ const jexlEvaluationCache = new Map(); /** * CachedTargetingGetter + * * @param property {string} Name of the method * @param options {any=} Options passed to the method * @param updateInterval {number?} Update interval for query. Defaults to FRECENT_SITES_UPDATE_INTERVAL @@ -1125,6 +1126,7 @@ const TargetingGetters = { /** * The distribution id, if any. + * * @return {string} */ get distributionId() { @@ -1135,6 +1137,7 @@ const TargetingGetters = { /** * Where the Firefox View button is shown, if at all. + * * @return {string} container of the button if it is shown in the toolbar/overflow menu * @return {string} `null` if the button has been removed */ @@ -1171,6 +1174,7 @@ const TargetingGetters = { /** * Has the user ever used the Migration Wizard to migrate bookmarks? + * * @return {boolean} `true` if bookmark migration has occurred. */ get hasMigratedBookmarks() { @@ -1180,6 +1184,7 @@ const TargetingGetters = { /** * Has the user ever used the Migration Wizard to migrate passwords from * a CSV file? + * * @return {boolean} `true` if CSV passwords have been imported via the * migration wizard. */ @@ -1189,6 +1194,7 @@ const TargetingGetters = { /** * Has the user ever used the Migration Wizard to migrate history? + * * @return {boolean} `true` if history migration has occurred. */ get hasMigratedHistory() { @@ -1197,6 +1203,7 @@ const TargetingGetters = { /** * Has the user ever used the Migration Wizard to migrate passwords? + * * @return {boolean} `true` if password migration has occurred. */ get hasMigratedPasswords() { @@ -1208,6 +1215,7 @@ const TargetingGetters = { * wizard in about:welcome by having * "browser.migrate.content-modal.about-welcome-behavior" be equal to * "embedded". + * * @return {boolean} `true` if the embedded migration wizard is enabled. */ get useEmbeddedMigrationWizard() { @@ -1217,6 +1225,7 @@ const TargetingGetters = { /** * Returns the version number of the New Tab built-in addon being used * by the build. + * * @return {string} */ get newtabAddonVersion() { @@ -1225,6 +1234,7 @@ const TargetingGetters = { /** * Whether the user installed Firefox via the RTAMO flow. + * * @return {boolean} `true` when RTAMO has been used to download Firefox, * `false` otherwise. */ @@ -1239,6 +1249,7 @@ const TargetingGetters = { /** * Whether the user installed via the device migration flow. + * * @return {boolean} `true` when the link to download the browser was part * of guidance for device migration. `false` otherwise. */ @@ -1251,6 +1262,7 @@ const TargetingGetters = { /** * Whether the user opted into a special message action represented by an * installer attribution campaign and this choice still needs to be honored. + * * @return {string} A special message action to be executed on first-run. For * example, `"SET_DEFAULT_BROWSER"` when the user selected to set as default * via the install marketing page and set default has not yet been @@ -1263,6 +1275,7 @@ const TargetingGetters = { * The values of the height and width available to the browser to display * web content. The available height and width are each calculated taking * into account the presence of menu bars, docks, and other similar OS elements + * * @returns {Object} resolution The resolution object containing width and height * @returns {number} resolution.width The available width of the primary monitor * @returns {number} resolution.height The available height of the primary monitor diff --git a/browser/components/asrouter/modules/ASRouterTriggerListeners.sys.mjs b/browser/components/asrouter/modules/ASRouterTriggerListeners.sys.mjs @@ -322,6 +322,7 @@ export const ASRouterTriggerListeners = new Map([ /** * _updateVisits - Record visit timestamps for websites that match `this._hosts` and only * if it's been more than FEW_MINUTES since the last visit. + * * @param {string} host - Location host of current selected tab * @returns {boolean} - If the new visit has been recorded */ diff --git a/browser/components/asrouter/modules/CFRPageActions.sys.mjs b/browser/components/asrouter/modules/CFRPageActions.sys.mjs @@ -943,6 +943,7 @@ export const CFRPageActions = { /** * Fetch the URL to the latest add-on xpi so the recommendation can download it. + * * @param id The add-on ID * @return A string for the URL that was fetched */ @@ -966,6 +967,7 @@ export const CFRPageActions = { /** * Force a recommendation to be shown. Should only happen via the Admin page. + * * @param browser The browser for the recommendation * @param recommendation The recommendation to show * @param dispatchCFRAction A function to dispatch resulting actions to @@ -1003,6 +1005,7 @@ export const CFRPageActions = { /** * Add a recommendation specific to the given browser and host. + * * @param browser The browser for the recommendation * @param host The host for the recommendation * @param recommendation The recommendation to show diff --git a/browser/components/asrouter/modules/FeatureCallout.sys.mjs b/browser/components/asrouter/modules/FeatureCallout.sys.mjs @@ -672,6 +672,7 @@ export class FeatureCallout { * Return the first visible anchor element for the current screen. Screens can * specify multiple anchors in an array, and the first one that is visible * will be used. If none are visible, return null. + * * @returns {Anchor|null} */ _getAnchor() { @@ -1169,6 +1170,7 @@ export class FeatureCallout { /** * Horizontally align a top/bottom-positioned callout according to the * passed position. + * * @param {String} position one of... * - "center": for use with top/bottom. arrow is in the center, and the * center of the callout aligns with the parent center. @@ -1621,6 +1623,7 @@ export class FeatureCallout { /** * Emit an event to the broker, if one is present. + * * @param {String} name * @param {any} data */ @@ -1749,6 +1752,7 @@ export class FeatureCallout { * provided, try requesting one from ASRouter. The message content is stored * in this.config, which is returned by AWGetFeatureConfig. The aboutwelcome * bundle will use that function to get the content when it executes. + * * @param {Object} [message] ASRouter message. Omit to request a new one. * @param {Number} [screenIndex] Index of the screen to render. * @returns {Promise<boolean>} true if a message is loaded, false if not. @@ -1823,6 +1827,7 @@ export class FeatureCallout { /** * Request a message from ASRouter, targeting the `browser` and `page` values * passed to the constructor. + * * @returns {Promise<Object>} the requested message. */ async _loadConfig() { @@ -1840,6 +1845,7 @@ export class FeatureCallout { /** * Try to render the callout in the current document. + * * @returns {Promise<Boolean>} whether the callout was rendered. */ async _renderCallout() { @@ -1860,6 +1866,7 @@ export class FeatureCallout { /** * For each member of the screen's page_event_listeners array, add a listener. + * * @param {Array<PageEventListenerConfig>} listeners * * @typedef {Object} PageEventListenerConfig @@ -1908,6 +1915,7 @@ export class FeatureCallout { /** * Perform an action in response to a page event. + * * @param {PageEventListenerAction} action * @param {Event} event Triggering event */ @@ -1974,6 +1982,7 @@ export class FeatureCallout { /** * For a given element, calculate a unique string that identifies it. + * * @param {Element} target Element to calculate the selector for * @returns {String} Computed event target selector, e.g. `button#next` */ @@ -2019,6 +2028,7 @@ export class FeatureCallout { * button is found, focus the first input element. If no affirmative action is * found, focus the first button, which is probably the dismiss button. A * custom selector can also be provided to focus a specific element. + * * @param {AutoFocusOptions} [options] * @returns {Element|null} The element to focus when the callout is shown. */ @@ -2055,6 +2065,7 @@ export class FeatureCallout { /** * Show a feature callout message, either by requesting one from ASRouter or * by showing a message passed as an argument. + * * @param {Object} [message] optional message to show instead of requesting one * @returns {Promise<Boolean>} true if a message was shown */ @@ -2172,6 +2183,7 @@ export class FeatureCallout { /** * Combine the preset and custom themes into a single object and store it. + * * @param {FeatureCalloutTheme} theme */ _initTheme(theme) { @@ -2222,6 +2234,7 @@ export class FeatureCallout { /** * Set or remove a CSS custom property on the feature callout container + * * @param {String} name Name of the CSS custom property * @param {String|void} [value] Value of the property, or omit to remove it */ diff --git a/browser/components/asrouter/modules/FeatureCalloutBroker.sys.mjs b/browser/components/asrouter/modules/FeatureCalloutBroker.sys.mjs @@ -42,6 +42,7 @@ export class _FeatureCalloutBroker { * Make a new FeatureCallout instance and store it in the callout map. Also * add an unload listener to the window to clean up the callout when the * window is unloaded. + * * @param {FeatureCalloutOptions} config */ makeFeatureCallout(config) { @@ -73,6 +74,7 @@ export class _FeatureCalloutBroker { /** * Show a feature callout message. For use by ASRouter, to be invoked when a * trigger has matched to a feature_callout message. + * * @param {MozBrowser} browser <browser> element associated with the trigger. * @param {Object} message feature_callout message from ASRouter. * @see {@link FeatureCalloutMessages.sys.mjs} @@ -150,6 +152,7 @@ export class _FeatureCalloutBroker { * callout is already in progress. This allows the PDF.js feature tour, which * simulates content, to be shown in the chrome window without interfering * with chrome feature callouts. + * * @param {FeatureCalloutOptions} config * @param {Object} message feature_callout message from ASRouter. * @see {@link FeatureCalloutMessages.sys.mjs} diff --git a/browser/components/asrouter/modules/MessagingExperimentConstants.sys.mjs b/browser/components/asrouter/modules/MessagingExperimentConstants.sys.mjs @@ -14,6 +14,7 @@ * Other Nimbus features contain specific variables whose keys are enumerated in * FeatureManifest.yaml. Conversely, messaging experiment features contain * actual messages, with the usual message keys like `template` and `targeting`. + * * @see FeatureManifest.yaml * Messages delivered through these feature IDs record reach events, with the * exception of "pbNewtab". If you're adding new features to this list, make diff --git a/browser/components/asrouter/modules/MomentsPageHub.sys.mjs b/browser/components/asrouter/modules/MomentsPageHub.sys.mjs @@ -70,6 +70,7 @@ export class _MomentsPageHub { * it depends on user dependent parameters. Since the message matched * targeting we calculate `expire` based on the current timestamp and the * `expireDelta` which defines for how long it should be available. + * * @param expireDelta {number} - Offset in milliseconds from the current date */ getExpirationDate(expireDelta) { diff --git a/browser/components/asrouter/modules/PageEventManager.sys.mjs b/browser/components/asrouter/modules/PageEventManager.sys.mjs @@ -12,6 +12,7 @@ ChromeUtils.defineESModuleGetters(lazy, { export class PageEventManager { /** * A set of parameters defining a page event listener. + * * @typedef {Object} PageEventListenerParams * @property {String} type Event type string e.g. `click` * @property {String} [selectors] Target selector, e.g. `tag.class, #id[attr]` @@ -37,6 +38,7 @@ export class PageEventManager { /** * Maps event listener params to their PageEventListeners, so they can be * called and cancelled. + * * @type {Map<PageEventListenerParams, PageEventListener>} */ _listeners = new Map(); @@ -51,6 +53,7 @@ export class PageEventManager { /** * Adds a page event listener. + * * @param {PageEventListenerParams} params * @param {Function} callback Function to call when event is triggered */ @@ -109,6 +112,7 @@ export class PageEventManager { /** * Removes a page event listener. + * * @param {PageEventListenerParams} params */ off(params) { @@ -123,6 +127,7 @@ export class PageEventManager { /** * Adds a page event listener that is removed after the first event. + * * @param {PageEventListenerParams} params * @param {Function} callback Function to call when event is triggered */ @@ -147,6 +152,7 @@ export class PageEventManager { /** * Calls matching page event listeners. A way to dispatch a "fake" event. + * * @param {PageEvent} event */ emit(event) { diff --git a/browser/components/asrouter/modules/Spotlight.sys.mjs b/browser/components/asrouter/modules/Spotlight.sys.mjs @@ -36,6 +36,7 @@ export const Spotlight = { /** * Shows spotlight tab or window modal specific to the given browser + * * @param browser The browser for spotlight display * @param message Message containing content to show * @param dispatchCFRAction A function to dispatch resulting actions diff --git a/browser/components/asrouter/modules/ToastNotification.sys.mjs b/browser/components/asrouter/modules/ToastNotification.sys.mjs @@ -35,6 +35,7 @@ export const ToastNotification = { /** * Show a toast notification. + * * @param message Message containing content to show. * @param dispatch A function to dispatch resulting actions. * @return boolean value capturing if toast notification was displayed. diff --git a/browser/components/asrouter/tests/browser/browser_asrouter_experimentsAPILoader.js b/browser/components/asrouter/tests/browser/browser_asrouter_experimentsAPILoader.js @@ -164,6 +164,7 @@ async function cleanup() { /** * Assert that a message is (or optionally is not) present in the ASRouter * messages list, optionally waiting for it to be present/not present. + * * @param {string} id message id * @param {boolean} [found=true] expect the message to be found * @param {boolean} [wait=true] check for the message until found/not found diff --git a/browser/components/asrouter/tests/unit/ASRouterPreferences.test.js b/browser/components/asrouter/tests/unit/ASRouterPreferences.test.js @@ -167,6 +167,7 @@ describe("ASRouterPreferences", () => { * looks like a migrated version of the original provider. Requires that: * its id matches the original provider's id; it has no bucket; and its * collection is set to the value of the original provider's bucket. + * * @param {object} provider the provider object to compare to * @returns {object} custom matcher object for sinon */ diff --git a/browser/components/attribution/AttributionCode.sys.mjs b/browser/components/attribution/AttributionCode.sys.mjs @@ -89,6 +89,7 @@ export var AttributionCode = { /** * Write the given attribution code to the attribution file. + * * @param {String} code to write. */ async writeAttributionFile(code) { @@ -340,6 +341,7 @@ export var AttributionCode = { /** * Return the cached attribution data synchronously without hitting * the disk. + * * @returns A dictionary with the attribution data if it's available, * null otherwise. */ diff --git a/browser/components/downloads/DownloadSpamProtection.sys.mjs b/browser/components/downloads/DownloadSpamProtection.sys.mjs @@ -35,6 +35,7 @@ class WindowSpamProtection { * This map stores blocked spam downloads for the window, keyed by the * download's source URL. This is done so we can track the number of times a * given download has been blocked. + * * @type {Map<String, DownloadSpam>} */ _downloadSpamForUrl = new Map(); @@ -43,6 +44,7 @@ class WindowSpamProtection { * This set stores views that are waiting to have download notification * listeners attached. They will be attached when the spamList is created * (i.e. when the first spam download is blocked). + * * @type {Set<Object>} */ _pendingViews = new Set(); @@ -52,6 +54,7 @@ class WindowSpamProtection { * used to lazily load the spamList. Spam downloads are rare enough that many * sessions will have no blocked downloads. So we don't want to create a * DownloadList unless we actually need it. + * * @type {Boolean} */ _blocking = false; @@ -61,6 +64,7 @@ class WindowSpamProtection { * be sent notifications about downloads in this list, so that blocked spam * downloads can be represented in the UI. If spam downloads haven't been * blocked in the window, this will be undefined. See DownloadList.sys.mjs. + * * @type {DownloadList | undefined} */ get spamList() { @@ -77,6 +81,7 @@ class WindowSpamProtection { * A per-window downloads indicator whose state depends on notifications from * DownloadLists registered in the window (for example, the visual state of * the downloads toolbar button). See DownloadsCommon.sys.mjs for more details. + * * @type {DownloadsIndicatorData} */ get indicator() { @@ -89,6 +94,7 @@ class WindowSpamProtection { /** * Add a blocked download to the spamList or increment the count of an * existing blocked download, then notify listeners about this. + * * @param {String} url */ addDownloadSpam(url) { @@ -114,6 +120,7 @@ class WindowSpamProtection { /** * Notify the downloads panel that a new download has been added to the * spamList. This is invoked when a new DownloadSpam object is created. + * * @param {DownloadSpam} downloadSpam */ _notifyDownloadSpamAdded(downloadSpam) { @@ -135,6 +142,7 @@ class WindowSpamProtection { /** * Remove the download spam data for a given source URL. + * * @param {String} url */ removeDownloadSpamForUrl(url) { @@ -149,6 +157,7 @@ class WindowSpamProtection { /** * Set up a downloads view (e.g. the downloads panel) to receive notifications * about downloads in the spamList. + * * @param {Object} view An object that implements handlers for download * related notifications, like onDownloadAdded. */ @@ -197,6 +206,7 @@ class WindowSpamProtection { export class DownloadSpamProtection { /** * Stores spam protection data per-window. + * * @type {WeakMap<Window, WindowSpamProtection>} */ _forWindowMap = new WeakMap(); @@ -205,6 +215,7 @@ export class DownloadSpamProtection { * Add download spam data for a given source URL in the window where the * download was blocked. This is invoked when a download is blocked by * nsExternalAppHandler::IsDownloadSpam + * * @param {String} url * @param {Window} window */ @@ -227,6 +238,7 @@ export class DownloadSpamProtection { /** * Get the spam list for a given window (provided it exists). + * * @param {Window} window * @returns {DownloadList} */ @@ -237,6 +249,7 @@ export class DownloadSpamProtection { /** * Remove the download spam data for a given source URL in the passed window, * if any exists. + * * @param {String} url * @param {Window} window */ @@ -250,6 +263,7 @@ export class DownloadSpamProtection { * created) and prepare to start listening for notifications on the passed * downloads view. The bulk of resources won't be expended until a download is * blocked. To add multiple views, call this method multiple times. + * * @param {Object} view An object that implements handlers for download * related notifications, like onDownloadAdded. * @param {Window} window @@ -264,6 +278,7 @@ export class DownloadSpamProtection { /** * Remove the spam protection object for a window when it is closed. + * * @param {Window} window */ unregister(window) { @@ -278,6 +293,7 @@ export class DownloadSpamProtection { /** * Represents a special Download object for download spam. + * * @extends Download */ class DownloadSpam extends Download { diff --git a/browser/components/downloads/DownloadsCommon.sys.mjs b/browser/components/downloads/DownloadsCommon.sys.mjs @@ -987,6 +987,7 @@ DownloadsDataCtor.prototype = { /** * Displays a new or finished download notification in the most recent browser * window, if one is currently available with the required privacy type. + * * @param {string} aType * Set to "start" for new downloads, "finish" for completed downloads, * "error" for downloads that failed and need attention diff --git a/browser/components/downloads/content/downloads.js b/browser/components/downloads/content/downloads.js @@ -230,6 +230,7 @@ var DownloadsPanel = { /** * Indicates whether the panel is showing. + * * @note this includes the hiding state. */ get isPanelShowing() { diff --git a/browser/components/downloads/content/indicator.js b/browser/components/downloads/content/indicator.js @@ -337,6 +337,7 @@ const DownloadsIndicatorView = { /** * Check if the panel containing aNode is open. + * * @param aNode * the node whose panel we're interested in. */ diff --git a/browser/components/downloads/test/browser/browser_downloads_panel_opens.js b/browser/components/downloads/test/browser/browser_downloads_panel_opens.js @@ -27,6 +27,7 @@ async function checkPanelOpens() { /** * Start a download and check that the downloads panel opens correctly according * to the download parameter, openDownloadsListOnStart + * * @param {boolean} [openDownloadsListOnStart] * true (default) - open downloads panel when download starts * false - no downloads panel; update indicator attention state @@ -95,6 +96,7 @@ function clickCheckbox(checkbox) { * we should get a file picker dialog. If preferredAction is alwaysAsk, we * should get an unknown content type dialog. If neither of those is true, we * should get no dialog at all, and expect the downloads panel to open. + * * @param {boolean} [expectPanelToOpen] true - fail if panel doesn't open * false (default) - fail if it opens * @param {number} [preferredAction] Default download action: diff --git a/browser/components/preferences/dialogs/translations.js b/browser/components/preferences/dialogs/translations.js @@ -179,6 +179,7 @@ var gTranslationsSettings = { /** * Retrieves the always-translate language tags as an array. + * * @returns {Array<string>} */ getAlwaysTranslateLanguages() { @@ -187,6 +188,7 @@ var gTranslationsSettings = { /** * Retrieves the never-translate language tags as an array. + * * @returns {Array<string>} */ getNeverTranslateLanguages() { diff --git a/browser/components/preferences/extensionControlled.js b/browser/components/preferences/extensionControlled.js @@ -272,6 +272,7 @@ function makeDisableControllingExtension(type, settingName) { /** * Initialize listeners though the Management API to update the UI * when an extension is controlling a pref. + * * @param {string} type * @param {string} prefId The unique id of the setting * @param {HTMLElement} controlledElement diff --git a/browser/components/preferences/findInPage.js b/browser/components/preferences/findInPage.js @@ -157,6 +157,7 @@ var gSearchResultsPane = { * We pass in the nodeSizes to tell exactly where highlighting need be done. * When creating the range for highlighting, if the nodes are section is split * by an access key, it is important to have the size of each of the nodes summed. + * * @param Array textNodes * List of DOM elements * @param Array nodeSizes diff --git a/browser/components/preferences/home.js b/browser/components/preferences/home.js @@ -135,6 +135,7 @@ var gHomePane = { /** * _updateMenuInterface: adds items to or removes them from the menulists + * * @param {string} selectId Optional Id of the menulist to add or remove items from. * If not included this will update both home and newtab menus. */ @@ -285,6 +286,7 @@ var gHomePane = { /** * _renderCustomSettings: Hides or shows the UI for setting a custom * homepage URL + * * @param {obj} options * @param {bool} options.shouldShow Should the custom UI be shown? * @param {bool} options.isControlled Is an extension controlling the home page? @@ -325,6 +327,7 @@ var gHomePane = { /** * _isHomePageDefaultValue + * * @returns {bool} Is the homepage set to the default pref value? */ _isHomePageDefaultValue() { @@ -336,6 +339,7 @@ var gHomePane = { /** * isHomePageBlank + * * @returns {bool} Is the homepage set to about:blank? */ isHomePageBlank() { @@ -348,6 +352,7 @@ var gHomePane = { /** * _isTabAboutPreferencesOrSettings: Is a given tab set to about:preferences or about:settings? + * * @param {Element} aTab A tab element * @returns {bool} Is the linkedBrowser of aElement set to about:preferences or about:settings? */ @@ -360,6 +365,7 @@ var gHomePane = { /** * _getTabsForHomePage + * * @returns {Array} An array of current tabs */ _getTabsForHomePage() { diff --git a/browser/components/preferences/main.js b/browser/components/preferences/main.js @@ -987,6 +987,7 @@ const DefaultBrowserHelper = { /** * Checks whether the browser is capable of being made default. + * * @type {boolean} */ get canCheck() { @@ -2609,6 +2610,7 @@ var gMainPane = { /** * Update the DownloadPhase for a single langTag. + * * @param {string} langTag * @param {DownloadPhase} downloadPhase */ @@ -2629,6 +2631,7 @@ var gMainPane = { /** * Set all the downloads. + * * @param {DownloadPhase} downloadPhase */ markAllDownloadPhases(downloadPhase) { diff --git a/browser/components/preferences/sync.js b/browser/components/preferences/sync.js @@ -521,6 +521,7 @@ var gSyncPane = { /** * Attempts to take the user through the sign in flow by opening the web content * with the given entrypoint as a query parameter + * * @param entrypoint: An string appended to the query parameters, used in telemtry to differentiate * different entrypoints to accounts */ diff --git a/browser/components/preferences/tests/browser_defaultbrowser_alwayscheck.js b/browser/components/preferences/tests/browser_defaultbrowser_alwayscheck.js @@ -2,6 +2,7 @@ /** * Sets up initial prefs and opens about:preferences page. + * * @returns {Promise<void>} */ async function setup() { diff --git a/browser/components/preferences/tests/browser_https_only_exceptions.js b/browser/components/preferences/tests/browser_https_only_exceptions.js @@ -283,6 +283,7 @@ add_task(async function checkDialogFunctionality() { /** * Changes HTTPS-Only Mode pref + * * @param {string} state "everywhere", "private", "off" */ async function setHttpsOnlyPref(state) { @@ -296,6 +297,7 @@ async function setHttpsOnlyPref(state) { /** * Changes HTTPS-First Mode pref + * * @param {string} state "everywhere", "private", "off" */ async function setHttpsFirstPref(state) { @@ -309,6 +311,7 @@ async function setHttpsFirstPref(state) { /** * Opens new exceptions dialog, runs test function + * * @param {HTMLElement} preferencesDoc document of about:preferences tab * @param {function} test function to call when dialog is open * @param {Array} observances permission changes to observe (order is important) diff --git a/browser/components/preferences/tests/head.js b/browser/components/preferences/tests/head.js @@ -191,6 +191,7 @@ function waitForMutation(target, opts, cb) { /** * Creates observer that waits for and then compares all perm-changes with the observances in order. + * * @param {Array} observances permission changes to observe (order is important) * @returns {Promise} Promise object that resolves once all permission changes have been observed */ @@ -247,6 +248,7 @@ function createObserveAllPromise(observances) { /** * Waits for preference to be set and asserts the value. + * * @param {string} pref - Preference key. * @param {*} expectedValue - Expected value of the preference. * @param {string} message - Assertion message. @@ -267,6 +269,7 @@ async function waitForAndAssertPrefState(pref, expectedValue, message) { * dummy address by the test harness, filling the prefs with a "user value." * This temporarily sets the default value equal to the dummy value, so that * Firefox thinks we've configured the correct FxA server. + * * @returns {Promise<MockFxAUtilityFunctions>} { mock, unmock } */ async function mockDefaultFxAInstance() { @@ -558,6 +561,7 @@ function enrollByClick(el, wantedActive) { /** * Clicks a checkbox and waits for the associated preference to change to the expected value. + * * @param {Document} doc - The content document. * @param {string} checkboxId - The checkbox element id. * @param {string} prefName - The preference name. @@ -586,6 +590,7 @@ async function clickCheckboxAndWaitForPrefChange( /** * Clicks a checkbox that triggers a confirmation dialog and handles the dialog response. + * * @param {Document} doc - The document containing the checkbox. * @param {string} checkboxId - The ID of the checkbox to click. * @param {string} prefName - The name of the preference that should change. diff --git a/browser/components/preferences/translations.js b/browser/components/preferences/translations.js @@ -33,18 +33,21 @@ const TOPIC_TRANSLATIONS_PREF_CHANGED = "translations:pref-changed"; let gTranslationsPane = { /** * List of languages set in the Always Translate Preferences + * * @type Array<string> */ alwaysTranslateLanguages: [], /** * List of languages set in the Never Translate Preferences + * * @type Array<string> */ neverTranslateLanguages: [], /** * List of languages set in the Never Translate Site Preferences + * * @type Array<string> */ neverTranslateSites: [], @@ -52,6 +55,7 @@ let gTranslationsPane = { /** * A mapping from the language tag to the current download phase for that language * and it's download size. + * * @type {Map<string, {downloadPhase: "downloaded" | "removed" | "loading", size: number}>} */ downloadPhases: new Map(), @@ -65,6 +69,7 @@ let gTranslationsPane = { /** * List of languages names supported along with their tags (BCP 47 locale identifiers). + * * @type Array<{ langTag: string, displayName: string}> */ supportedLanguageTagsNames: [], @@ -463,6 +468,7 @@ let gTranslationsPane = { /** * Event handler when the user wants to add a language to * Always translate settings preferences list. + * * @param {Event} event */ async handleAddAlwaysTranslateLanguage(langTag) { @@ -478,6 +484,7 @@ let gTranslationsPane = { /** * Event handler when the user wants to add a language to * Never translate settings preferences list. + * * @param {Event} event */ async handleAddNeverTranslateLanguage(langTag) { @@ -494,6 +501,7 @@ let gTranslationsPane = { /** * Finds the langauges added and/or removed in the * Always/Never translate lists. + * * @param {Array<string>} currentSet * @param {Array<string>} newSet * @returns {Object} {Array<string>, Array<string>} @@ -507,6 +515,7 @@ let gTranslationsPane = { /** * Builds HTML elements for the Always/Never translate list * According to the preference setting + * * @param {string} pref - name of the preference for which the HTML is built * NEVER_TRANSLATE_LANGS_PREF / ALWAYS_TRANSLATE_LANGS_PREF */ @@ -563,6 +572,7 @@ let gTranslationsPane = { /** * Adds a site to Never translate site list + * * @param {string} site */ addSite(site) { @@ -605,6 +615,7 @@ let gTranslationsPane = { /** * Removes a site from Never translate site list + * * @param {string} site */ removeSite(site) { @@ -634,6 +645,7 @@ let gTranslationsPane = { /** * Oberver + * * @param {string} subject Notification specific interface pointer. * @param {string} topic nsPref:changed/perm-changed * @param {string} data cleared/changed/added/deleted @@ -691,6 +703,7 @@ let gTranslationsPane = { /** * Create a div HTML element representing a language. + * * @param {Array} langChildren * @returns {Element} div HTML element */ @@ -710,6 +723,7 @@ let gTranslationsPane = { /** * Creates a moz-button element as icon + * * @param {string} classNames classes added to the moz-button element * @param {string} buttonFluentID Fluent ID for the aria-label * @param {string} accessibleName "name" variable value of the aria-label @@ -736,6 +750,7 @@ let gTranslationsPane = { /** * Adds a language selected by the user to the list of * Always/Never translate settings list in the HTML. + * * @param {string} langTag - The BCP-47 language tag for the language * @param {Element} languageList - HTML element for the list of the languages. * @param {string} translatePrefix - "never" / "always" prefix depending on the settings section @@ -790,6 +805,7 @@ let gTranslationsPane = { /** * Creates a label HTML element representing * a language + * * @param {string} textContent * @param {string} value * @param {string} id @@ -806,6 +822,7 @@ let gTranslationsPane = { /** * Removes a language currently in the always/never translate language list * from the DOM. Invoked in response to changes in the relevant preferences. + * * @param {string} langTag The BCP-47 language tag for the language * @param {Element} languageList - HTML element for the list of the languages. */ @@ -822,6 +839,7 @@ let gTranslationsPane = { /** * Event Handler to remove a language selected by the user from the list of * Always translate settings list in Preferences. + * * @param {Event} event */ handleRemoveAlwaysTranslateLanguage(event) { @@ -834,6 +852,7 @@ let gTranslationsPane = { /** * Event Handler to remove a language selected by the user from the list of * Never translate settings list in Preferences. + * * @param {Event} event */ handleRemoveNeverTranslateLanguage(event) { @@ -846,6 +865,7 @@ let gTranslationsPane = { /** * Removes the site chosen by the user in the HTML * from the Never Translate Site Permission + * * @param {Event} event */ handleRemoveNeverTranslateSite(event) { @@ -857,6 +877,7 @@ let gTranslationsPane = { /** * Record the download phase downloaded/loading/removed for * given language in the local data. + * * @param {string} langTag * @param {string} downloadPhase */ @@ -945,6 +966,7 @@ let gTranslationsPane = { /** * Event Handler to download a language model selected by the user through HTML + * * @param {Event} event */ async handleDownloadLanguage(event) { @@ -1011,6 +1033,7 @@ let gTranslationsPane = { /** * Event Handler to remove a language model selected by the user through HTML + * * @param {Event} event */ async handleRemoveDownloadLanguage(event) { @@ -1072,6 +1095,7 @@ let gTranslationsPane = { /** * Event Handler to download all language models + * * @param {Event} event */ async handleDownloadAllLanguages(event) { @@ -1106,6 +1130,7 @@ let gTranslationsPane = { /** * Event Handler to remove all language models + * * @param {Event} event */ async handleRemoveAllDownloadLanguages(event) { @@ -1161,6 +1186,7 @@ let gTranslationsPane = { * changes the icon of individual language buttons: * from "download" icon to "remove" icon if "All Language" is downloaded. * from "remove" icon to "download" icon if "All Language" is removed. + * * @param {string} allLanguageDownloadStatus "All Language" status: downloaded/removed */ updateAllLanguageDownloadButtons(allLanguageDownloadStatus) { diff --git a/browser/components/preferences/widgets/security-privacy/security-privacy-card/security-privacy-card.mjs b/browser/components/preferences/widgets/security-privacy/security-privacy-card/security-privacy-card.mjs @@ -33,6 +33,7 @@ const L10N_IDS = { export default class SecurityPrivacyCard extends MozLitElement { /** * Private member to check the App Updater status + * * @returns {boolean} should we NOT warn the user about their app update status */ #okUpdateStatus() { diff --git a/browser/components/preferences/widgets/setting-control/setting-control.mjs b/browser/components/preferences/widgets/setting-control/setting-control.mjs @@ -22,6 +22,7 @@ import { /** * Properties that represent a nested HTML element that will be a direct descendant of this setting control element + * * @typedef {object} SettingNestedElementOption * @property {Array<SettingNestedElementOption>} [options] * @property {string} control - The {@link HTMLElement#localName} of any HTML element @@ -31,6 +32,7 @@ import { /** * Mapping of parent control tag names to the literal tag name for their * expected children. eg. "moz-radio-group"->literal`moz-radio`. + * * @type Map<string, literal> */ const KNOWN_OPTIONS = new Map([ @@ -43,6 +45,7 @@ const KNOWN_OPTIONS = new Map([ * Mapping of parent control tag names to the expected slot for their children. * If there's no entry here for a control then it's expected that its children * should go in the default slot. + * * @type Map<string, string> */ const ITEM_SLOT_BY_PARENT = new Map([ @@ -199,6 +202,7 @@ export class SettingControl extends SettingElement { /** * The default properties for an option. + * * @param {PreferencesSettingConfigNestedControlOption | SettingNestedElementOption} config */ getOptionPropertyMapping(config) { @@ -285,6 +289,7 @@ export class SettingControl extends SettingElement { /** * Prepare nested item config and settings. + * * @param {PreferencesSettingConfigNestedControlOption} config * @returns {Array<string>} */ @@ -311,6 +316,7 @@ export class SettingControl extends SettingElement { /** * Prepares any children (and any of its children's children) that this element may need. + * * @param {PreferencesSettingConfigNestedControlOption | SettingNestedElementOption} config * @returns {Array<string>} */ diff --git a/browser/components/preferences/widgets/setting-element/setting-element.mjs b/browser/components/preferences/widgets/setting-element/setting-element.mjs @@ -29,6 +29,7 @@ import { MozLitElement } from "chrome://global/content/lit-utils.mjs"; class SpreadDirective extends Directive { /** * A record of previously applied properties to avoid redundant updates. + * * @type {Record<string, unknown>} */ #prevProps = {}; @@ -36,6 +37,7 @@ class SpreadDirective extends Directive { /** * Render nothing by default as all changes are made in update using DOM APIs * on the element directly. + * * @returns {typeof nothing} */ render() { @@ -44,6 +46,7 @@ class SpreadDirective extends Directive { /** * Apply props to the element using DOM APIs, updating only changed values. + * * @param {AttributePart} part - The part of the template this directive is bound to. * @param {[Record<string, unknown>]} propsArray - An array with a single object containing props to apply. * @returns {typeof noChange} - Indicates to Lit that no re-render is needed. diff --git a/browser/components/preferences/widgets/sync-device-name/sync-device-name.mjs b/browser/components/preferences/widgets/sync-device-name/sync-device-name.mjs @@ -71,6 +71,7 @@ class SyncDeviceName extends MozLitElement { /** * Handles key presses in the device name input. * Pressing Enter saves the name, pressing Escape cancels editing. + * * @param {KeyboardEvent} event */ onDeviceNameKeyDown(event) { diff --git a/browser/components/privatebrowsing/ResetPBMPanel.sys.mjs b/browser/components/privatebrowsing/ResetPBMPanel.sys.mjs @@ -112,6 +112,7 @@ export const ResetPBMPanel = { /** * Handles the confirmation panel cancel button. + * * @param {MozButton} button - Cancel button that triggered the action. */ onCancel(button) { @@ -129,6 +130,7 @@ export const ResetPBMPanel = { /** * Handles the confirmation panel confirm button which triggers the clear * action. + * * @param {MozButton} button - Confirm button that triggered the action. */ async onConfirm(button) { diff --git a/browser/components/privatebrowsing/content/aboutPrivateBrowsing.js b/browser/components/privatebrowsing/content/aboutPrivateBrowsing.js @@ -4,6 +4,7 @@ /** * Determines whether a given value is a fluent id or plain text and adds it to an element + * * @param {Array<[HTMLElement, string]>} items An array of [element, value] where value is * a fluent id starting with "fluent:" or plain text */ diff --git a/browser/components/privatebrowsing/test/browser/browser_privatebrowsing_resetPBM.js b/browser/components/privatebrowsing/test/browser/browser_privatebrowsing_resetPBM.js @@ -25,6 +25,7 @@ const SELECTOR_PANEL_COMPLETION_TOAST = "#confirmation-hint"; /** * Wait for the reset pbm confirmation panel to open. May also be called if the * panel is already open. + * * @param {ChromeWindow} win - Chrome window in which the panel is embedded. * @returns {Promise} - Promise which resolves once the panel has been shown. * Resolves directly if the panel is already visible. @@ -46,6 +47,7 @@ async function waitForConfirmPanelShow(win) { /** * Hides the completion toast which is shown after the reset action has been * completed. + * * @param {ChromeWindow} win - Chrome window the toast is shown in. */ async function hideCompletionToast(win) { @@ -62,6 +64,7 @@ async function hideCompletionToast(win) { /** * Trigger the reset pbm toolbar button which may open the confirm panel in the * given window. + * * @param {nsIDOMWindow} win - PBM window to trigger the button in. * @param {boolean} [expectPanelOpen] - After the button action: whether the * panel is expected to open (true) or remain closed (false). @@ -91,6 +94,7 @@ async function triggerResetBtn(win, expectPanelOpen = true) { /** * Provides a promise that resolves once the reset confirmation panel has been hidden. + * * @param nsIDOMWindow win - Chrome window that has the panel. * @returns {Promise} */ @@ -103,6 +107,7 @@ function waitForConfirmPanelHidden(win) { /** * Provides a promise that resolves once the completion toast has been shown. + * * @param nsIDOMWindow win - Chrome window that has the panel. * @returns {Promise} */ @@ -120,6 +125,7 @@ function waitForCompletionToastShown(win) { * Clearing is not guaranteed to be done at this point. Bug 1846494 will add a * promise based mechanism and potentially a new triggering method for clearing, * at which point this helper should be updated. + * * @returns {Promise} Promise which resolves when the last-pb-context-exited * message has been dispatched. */ @@ -129,6 +135,7 @@ function waitForPBMDataClear() { /** * Test panel visibility. + * * @param {nsIDOMWindow} win - Chrome window which is the parent of the panel. * @param {string} selector - Query selector for the panel. * @param {boolean} expectVisible - Whether the panel should be visible (true) or invisible or not present (false). diff --git a/browser/components/screenshots/ScreenshotsOverlayChild.sys.mjs b/browser/components/screenshots/ScreenshotsOverlayChild.sys.mjs @@ -330,6 +330,7 @@ export class ScreenshotsOverlay { /** * Returns the x and y coordinates of the event relative to both the * viewport and the page. + * * @param {Event} event The event * @returns * { @@ -378,6 +379,7 @@ export class ScreenshotsOverlay { * early return in the event handler function. * If the event had another button, set to the crosshairs or selected state * and return true to early return from the event handler function. + * * @param {PointerEvent} event * @returns true if the event button(s) was the non primary button * false otherwise @@ -430,6 +432,7 @@ export class ScreenshotsOverlay { /** * Handles the pointerdown event depending on the state. * Early return when a pointer down happens on a button. + * * @param {Event} event The pointerown event */ handlePointerDown(event) { @@ -468,6 +471,7 @@ export class ScreenshotsOverlay { /** * Handles the pointermove event depending on the state + * * @param {Event} event The pointermove event */ handlePointerMove(event) { @@ -500,6 +504,7 @@ export class ScreenshotsOverlay { /** * Handles the pointerup event depending on the state + * * @param {Event} event The pointerup event */ handlePointerUp(event) { @@ -524,6 +529,7 @@ export class ScreenshotsOverlay { /** * Handles when a keydown occurs in the screenshots component. + * * @param {Event} event The keydown event */ handleKeyDown(event) { @@ -551,6 +557,7 @@ export class ScreenshotsOverlay { /** * Handles when a keyup occurs in the screenshots component. * All we need to do on keyup is set the state to selected. + * * @param {Event} event The keydown event */ handleKeyUp(event) { @@ -579,6 +586,7 @@ export class ScreenshotsOverlay { /** * Gets the accel key depending on the platform. * metaKey for macOS. ctrlKey for Windows and Linux. + * * @param {Event} event The keydown event * @returns {Boolean} True if the accel key is pressed, false otherwise. */ @@ -656,6 +664,7 @@ export class ScreenshotsOverlay { /** * Handles a keydown event for the dragging state. + * * @param {Event} event The keydown event */ draggingKeyDown(event) { @@ -685,6 +694,7 @@ export class ScreenshotsOverlay { /** * Handles a keydown event for the resizing state. + * * @param {Event} event The keydown event */ resizingKeyDown(event) { @@ -754,6 +764,7 @@ export class ScreenshotsOverlay { * Just the arrow key will move the region by 1px. * Arrow key + shift will move the region by 10px. * Arrow key + control/meta will move to the edge of the window. + * * @param {Event} event The keydown event */ resizingArrowLeftKeyDown(event) { @@ -771,6 +782,7 @@ export class ScreenshotsOverlay { * Just the arrow key will move the region by 1px. * Arrow key + shift will move the region by 10px. * Arrow key + control/meta will move to the edge of the window. + * * @param {Event} event The keydown event */ handleArrowLeftKeyDown(event) { @@ -831,6 +843,7 @@ export class ScreenshotsOverlay { * Just the arrow key will move the region by 1px. * Arrow key + shift will move the region by 10px. * Arrow key + control/meta will move to the edge of the window. + * * @param {Event} event The keydown event */ resizingArrowUpKeyDown(event) { @@ -848,6 +861,7 @@ export class ScreenshotsOverlay { * Just the arrow key will move the region by 1px. * Arrow key + shift will move the region by 10px. * Arrow key + control/meta will move to the edge of the window. + * * @param {Event} event The keydown event */ handleArrowUpKeyDown(event) { @@ -908,6 +922,7 @@ export class ScreenshotsOverlay { * Just the arrow key will move the region by 1px. * Arrow key + shift will move the region by 10px. * Arrow key + control/meta will move to the edge of the window. + * * @param {Event} event The keydown event */ resizingArrowRightKeyDown(event) { @@ -925,6 +940,7 @@ export class ScreenshotsOverlay { * Just the arrow key will move the region by 1px. * Arrow key + shift will move the region by 10px. * Arrow key + control/meta will move to the edge of the window. + * * @param {Event} event The keydown event */ handleArrowRightKeyDown(event) { @@ -988,6 +1004,7 @@ export class ScreenshotsOverlay { * Just the arrow key will move the region by 1px. * Arrow key + shift will move the region by 10px. * Arrow key + control/meta will move to the edge of the window. + * * @param {Event} event The keydown event */ resizingArrowDownKeyDown(event) { @@ -1059,6 +1076,7 @@ export class ScreenshotsOverlay { /** * We lock focus to the overlay when a region is selected. * Can still escape with shift + F6. + * * @param {Event} event The keydown event */ maybeLockFocus(event) { @@ -1157,6 +1175,7 @@ export class ScreenshotsOverlay { /** * Dispatch a custom event to the ScreenshotsComponentChild actor + * * @param {String} eventType The name of the event * @param {object} detail Extra details to send to the child actor */ @@ -1172,6 +1191,7 @@ export class ScreenshotsOverlay { /** * Set a new state for the overlay + * * @param {String} newState * @param {Object} options (optional) Options for calling start of state method */ @@ -1298,6 +1318,7 @@ export class ScreenshotsOverlay { /** * Dragging has started so we set the initial selection region and set the * state to draggingReady. + * * @param {Number} pageX The x position relative to the page * @param {Number} pageY The y position relative to the page */ @@ -1315,6 +1336,7 @@ export class ScreenshotsOverlay { /** * If the background is clicked we set the state to crosshairs * otherwise set the state to resizing + * * @param {Number} pageX The x position relative to the page * @param {Number} pageY The y position relative to the page * @param {String} targetId The id of the event target @@ -1334,6 +1356,7 @@ export class ScreenshotsOverlay { /** * Draw the eyes in the preview container and find the element currently * being hovered. + * * @param {Number} clientX The x position relative to the viewport * @param {Number} clientY The y position relative to the viewport */ @@ -1346,6 +1369,7 @@ export class ScreenshotsOverlay { /** * Set the selection region dimensions and if the region is at least 40 * pixels diagnally in distance, set the state to dragging. + * * @param {Number} pageX The x position relative to the page * @param {Number} pageY The y position relative to the page */ @@ -1363,6 +1387,7 @@ export class ScreenshotsOverlay { /** * Scroll if along the edge of the viewport, update the selection region * dimensions and draw the selection container. + * * @param {Number} pageX The x position relative to the page * @param {Number} pageY The y position relative to the page */ @@ -1378,6 +1403,7 @@ export class ScreenshotsOverlay { /** * Resize the selection region depending on the mover that started the resize. + * * @param {Number} pageX The x position relative to the page * @param {Number} pageY The y position relative to the page */ @@ -1520,6 +1546,7 @@ export class ScreenshotsOverlay { /** * Update the selection region dimensions and set the state to selected. + * * @param {Number} pageX The x position relative to the page * @param {Number} pageY The y position relative to the page */ @@ -1536,6 +1563,7 @@ export class ScreenshotsOverlay { /** * Update the selection region dimensions by calling `resizingDrag` and set * the state to selected. + * * @param {Number} pageX The x position relative to the page * @param {Number} pageY The y position relative to the page */ @@ -1569,6 +1597,7 @@ export class ScreenshotsOverlay { /** * Draw the preview eyes pointer towards the mouse. + * * @param {Number} clientX The x position relative to the viewport * @param {Number} clientY The y position relative to the viewport */ @@ -1776,6 +1805,7 @@ export class ScreenshotsOverlay { * Try to find a reasonable element for a given point. * If a reasonable element is found, draw the hover element container for * that element region. + * * @param {Number} clientX The x position relative to the viewport * @param {Number} clientY The y position relative to the viewport */ @@ -1819,6 +1849,7 @@ export class ScreenshotsOverlay { /** * Scroll the viewport if near one or both of the edges. + * * @param {Number} pageX The x position relative to the page * @param {Number} pageY The y position relative to the page */ @@ -1845,6 +1876,7 @@ export class ScreenshotsOverlay { /** * Scroll the window by the given amount. + * * @param {Number} x The x amount to scroll * @param {Number} y The y amount to scroll */ @@ -1856,6 +1888,7 @@ export class ScreenshotsOverlay { /** * The page was resized or scrolled. We need to update the screenshots * container size so we don't draw outside the page bounds. + * * @param {String} eventType will be "scroll" or "resize" */ async updateScreenshotsOverlayDimensions(eventType) { diff --git a/browser/components/screenshots/ScreenshotsUtils.sys.mjs b/browser/components/screenshots/ScreenshotsUtils.sys.mjs @@ -155,6 +155,7 @@ export var ScreenshotsUtils = { /** * Figures out which of various states the screenshots UI is in, for the given browser. + * * @param browser The selected browser * @returns One of the `UIPhases` constants */ @@ -332,6 +333,7 @@ export var ScreenshotsUtils = { /** * If the overlay state is crosshairs or dragging, move the native cursor * respective to the arrow key pressed. + * * @param {Event} event A keydown event * @param {Browser} browser The selected browser * @returns @@ -390,6 +392,7 @@ export var ScreenshotsUtils = { /** * Move the native cursor to the given position. Clamp the position to the * window just in case. + * * @param {Object} position An object containing the left and top position * @param {Browser} browser The selected browser */ @@ -448,6 +451,7 @@ export var ScreenshotsUtils = { /** * Notify screenshots when screenshot command is used. + * * @param window The current window the screenshot command was used. * @param type The type of screenshot taken. Used for telemetry. */ @@ -474,6 +478,7 @@ export var ScreenshotsUtils = { /** * Show the Screenshots UI and start the capture flow + * * @param browser The current browser. * @param reason [string] Optional reason string passed along when recording telemetry events */ @@ -503,6 +508,7 @@ export var ScreenshotsUtils = { /** * Exit the Screenshots UI for the given browser * Closes any of open UI elements (preview dialog, panel, overlay) and cleans up internal state. + * * @param browser The current browser. */ exit(browser) { @@ -760,6 +766,7 @@ export var ScreenshotsUtils = { /** * Returns the buttons panel for the given browser if the panel exists. * Otherwise creates the buttons panel and returns the buttons panel. + * * @param browser The current browser * @returns The buttons panel */ @@ -784,6 +791,7 @@ export var ScreenshotsUtils = { /** * Open the buttons panel. + * * @param browser The current browser */ openPanel(browser) { @@ -805,6 +813,7 @@ export var ScreenshotsUtils = { /** * Close the panel + * * @param browser The current browser */ closePanel(browser) { @@ -819,6 +828,7 @@ export var ScreenshotsUtils = { * If the buttons panel exists and is open we will hide both the panel * and the overlay. If the overlay is showing, we will hide the overlay. * Otherwise create or display the buttons. + * * @param browser The current browser. */ async showPanelAndOverlay(browser, data) { @@ -831,6 +841,7 @@ export var ScreenshotsUtils = { /** * Close the overlay UI, and clear out internal state if there was an overlay selection * The overlay lives in the child document; so although closing is actually async, we assume success. + * * @param browser The current browser. */ closeOverlay(browser, options = {}) { @@ -851,6 +862,7 @@ export var ScreenshotsUtils = { /** * Gets the screenshots dialog box + * * @param browser The selected browser * @returns Screenshots dialog box if it exists otherwise null */ @@ -878,6 +890,7 @@ export var ScreenshotsUtils = { /** * Closes the dialog box it it exists + * * @param browser The selected browser */ closeDialogBox(browser) { @@ -892,6 +905,7 @@ export var ScreenshotsUtils = { /** * Callback fired when the preview dialog window closes * Will exit the screenshots UI if the `exitOnPreviewClose` flag is set for this browser + * * @param browser The associated browser */ onDialogClose(browser) { @@ -909,6 +923,7 @@ export var ScreenshotsUtils = { * Gets the screenshots button if it is visible, otherwise it will get the * element that the screenshots button is nested under. If the screenshots * button doesn't exist then we will default to the navigator toolbox. + * * @param browser The selected browser * @returns The anchor element for the ConfirmationHint */ @@ -932,6 +947,7 @@ export var ScreenshotsUtils = { /** * Indicate that the screenshot has been copied via ConfirmationHint. + * * @param browser The selected browser */ showCopiedConfirmationHint(browser) { @@ -945,6 +961,7 @@ export var ScreenshotsUtils = { /** * Gets the full page bounds from the screenshots child actor. + * * @param browser The current browser. * @returns { object } * Contains the full page bounds from the screenshots child actor. @@ -956,6 +973,7 @@ export var ScreenshotsUtils = { /** * Gets the visible bounds from the screenshots child actor. + * * @param browser The current browser. * @returns { object } * Contains the visible bounds from the screenshots child actor. @@ -1000,6 +1018,7 @@ export var ScreenshotsUtils = { * 124925329. If the width or height is greater or equal to 32766 we will crop the * screenshot to the max width. If the area is still too large for the canvas * we will adjust the height so we can successfully capture the screenshot. + * * @param {Object} rect The dimensions of the screenshot. The rect will be * modified in place */ @@ -1040,6 +1059,7 @@ export var ScreenshotsUtils = { /** * Take the screenshot, then open and add the screenshot-ui element to the * dialog box. + * * @param browser The current browser. * @param type The type of screenshot taken. */ @@ -1091,6 +1111,7 @@ export var ScreenshotsUtils = { /** * Creates a canvas and draws a snapshot of the screenshot on the canvas + * * @param region The bounds of screenshots * @param browser The current browser * @returns The canvas @@ -1168,6 +1189,7 @@ export var ScreenshotsUtils = { /** * Copy the screenshot + * * @param region The bounds of the screenshots * @param browser The current browser */ @@ -1186,6 +1208,7 @@ export var ScreenshotsUtils = { /** * Copy the image to the clipboard * This is called from the preview dialog + * * @param blob The image data * @param browser The current browser * @param eventName For telemetry @@ -1250,6 +1273,7 @@ export var ScreenshotsUtils = { /** * Download the screenshot + * * @param title The title of the current page * @param region The bounds of the screenshot * @param browser The current browser @@ -1266,6 +1290,7 @@ export var ScreenshotsUtils = { /** * Download the screenshot * This is called from the preview dialog + * * @param title The title of the current page or null and getFilename will get the title * @param blobURL The image data * @param browser The current browser diff --git a/browser/components/screenshots/fileHelpers.mjs b/browser/components/screenshots/fileHelpers.mjs @@ -70,6 +70,7 @@ function checkFilenameLength(filename, maxFilenameLength) { /** * Gets the filename automatically or by a file picker depending on "browser.download.useDownloadDir" + * * @param filenameTitle The title of the current page * @param browser The current browser * @returns Path of the chosen filename @@ -149,6 +150,7 @@ export async function getFilename(filenameTitle, browser) { /** * Gets the path to the preferred screenshots directory if "browser.download.useDownloadDir" is true + * * @returns Path to preferred screenshots directory or null if not available */ export async function getDownloadDirectory() { @@ -166,6 +168,7 @@ export async function getDownloadDirectory() { /** * Structure for holding info about a URL and the target filename it should be * saved to. + * * @param aFileName The target filename */ class FileInfo { @@ -265,6 +268,7 @@ function appendFiltersForContentType( /** * Given the Filepicker Parameters (aFpP), show the file picker dialog, * prompting the user to confirm (or change) the fileName. + * * @param aFpP * A structure (see definition in internalSave(...) method) * containing all the data used within this method. diff --git a/browser/components/screenshots/overlayHelpers.mjs b/browser/components/screenshots/overlayHelpers.mjs @@ -23,6 +23,7 @@ const doNotAutoselectTags = { /** * Gets the rect for an element if getBoundingClientRect exists + * * @param ele The element to get the rect from * @returns The bounding client rect of the element or null */ @@ -111,6 +112,7 @@ export async function getElementFromPoint(x, y, doc) { /** * This function takes an element and finds a suitable rect to draw the hover box on + * * @param {Element} ele The element to find a suitale rect of * @param {Document} doc The current document * @returns A suitable rect or null @@ -200,6 +202,7 @@ export function getBestRectForElement(ele, doc) { /** * This finds a better element by looking for elements with role article + * * @param {Element} node The currently hovered node * @param {Document} doc The current document * @returns A better node or null @@ -243,6 +246,7 @@ export class Region { /** * Sets the dimensions if the given dimension is defined. * Otherwise will reset the dimensions + * * @param {Object} dims The new region dimensions * { * left: new left dimension value or undefined diff --git a/browser/components/screenshots/screenshots-buttons.js b/browser/components/screenshots/screenshots-buttons.js @@ -59,6 +59,7 @@ /** * Focus the last used button. * This will default to the visible page button. + * * @param {String} buttonToFocus */ async focusButton(buttonToFocus) { diff --git a/browser/components/screenshots/screenshots-preview.mjs b/browser/components/screenshots/screenshots-preview.mjs @@ -129,6 +129,7 @@ class ScreenshotsPreview extends MozLitElement { /** * If the image is complete and the height is greater than 0, we can resolve. * Otherwise wait for a load event on the image and resolve then. + * * @returns {Promise<String>} Resolves that resolves to the preview image src * once the image is loaded. */ @@ -208,6 +209,7 @@ class ScreenshotsPreview extends MozLitElement { /** * Set the focus to the most recent saved method. * This will default to the download button. + * * @param {String} buttonToFocus */ focusButton(buttonToFocus) { diff --git a/browser/components/screenshots/tests/browser/head.js b/browser/components/screenshots/tests/browser/head.js @@ -147,6 +147,7 @@ class ScreenshotsHelper { /** * Get the button from screenshots preview dialog + * * @param {Sting} name The id of the button to query * @returns The button or null */ @@ -335,6 +336,7 @@ class ScreenshotsHelper { * * Note: The distance of the rect should be greater than 40 to enter in the "dragging" state. * See https://searchfox.org/mozilla-central/rev/af78418c4b5f2c8721d1a06486cf4cf0b33e1e8d/browser/components/screenshots/ScreenshotsOverlayChild.sys.mjs#809 + * * @param {Number} startX The starting X coordinate. The left edge of the overlay rect. * @param {Number} startY The starting Y coordinate. The top edge of the overlay rect. * @param {Number} endX The end X coordinate. The right edge of the overlay rect. @@ -676,6 +678,7 @@ class ScreenshotsHelper { /** * Gets the dialog box + * * @returns The dialog box */ getDialog() { @@ -737,6 +740,7 @@ class ScreenshotsHelper { /** * Gets the client and scroll demensions on the window + * * @returns { Object } * clientHeight The visible height * clientWidth The visible width @@ -898,6 +902,7 @@ class ScreenshotsHelper { * Copied from screenshots extension * A helper that returns the size of the image that was just put into the clipboard by the * :screenshot command. + * * @return The {width, height, color} dimension and color object. */ async getImageSizeAndColorFromClipboard(options = {}) { @@ -1000,6 +1005,7 @@ class ScreenshotsHelper { /** * Get the raw clipboard data + * * @param flavor Type of data to get from clipboard * @returns The data from the clipboard */ diff --git a/browser/components/sessionstore/RecentlyClosedTabsAndWindowsMenuUtils.sys.mjs b/browser/components/sessionstore/RecentlyClosedTabsAndWindowsMenuUtils.sys.mjs @@ -45,6 +45,7 @@ function getClosedTabGroupsById() { export var RecentlyClosedTabsAndWindowsMenuUtils = { /** * Builds up a document fragment of UI items for the recently closed tabs. + * * @param {Window} aWindow * The window that the tabs were closed in. * @param {"menuitem"|"toolbarbutton"} aTagName @@ -141,6 +142,7 @@ export var RecentlyClosedTabsAndWindowsMenuUtils = { /** * Builds up a document fragment of UI items for the recently closed windows. + * * @param {Window} aWindow * A window that can be used to create the elements and document fragment. * @param {"menuitem"|"toolbarbutton"} aTagName @@ -179,6 +181,7 @@ export var RecentlyClosedTabsAndWindowsMenuUtils = { /** * Handle a command event to re-open all closed tabs + * * @param aEvent * The command event when the user clicks the restore all menu item */ @@ -246,6 +249,7 @@ export var RecentlyClosedTabsAndWindowsMenuUtils = { /** * Handle a command event to re-open all closed windows + * * @param aEvent * The command event when the user clicks the restore all menu item */ @@ -259,6 +263,7 @@ export var RecentlyClosedTabsAndWindowsMenuUtils = { /** * Re-open a closed tab and put it to the end of the tab strip. * Used for a middle click. + * * @param aEvent * The event when the user clicks the menu item */ @@ -465,6 +470,7 @@ function createTabGroupSubpanel( /** * Create a UI entry for a recently closed tab, tab group, or window. + * * @param {"menuitem"|"toolbarbutton"} aTagName * the tag name that will be used when creating the UI entry * @param {boolean} aIsWindowsFragment diff --git a/browser/components/sessionstore/SessionFile.sys.mjs b/browser/components/sessionstore/SessionFile.sys.mjs @@ -40,6 +40,7 @@ export var SessionFile = { }, /** * Write the contents of the session file, asynchronously. + * * @param aData - May get changed on shutdown. */ write(aData) { diff --git a/browser/components/sessionstore/SessionStartup.sys.mjs b/browser/components/sessionstore/SessionStartup.sys.mjs @@ -330,6 +330,7 @@ export var SessionStartup = { * launch of the browser. This does not include crash restoration. In * particular, if session restore is configured to restore only in case of * crash, this method returns false. + * * @returns bool */ isAutomaticRestoreEnabled() { @@ -348,6 +349,7 @@ export var SessionStartup = { /** * Determines whether there is a pending session restore. + * * @returns bool */ willRestore() { @@ -360,6 +362,7 @@ export var SessionStartup = { /** * Determines whether there is a pending session restore and if that will refer * back to a crash. + * * @returns bool */ willRestoreAsCrashed() { diff --git a/browser/components/sessionstore/SessionStore.sys.mjs b/browser/components/sessionstore/SessionStore.sys.mjs @@ -271,6 +271,7 @@ export var SessionStore = { /** * Get the collection of all matching windows tracked by SessionStore + * * @param {Window|Object} [aWindowOrOptions] Optionally an options object or a window to used to determine if we're filtering for private or non-private windows * @param {boolean} [aWindowOrOptions.private] Determine if we should filter for private or non-private windows */ @@ -280,6 +281,7 @@ export var SessionStore = { /** * Get window a given closed tab belongs to + * * @param {integer} aClosedId The closedId of the tab whose window we want to find * @param {boolean} [aIncludePrivate] Optionally include private windows when searching for the closed tab */ @@ -343,6 +345,7 @@ export var SessionStore = { * How many tabs were last closed. If multiple tabs were selected and closed together, * we'll return that number. Normally the count is 1, or 0 if no tabs have been * recently closed in this window. + * * @returns the number of tabs that were last closed. */ getLastClosedTabCount(aWindow) { @@ -355,6 +358,7 @@ export var SessionStore = { /** * Get the number of closed tabs associated with a specific window + * * @param {Window} aWindow */ getClosedTabCountForWindow: function ss_getClosedTabCountForWindow(aWindow) { @@ -363,6 +367,7 @@ export var SessionStore = { /** * Get the number of closed tabs associated with all matching windows + * * @param {Window|Object} [aOptions] * Either a DOMWindow (see aOptions.sourceWindow) or an object with properties to identify which closed tabs to include in the count. @@ -393,6 +398,7 @@ export var SessionStore = { /** * Get the closed tab data associated with this window + * * @param {Window} aWindow */ getClosedTabDataForWindow: function ss_getClosedTabDataForWindow(aWindow) { @@ -401,6 +407,7 @@ export var SessionStore = { /** * Get the closed tab data associated with all matching windows + * * @param {Window|Object} [aOptions] * Either a DOMWindow (see aOptions.sourceWindow) or an object with properties to identify which closed tabs to get data from @@ -420,6 +427,7 @@ export var SessionStore = { /** * Get the closed tab data associated with all closed windows + * * @returns an un-sorted array of tabData for closed tabs from closed windows */ getClosedTabDataFromClosedWindows: @@ -429,6 +437,7 @@ export var SessionStore = { /** * Get the closed tab group data associated with all matching windows + * * @param {Window|object} aOptions * Either a DOMWindow (see aOptions.sourceWindow) or an object with properties to identify the window source of the closed tab groups @@ -449,6 +458,7 @@ export var SessionStore = { /** * Get the last closed tab ID associated with a specific window + * * @param {Window} aWindow */ getLastClosedTabGroupId(window) { @@ -457,6 +467,7 @@ export var SessionStore = { /** * Re-open a closed tab + * * @param {Window|Object} aSource * Either a DOMWindow or an object with properties to resolve to the window * the tab was previously open in. @@ -475,6 +486,7 @@ export var SessionStore = { /** * Re-open a tab from a closed window, which corresponds to the closedId + * * @param {Window|Object} aSource * Either a DOMWindow or an object with properties to resolve to the window * the tab was previously open in. @@ -581,6 +593,7 @@ export var SessionStore = { /** * Look up the object type ("tab" or "window") for a given closedId + * * @param {integer} aClosedId */ getObjectTypeForClosedId(aClosedId) { @@ -589,6 +602,7 @@ export var SessionStore = { /** * Look up a window tracked by SessionStore by its id + * * @param {String} aSessionStoreId */ getWindowById: function ss_getWindowById(aSessionStoreId) { @@ -745,6 +759,7 @@ export var SessionStore = { /** * Ensures that session store has registered and started tracking a given window. + * * @param window * Window reference */ @@ -830,6 +845,7 @@ export var SessionStore = { /** * Clear session store data for a given private browsing window. + * * @param {ChromeWindow} win - Open private browsing window to clear data for. */ purgeDataForPrivateWindow(win) { @@ -838,6 +854,7 @@ export var SessionStore = { /** * Add a tab group to the session's saved group list. + * * @param {MozTabbrowserTabGroup} tabGroup - The group to save */ addSavedTabGroup(tabGroup) { @@ -873,6 +890,7 @@ export var SessionStore = { /** * Returns all tab groups that were saved in this session. + * * @returns {SavedTabGroupStateData[]} */ getSavedTabGroups() { @@ -881,6 +899,7 @@ export var SessionStore = { /** * Remove a tab group from the session's saved tab group list. + * * @param {string} tabGroupId * The ID of the tab group to remove */ @@ -890,6 +909,7 @@ export var SessionStore = { /** * Re-open a closed tab group + * * @param {Window|Object} source * Either a DOMWindow or an object with properties to resolve to the window * the tab was previously open in. @@ -916,6 +936,7 @@ export var SessionStore = { * Note that this method does not require passing a window source, as saved * tab groups are independent of windows. * Attempting to open a saved tab group in a private window will raise an error. + * * @param {string} tabGroupId * The unique ID of the group to restore. * @param {Window} [targetWindow] defaults to the top window if not specified. @@ -1066,6 +1087,7 @@ var SessionStoreInternal = { /** * states for all currently opened windows + * * @type {object.<WindowID, WindowStateData>} */ _windows: {}, @@ -1111,6 +1133,7 @@ var SessionStoreInternal = { /** * An in-order stack of close actions for tabs and windows. + * * @type {CloseAction[]} */ _lastClosedActions: [], @@ -1960,6 +1983,7 @@ var SessionStoreInternal = { /** * Generate a unique window identifier + * * @return string * A unique string to identify a window */ @@ -2226,6 +2250,7 @@ var SessionStoreInternal = { /** * Called right before a new browser window is shown. + * * @param aWindow * Window reference */ @@ -2318,6 +2343,7 @@ var SessionStoreInternal = { * On window close... * - remove event listeners from tabs * - save all window data + * * @param aWindow * Window reference * @@ -2923,6 +2949,7 @@ var SessionStoreInternal = { /** * On quitting application + * * @param aData * String type of quitting */ @@ -2960,6 +2987,7 @@ var SessionStoreInternal = { /** * Clear session store data for a given private browsing window. + * * @param {ChromeWindow} win - Open private browsing window to clear data for. */ purgeDataForPrivateWindow(win) { @@ -3055,6 +3083,7 @@ var SessionStoreInternal = { /** * On purge of domain data + * * @param {string} aDomain * The domain we want to purge data for */ @@ -3136,6 +3165,7 @@ var SessionStoreInternal = { /** * On preference change + * * @param aData * String preference changed */ @@ -3185,6 +3215,7 @@ var SessionStoreInternal = { /** * save state when new tab is added + * * @param aWindow * Window reference */ @@ -3194,6 +3225,7 @@ var SessionStoreInternal = { /** * set up listeners for a new tab + * * @param aWindow * Window reference * @param aTab @@ -3225,6 +3257,7 @@ var SessionStoreInternal = { /** * remove listeners for a tab + * * @param aWindow * Window reference * @param aTab @@ -3242,6 +3275,7 @@ var SessionStoreInternal = { /** * When a tab closes, collect its properties + * * @param {Window} aWindow * Window reference * @param {MozTabbrowserTab} aTab @@ -3328,6 +3362,7 @@ var SessionStoreInternal = { /** * Flush and copy tab state when moving a tab to a new window. + * * @param aFromBrowser * Browser reference. * @param aToBrowser @@ -3418,6 +3453,7 @@ var SessionStoreInternal = { /** * Remove listeners which were added when browser was inserted and reset restoring state. * Also re-instate lazy data and basically revert tab to its lazy browser state. + * * @param aTab * Tab reference */ @@ -3483,6 +3519,7 @@ var SessionStoreInternal = { * Check if we are dealing with a crashed browser. If so, then the corresponding * crashed tab was revived by navigating to a different page. Remove the browser * from the list of crashed browsers to stop ignoring its messages. + * * @param aBrowser * Browser reference */ @@ -3495,6 +3532,7 @@ var SessionStoreInternal = { /** * A debugging-only function to check if a browser is in _crashedBrowsers. + * * @param aBrowser * Browser reference */ @@ -3509,6 +3547,7 @@ var SessionStoreInternal = { /** * When a tab is removed or suspended, remove listeners and reset restoring state. + * * @param aBrowser * Browser reference */ @@ -3636,6 +3675,7 @@ var SessionStoreInternal = { /** * When a tab is selected, save session data + * * @param aWindow * Window reference */ @@ -5405,6 +5445,7 @@ var SessionStoreInternal = { /** * Store window dimensions, visibility, sidebar + * * @param aWindow * Window reference */ @@ -5441,6 +5482,7 @@ var SessionStoreInternal = { /** * gather session data as object + * * @param aUpdateAll * Bool update all windows * @returns object @@ -5574,6 +5616,7 @@ var SessionStoreInternal = { /** * serialize session data for a window + * * @param {Window} aWindow * Window reference * @returns {{windows: [WindowStateData]}} @@ -5699,6 +5742,7 @@ var SessionStoreInternal = { /** * Reset closedId's from previous sessions to ensure these IDs are unique + * * @param tabData * an array of data to be restored * @param {String} windowId @@ -5714,6 +5758,7 @@ var SessionStoreInternal = { }, /** * restore features to a single window + * * @param aWindow * Window reference to the window to use for restoration * @param winData @@ -6038,6 +6083,7 @@ var SessionStoreInternal = { /** * Restore multiple windows using the provided state. + * * @param aWindow * Window reference to the first window to use for restoration. * Additionally required windows will be opened. @@ -6117,6 +6163,7 @@ var SessionStoreInternal = { /** * Manage history restoration for a window + * * @param aWindow * Window to restore the tabs into * @param aTabs @@ -6493,6 +6540,7 @@ var SessionStoreInternal = { /** * Restore visibility and dimension features to a window + * * @param aWindow * Window reference * @param aWinData @@ -6552,6 +6600,7 @@ var SessionStoreInternal = { /** * Restore a window's dimensions + * * @param aWidth * Window width in desktop pixels * @param aHeight @@ -6858,6 +6907,7 @@ var SessionStoreInternal = { /** * Returns most recent window + * * @param {boolean} [isPrivate] * Optional boolean to get only non-private or private windows * When omitted, we'll return whatever the top-most window is regardless of privateness @@ -6911,6 +6961,7 @@ var SessionStoreInternal = { /** * open a new browser window for a given session state * called when restoring a multi-window session + * * @param aState * Object containing session data */ @@ -6989,6 +7040,7 @@ var SessionStoreInternal = { * whether the user wants to load any other page at startup * (except the homepage) - needed for determining whether to overwrite the current tabs * C.f.: nsBrowserContentHandler's defaultArgs implementation. + * * @returns bool */ _isCmdLineEmpty: function ssi_isCmdLineEmpty(aWindow, aState) { @@ -7018,6 +7070,7 @@ var SessionStoreInternal = { * we use thus JSDOMWindow attributes for sizemode and normal window attributes * (and hope for reasonable values when maximized/minimized - since then * outerWidth/outerHeight aren't the dimensions of the restored window) + * * @param aWindow * Window reference * @param aAttribute @@ -7477,6 +7530,7 @@ var SessionStoreInternal = { /** * Set the given window's busy state + * * @param aWindow the window * @param aValue the window's busy state */ @@ -7497,6 +7551,7 @@ var SessionStoreInternal = { /** * Set the given window's state to 'not busy'. + * * @param aWindow the window */ _setWindowStateReady: function ssi_setWindowStateReady(aWindow) { @@ -7514,6 +7569,7 @@ var SessionStoreInternal = { /** * Set the given window's state to 'busy'. + * * @param aWindow the window */ _setWindowStateBusy: function ssi_setWindowStateBusy(aWindow) { @@ -7528,6 +7584,7 @@ var SessionStoreInternal = { /** * Dispatch an SSWindowStateReady event for the given window. + * * @param aWindow the window */ _sendWindowStateReadyEvent: function ssi_sendWindowStateReadyEvent(aWindow) { @@ -7538,6 +7595,7 @@ var SessionStoreInternal = { /** * Dispatch an SSWindowStateBusy event for the given window. + * * @param aWindow the window */ _sendWindowStateBusyEvent: function ssi_sendWindowStateBusyEvent(aWindow) { @@ -7548,6 +7606,7 @@ var SessionStoreInternal = { /** * Dispatch the SSWindowRestoring event for the given window. + * * @param aWindow * The window which is going to be restored */ @@ -7559,6 +7618,7 @@ var SessionStoreInternal = { /** * Dispatch the SSWindowRestored event for the given window. + * * @param aWindow * The window which has been restored */ @@ -7570,6 +7630,7 @@ var SessionStoreInternal = { /** * Dispatch the SSTabRestored event for the given tab. + * * @param aTab * The tab which has been restored * @param aIsRemotenessUpdate @@ -8246,6 +8307,7 @@ var SessionStoreInternal = { /** * Returns all tab groups that were saved in this session. + * * @returns {SavedTabGroupStateData[]} */ getSavedTabGroups() { diff --git a/browser/components/sessionstore/SessionWindowUI.sys.mjs b/browser/components/sessionstore/SessionWindowUI.sys.mjs @@ -49,6 +49,7 @@ export var SessionWindowUI = { /** * Re-open a closed tab into the current window. + * * @param window * Window reference * @param [aIndex] @@ -139,6 +140,7 @@ export var SessionWindowUI = { /** * Re-open a closed window. + * * @param aIndex * The index of the window (via SessionStore.getClosedWindowData) * @returns a reference to the reopened window. diff --git a/browser/components/sessionstore/SessionWriter.sys.mjs b/browser/components/sessionstore/SessionWriter.sys.mjs @@ -62,6 +62,7 @@ export const SessionWriter = { /** * Write the contents of the session file. + * * @param state - May get changed on shutdown. */ async write(state, options = {}) { diff --git a/browser/components/sessionstore/test/browser_354894_perwindowpb.js b/browser/components/sessionstore/test/browser_354894_perwindowpb.js @@ -460,6 +460,7 @@ add_task(async function test_open_close_restore_from_popup() { /** * Test if closing can be denied on Mac. + * * @note: Mac only */ add_task(async function test_mac_notifications() { diff --git a/browser/components/storybook/.storybook/markdown-story-indexer.js b/browser/components/storybook/.storybook/markdown-story-indexer.js @@ -15,6 +15,7 @@ const fs = require("fs"); * order to get the data Storybook needs, we have to convert the markdown to * MDX, the convert that to CSF. * More info on indexers can be found here: storybook.js.org/docs/api/main-config-indexers + * * @param {string} fileName - Path to the file being processed. * @param {Object} opts - Options to configure the indexer. * @returns Array of IndexInput objects. diff --git a/browser/components/storybook/.storybook/markdown-story-utils.js b/browser/components/storybook/.storybook/markdown-story-utils.js @@ -41,6 +41,7 @@ function getTitleFromPath(filePath) { /** * Splits a string into multiple capitalized words e.g. hello-world, helloWorld, * and hello.world all become "Hello World." + * * @param {string} str - String in any case. * @returns {string} The string split into multiple words. */ @@ -56,6 +57,7 @@ function separateWords(str) { /** * Enables rendering code in our markdown docs by parsing the source for * annotated code blocks and replacing them with Storybook's Canvas component. + * * @param {string} source - Stringified markdown source code. * @returns {string} Source with code blocks replaced by Canvas components. */ @@ -71,6 +73,7 @@ function parseStoriesFromMarkdown(source) { /** * Finds the name of the component for files in toolkit widgets. + * * @param {string} resourcePath - Path to the file being processed. * @returns The component name e.g. "moz-toggle" */ @@ -87,6 +90,7 @@ function getComponentName(resourcePath) { * Figures out where a markdown based story should live in Storybook i.e. * whether it belongs under "Docs" or "UI Widgets" as well as what name to * display in the sidebar. + * * @param {string} resourcePath - Path to the file being processed. * @returns {string} The title of the story. */ @@ -117,6 +121,7 @@ function getStoryTitle(resourcePath) { * interactive examples in the docs that require the component to have been * loaded. This wasn't necessary prior to Storybook V7 since everything was * loaded up front; now stories are loaded on demand. + * * @param {string} resourcePath - Path to the file being processed. * @returns Path used to import a component into a story. */ @@ -154,6 +159,7 @@ function getImportPath(resourcePath) { /** * Takes markdown and re-writes it to MDX. Conditionally includes a table of * arguments when we're documenting a component. + * * @param {string} source - The markdown source to rewrite to MDX. * @param {string} title - The title of the story. * @param {string} resourcePath - Path to the file being processed. diff --git a/browser/components/tabbrowser/AsyncTabSwitcher.sys.mjs b/browser/components/tabbrowser/AsyncTabSwitcher.sys.mjs @@ -930,6 +930,7 @@ export class AsyncTabSwitcher { /** * Check if the browser should be deactivated. If the browser is a print preview or * split view or PiP browser then we won't deactivate it. + * * @param browser The browser to check if it should be deactivated * @returns false if a print preview or PiP browser else true */ diff --git a/browser/components/tabbrowser/SmartTabGrouping.sys.mjs b/browser/components/tabbrowser/SmartTabGrouping.sys.mjs @@ -187,6 +187,7 @@ export function getBestAnchorClusterInfo(groupIndices, anchorItems) { /** * Check tab to see if it's a search page + * * @param {Object} tab * @returns {boolean} Returns true if the tab is a web search from the Firefox search UI and the user is still on the original page. * Changes in search query after search is made is supported. @@ -217,6 +218,7 @@ export function isSearchTab(tab) { export class SmartTabGroupingManager { /** * Creates the SmartTabGroupingManager object. + * * @param {object} config configuration options */ constructor(config) { @@ -252,6 +254,7 @@ export class SmartTabGroupingManager { /** * Generates suggested tabs for an existing or provisional group + * * @param {object} group active group we are adding tabs to * @param {array} tabs list of tabs from gbrowser, some of which may be grouped in other groups * @returns a list of suggested new tabs. If no new tabs are suggested an empty list is returned. @@ -327,6 +330,7 @@ export class SmartTabGroupingManager { /** * Get tabs that need to be included in suggestions + * * @param {array} allTabs all tabs that are part of the window * @param {array} groupedIndices indices of tabs that are already part of the group * @param {array} alreadyGroupedIndices indices of tabs that are part of other groups @@ -352,6 +356,7 @@ export class SmartTabGroupingManager { /** * Generates similar tabs a grouped list of tabs + * * @param {array} allTabs all tabs that are part of the window * @param {array} groupedIndices indices of tabs that are already part of the group * @param {array} alreadyGroupedIndices indices of tabs that are part of other groups @@ -436,6 +441,7 @@ export class SmartTabGroupingManager { /** * Calculates the average similarity between the anchor embeddings and the candidate embeddings + * * @param {list[Number]} anchorEmbeddings title embeddings for the anchor tabs * @param {list[Number]} candidateEmbeddings title embeddings for the candidate tabs */ @@ -590,6 +596,7 @@ export class SmartTabGroupingManager { /** * Changes the clustering method. Must be one of supported methods. + * * @param {string} method Name of method */ setClusteringMethod(method) { @@ -617,6 +624,7 @@ export class SmartTabGroupingManager { /** * Sets method to reduce dimensionality of embeddings prior to clustering + * * @param {string} method Name of method */ setDimensionReductionMethod(method) { @@ -629,6 +637,7 @@ export class SmartTabGroupingManager { /** * Sets the field name of the title of a page to be used when clustering or generating embeddings * This is useful when clustering test data that is not a tab object + * * @param {string} titleKey KEY FOR THE TITLE */ setDataTitleKey(titleKey) { @@ -637,6 +646,7 @@ export class SmartTabGroupingManager { /** * Logs to the appropriate place for debugging. Console for now + * * @param {string} msg Message to log * @param {boolean} useDescription Whether to add description to the final text */ @@ -644,6 +654,7 @@ export class SmartTabGroupingManager { /** * Prepares data to be used by the ml models + * * @param {Object[]} tabList list of tabs in the current window * @param {boolean} useDescription whether we should combined the title and description * @return {Promise<*[Object]>} @@ -699,6 +710,7 @@ export class SmartTabGroupingManager { /** * Creates an ML engine for a given config. + * * @param {*} engineConfig * @param {function} progressCallback * @returns MLEngine @@ -745,6 +757,7 @@ export class SmartTabGroupingManager { /** * Generates embeddings from a list of tab data structures + * * @param tabList List of tabs with label (title) and description keys * @returns {Promise<*[]>} List of embeddings (2d array) * @private @@ -771,6 +784,7 @@ export class SmartTabGroupingManager { /** * Clusters in desired methods * based on the config of the class + * * @param tabList List of tabs as array * @param docEmbeddings Precomputed embeddings for the Tab as two dimensional array * @param k Desired number of clusters. Tries a range of sizes if 0. @@ -975,6 +989,7 @@ export class SmartTabGroupingManager { /** * Create static cluster from a list of tabs. A single tab is Ok. Returns null for 0 tabs + * * @param tabs * @returns {SmartTabGroupingResult} groupingResult */ @@ -992,6 +1007,7 @@ export class SmartTabGroupingManager { /** * Utility function that loads all required engines for Smart Tab Grouping and any dependent models + * * @param {(progress: { percentage: number }) => void} progressCallback callback function to call. * Callback passes a dict with percentage indicating best effort 0.0-100.0 progress in model download. */ @@ -1055,6 +1071,7 @@ export class SmartTabGroupingManager { /** * Generate model input from keywords and documents + * * @param {string []} keywords * @param {string []} documents */ @@ -1069,6 +1086,7 @@ export class SmartTabGroupingManager { * One artifact of the LLM output is that sometimes words are duplicated * This function cuts the phrase when it sees the first duplicate word. * Handles simple singluar / plural duplicates (-s only). + * * @param {string} phrase Input phrase * @returns {string} phrase cut before any duplicate word */ @@ -1098,6 +1116,7 @@ export class SmartTabGroupingManager { /** * Removes trailing domain-related text such as '... - Mail' or '... | News' * If there's not enough information remaining after, we keep the text as is + * * @param {string} text tab title with potential domain information * @return {string} */ @@ -1133,6 +1152,7 @@ export class SmartTabGroupingManager { /** * Postprocessing of raw output from Topic Model ML Engine + * * @param {string | undefined} topic Raw topic phrase from topic model or undefined in case of an error */ processTopicModelResult(topic) { @@ -1153,6 +1173,7 @@ export class SmartTabGroupingManager { * item that represents all other ungrouped tabs. * * In the future this may be updated to more generally find labels for a set of clusters. + * * @param {SmartTabGroupingResult} groupingResult The cluster we are generating the label for * @param {SmartTabGroupingResult} otherGroupingResult A 'made up' cluster representing all other tabs in the window */ @@ -1317,6 +1338,7 @@ export class SmartTabGroupingResult { /** * Creates a result from indices and complete tab and embedding lists. * This may create some extra data for management later + * * @param indices indices of clusters (eg [[2,4], [1], [3]]_ * @param tabItems 1D array of tabs * @param embeddingItems Two dimensional array of embeddings @@ -1351,6 +1373,7 @@ export class SmartTabGroupingResult { /** * Returns a list of documents for each cluster. Currently it is a list of documents picked * in no particular order. + * * @return {[strings]} Title and description that represent the cluster. (If no docs are in the class, then titles are returned) */ getRepresentativeDocuments() { @@ -1366,6 +1389,7 @@ export class SmartTabGroupingResult { /** * Returns the keywords and documents for the cluster, computing if needed * Does not return keywods if only one document is passed to the function. + * * @param{string[]} otherDocuments other clusters that we'll compare against * @return keywords and documents that represent the cluster */ @@ -1390,6 +1414,7 @@ export class SmartTabGroupingResult { /** * Get the cluster we originally are grouping around (finding additinoal item) + * * @returns ClusterRepresentation */ getAnchorCluster() { @@ -1434,6 +1459,7 @@ export class SmartTabGroupingResult { /** * Computes the inertia of the cluster which is the sum of square total distance. + * * @returns {number} */ getCentroidInertia() { @@ -1447,6 +1473,7 @@ export class SmartTabGroupingResult { /** * Converts a cluster representation to a flat list of tabs, with clusterID key in each * tab representing the id of the cluster it was part of. + * * @returns {[Object]} */ _flatMapItemsInClusters() { @@ -1464,6 +1491,7 @@ export class SmartTabGroupingResult { /** * Get rand score which describes the accuracy versus a user labeled * annotation on the dataset. Requires the dataset to be labeled. + * * @param labelKey Key in the tabs that represent a unique label ID for the cluster. * @returns {number} The rand score. */ @@ -1474,6 +1502,7 @@ export class SmartTabGroupingResult { /** * Get accuracy for a specific cluster + * * @param labelKey Key in the tabs that represent a unique label ID for the cluster. * @param clusterValue is the cluster we are comparing * @returns {number} The rand score. @@ -1517,6 +1546,7 @@ export class SmartTabGroupingResult { /** * Utility function to generate a random ID string + * * @param len Length of the string * @returns {string} */ @@ -1553,6 +1583,7 @@ class EmbeddingCluster { /** * Returns number of items in the cluster + * * @returns {int} */ numItems() { @@ -1580,6 +1611,7 @@ export class ClusterRepresentation extends EmbeddingCluster { /** * For a single tab cluster with a search field, set the predicted topic * to be the title of the page + * * @returns {boolean} True if we updated the cluster label successfully */ setSingleTabSearchLabel() { @@ -1616,6 +1648,7 @@ export class ClusterRepresentation extends EmbeddingCluster { /** * Returns representative text for a cluster. * For this in initial implementation it simply returns title from a few tabs + * * @returns {string} * @private */ diff --git a/browser/components/tabbrowser/TabUnloader.sys.mjs b/browser/components/tabbrowser/TabUnloader.sys.mjs @@ -317,6 +317,7 @@ export var TabUnloader = { /** * Select and discard one tab. + * * @returns true if a tab was unloaded, otherwise false. */ async unloadLeastRecentlyUsedTab( diff --git a/browser/components/tabbrowser/TabsList.sys.mjs b/browser/components/tabbrowser/TabsList.sys.mjs @@ -513,6 +513,7 @@ export class TabsPanel extends TabsListBase { /** * Setting a new property `XulToolbarItem._tab` on the row elements * for internal use by this module only. + * * @see getTabFromRow */ row._tab = tab; @@ -529,6 +530,7 @@ export class TabsPanel extends TabsListBase { /** * Setting a new property `MozToolbarbutton.tab` on the buttons * to support tab context menu integration. + * * @see TabContextMenu.updateContextMenu */ button.tab = tab; @@ -587,6 +589,7 @@ export class TabsPanel extends TabsListBase { /** * Setting a new property `XulToolbarItem._tabGroup` on the row elements * for internal use by this module only. + * * @see getTabGroupFromRow */ row._tabGroup = group; diff --git a/browser/components/tabbrowser/content/browser-ctrlTab.js b/browser/components/tabbrowser/content/browser-ctrlTab.js @@ -20,6 +20,7 @@ var tabPreviews = { * to load. If the browser is discarded and there is no stored thumbnail, the * image URL will fail to load and this method will return null after 1s. * Callers should handle this case by doing nothing or using a fallback image. + * * @param {String} uri The page URL. * @returns {Promise<Image|null>} */ @@ -51,6 +52,7 @@ var tabPreviews = { * For a given tab, retrieve a preview thumbnail (a canvas or an image) from * storage or capture a new one. If the tab's URL has changed since the * previous call, the thumbnail will be regenerated. + * * @param {MozTabbrowserTab} aTab The tab to get a preview for. * @returns {Promise<HTMLCanvasElement|Image|null>} Resolves to... * @resolves {HTMLCanvasElement} If a thumbnail can NOT be captured and stored @@ -93,6 +95,7 @@ var tabPreviews = { /** * For a given tab, capture a preview thumbnail (a canvas), optionally cache * it in aTab.__thumbnail, and possibly store it in thumbnail storage. + * * @param {MozTabbrowserTab} aTab The tab to capture a preview for. * @param {Boolean} aShouldCache Cache/store the captured thumbnail? * @returns {Promise<HTMLCanvasElement|null>} Resolves to... diff --git a/browser/components/tabbrowser/content/browser-fullZoom.js b/browser/components/tabbrowser/content/browser-fullZoom.js @@ -635,6 +635,7 @@ var FullZoom = { /** * Returns the browser that the supplied zoom event is associated with. + * * @param event The zoom event. * @return The associated browser element, if one exists, otherwise null. */ diff --git a/browser/components/tabbrowser/content/tabbrowser.js b/browser/components/tabbrowser/content/tabbrowser.js @@ -807,6 +807,7 @@ /** * Get the findbar, and create it if it doesn't exist. + * * @return the find bar (or null if the window or tab is closed/closing in the interim). */ async getFindBar(aTab = this.selectedTab) { @@ -824,6 +825,7 @@ /** * Create a findbar instance. + * * @param aTab the tab to create the find bar for. * @return the created findbar, or null if the window or tab is closed/closing. */ @@ -2850,6 +2852,7 @@ /** * Must only be used sparingly for content that came from Chrome context * If in doubt use addWebTab + * * @param {string} aURI * @param {object} [options] * @see this.addTab options @@ -3187,6 +3190,7 @@ /** * Adds a new tab split view. + * * @param {object[]} tabs * The set of tabs to include in the split view. * @param {object} [options] @@ -4857,6 +4861,7 @@ * of how many tabs in the tab group will be left after removing `tabs`. * For any tab group with 0 surviving tabs, we can know that that tab * group will be removed as a consequence of removing these `tabs`. + * * @type {Map<MozTabbrowserTabGroup, Set<MozTabbrowserTab>>} */ let tabGroupSurvivingTabs = new Map(); @@ -5625,6 +5630,7 @@ /** * Handles opening a new tab with mouse middleclick. + * * @param node * @param event * The click event @@ -5649,6 +5655,7 @@ /** * Finds the tab that we will blur to if we blur aTab. + * * @param {MozTabbrowserTab} aTab * The tab we would blur * @param {MozTabbrowserTab[]} [aExcludeTabs=[]] @@ -9009,6 +9016,7 @@ * Handles URIs when we want to deal with them in chrome code rather than pass * them down to a content browser. This can avoid unnecessary process switching * for the browser. + * * @param aBrowser the browser that is attempting to load the URI * @param aUri the nsIURI that is being loaded * @returns true if the URI is handled, otherwise false diff --git a/browser/components/tabbrowser/content/tabgroup-menu.js b/browser/components/tabbrowser/content/tabgroup-menu.js @@ -805,6 +805,7 @@ /** * Check if the label should be updated with the suggested label + * * @returns {boolean} */ #shouldUpdateLabelWithMlLabel() { @@ -813,6 +814,7 @@ /** * Attempt to set the label of the group to the suggested label + * * @param {MozTabbrowserTabGroup} group * @param {string} newLabel * @returns @@ -1045,6 +1047,7 @@ /** * Set the state of the form to disabled or enabled + * * @param {boolean} state */ #setFormToDisabled(state) { @@ -1139,6 +1142,7 @@ /** * Sends Glean metrics if smart tab grouping is enabled + * * @param {string} action "save", "save-popup-hidden" or "cancel" */ #handleMlTelemetry(action) { @@ -1172,6 +1176,7 @@ /** * Sends Glean metrics for opt-in UI flow + * * @param {string} step contains step number and description of flow */ #handleMLOptinTelemetry(step) { @@ -1258,6 +1263,7 @@ /** * Unique state setter for a "3rd" panel state while in suggest Mode * that just shows suggestions and hides the majority of the panel + * * @param {boolean} value */ #setSuggestModeSuggestionState(value) { diff --git a/browser/components/tabbrowser/content/tabgroup.js b/browser/components/tabbrowser/content/tabgroup.js @@ -569,6 +569,7 @@ /** * Remove all tabs from the group and delete the group. + * * @param {TabMetricsContext} [metricsContext] */ ungroupTabs( diff --git a/browser/components/tabbrowser/test/browser/smarttabgrouping/browser_tab_grouping.js b/browser/components/tabbrowser/test/browser/smarttabgrouping/browser_tab_grouping.js @@ -108,6 +108,7 @@ add_task(async function testClustering() { /** * Run tests for finding similar items for a single item or cluster of items with label anchorLabel + * * @param {Number[][]} embeddings Embeddings for each item * @param {String} anchorLabel String representing the ID of the anchor cluster * @param {Object[]} labels Dict representing each document (unused ) diff --git a/browser/components/tabbrowser/test/browser/smarttabgrouping/browser_tab_grouping_utils.js b/browser/components/tabbrowser/test/browser/smarttabgrouping/browser_tab_grouping_utils.js @@ -6,6 +6,7 @@ /** * Generates a dummy tab with title, url and description + * * @param {string} title * @param {string} url * @param {string} description @@ -24,6 +25,7 @@ function generateTabWithInfo({ title, url, description = "" }) { /** * Returns a list of dummy tab data from an existing filename + * * @param {string} filename path to local file * @return {Promise<object[]>} list of tabs */ diff --git a/browser/components/tabbrowser/test/browser/tabMediaIndicator/head.js b/browser/components/tabbrowser/test/browser/tabMediaIndicator/head.js @@ -5,6 +5,7 @@ const gEMPTY_PAGE_URL = GetTestWebBasedURL("file_empty.html"); /** * Return a web-based URL for a given file based on the testing directory. + * * @param {String} fileName * file that caller wants its web-based url * @param {Boolean} cors [optional] @@ -22,6 +23,7 @@ function GetTestWebBasedURL(fileName, cors = false) { /** * Wait until tab sound indicator appears on the given tab. + * * @param {tabbrowser} tab * given tab where tab sound indicator should appear */ @@ -42,6 +44,7 @@ async function waitForTabSoundIndicatorAppears(tab) { /** * Wait until tab sound indicator disappears on the given tab. + * * @param {tabbrowser} tab * given tab where tab sound indicator should disappear */ @@ -62,6 +65,7 @@ async function waitForTabSoundIndicatorDisappears(tab) { /** * Return a new foreground tab loading with an empty file. + * * @param {boolean} needObserver * If true, sets an observer property on the returned tab. This property * exposes `hasEverUpdated()` which will return a bool indicating if the @@ -98,6 +102,7 @@ function createSoundIndicatorObserver(tab) { * Sythesize mouse hover on the given icon, which would sythesize `mouseover` * and `mousemove` event on that. Return a promise that will be resolved when * the tooptip element shows. + * * @param {tab icon} icon * the icon on which we want to mouse hover * @param {tooltip element} tooltip @@ -121,6 +126,7 @@ function hoverIcon(icon, tooltip) { /** * Leave mouse from the given icon, which would sythesize `mouseout` * and `mousemove` event on that. + * * @param {tab icon} icon * the icon on which we want to mouse hover * @param {tooltip element} tooltip @@ -143,6 +149,7 @@ function leaveIcon(icon) { /** * Sythesize mouse click on the given icon. + * * @param {tab icon} icon * the icon on which we want to mouse hover */ diff --git a/browser/components/tabbrowser/test/browser/tabs/browser_tabSpinnerProbe.js b/browser/components/tabbrowser/test/browser/tabs/browser_tabSpinnerProbe.js @@ -8,6 +8,7 @@ const MAX_HANG_TIME = 5 * 1000; // ms /** * Returns the sum of all values in an array. + * * @param {Array} aArray An array of integers * @return {Number} The sum of the integers in the array */ @@ -42,6 +43,7 @@ function hangContentProcess(browser, aMs) { /** * A generator intended to be run as a Task. It tests one of the tab spinner * telemetry probes. + * * @param {String} aProbe The probe to test. Should be: * - FX_TAB_SWITCH_SPINNER_VISIBLE_MS */ diff --git a/browser/components/tabbrowser/test/browser/tabs/browser_tab_manager_drag.js b/browser/components/tabbrowser/test/browser/tabs/browser_tab_manager_drag.js @@ -196,6 +196,7 @@ async function dropAfter(rowToDrag, rowToDropAfter, win) { /** * Virtually drag and drop one tabs list row before another. + * * @param {XulToolbarItem} rowToDrag * @param {XulToolbarItem} rowToDropBefore * @param {Window} win diff --git a/browser/extensions/newtab/content-src/components/DiscoveryStreamComponents/DSCard/DSCard.jsx b/browser/extensions/newtab/content-src/components/DiscoveryStreamComponents/DSCard/DSCard.jsx @@ -26,6 +26,7 @@ const PREF_FAVICONS_ENABLED = "discoverystream.publisherFavicon.enabled"; /** * READ TIME FROM WORD COUNT + * * @param {int} wordCount number of words in an article * @returns {int} number of words per minute in minutes */ diff --git a/browser/extensions/newtab/content-src/components/TopSites/TopSites.jsx b/browser/extensions/newtab/content-src/components/TopSites/TopSites.jsx @@ -32,6 +32,7 @@ function topSiteIconType(link) { /** * Iterates through TopSites and counts types of images. + * * @param acc Accumulator for reducer. * @param topsite Entry in TopSites. */ diff --git a/browser/extensions/newtab/content-src/lib/utils.jsx b/browser/extensions/newtab/content-src/lib/utils.jsx @@ -13,6 +13,7 @@ const PREF_SYSTEM_STORIES_ENABLED = "feeds.system.topstories"; * A custom react hook that sets up an IntersectionObserver to observe a single * or list of elements and triggers a callback when the element comes into the viewport * Note: The refs used should be an array type + * * @function useIntersectionObserver * @param {function} callback - The function to call when an element comes into the viewport * @param {Object} options - Options object passed to Intersection Observer: @@ -20,9 +21,6 @@ const PREF_SYSTEM_STORIES_ENABLED = "feeds.system.topstories"; * @param {Boolean} [isSingle = false] Boolean if the elements are an array or single element * * @returns {React.MutableRefObject} a ref containing an array of elements or single element - * - * - * */ function useIntersectionObserver(callback, threshold = 0.3) { const elementsRef = useRef([]); @@ -59,6 +57,7 @@ function useIntersectionObserver(callback, threshold = 0.3) { /** * Determines which column layout is active based on the screen width + * * @param {number} screenWidth - The current window width (in pixels) * @returns {string} The active column layout (e.g. "col-3", "col-2", "col-1") */ diff --git a/browser/extensions/newtab/data/content/activity-stream.bundle.js b/browser/extensions/newtab/data/content/activity-stream.bundle.js @@ -2553,6 +2553,7 @@ const PREF_SYSTEM_STORIES_ENABLED = "feeds.system.topstories"; * A custom react hook that sets up an IntersectionObserver to observe a single * or list of elements and triggers a callback when the element comes into the viewport * Note: The refs used should be an array type + * * @function useIntersectionObserver * @param {function} callback - The function to call when an element comes into the viewport * @param {Object} options - Options object passed to Intersection Observer: @@ -2560,9 +2561,6 @@ const PREF_SYSTEM_STORIES_ENABLED = "feeds.system.topstories"; * @param {Boolean} [isSingle = false] Boolean if the elements are an array or single element * * @returns {React.MutableRefObject} a ref containing an array of elements or single element - * - * - * */ function useIntersectionObserver(callback, threshold = 0.3) { const elementsRef = (0,external_React_namespaceObject.useRef)([]); @@ -2593,6 +2591,7 @@ function useIntersectionObserver(callback, threshold = 0.3) { /** * Determines which column layout is active based on the screen width + * * @param {number} screenWidth - The current window width (in pixels) * @returns {string} The active column layout (e.g. "col-3", "col-2", "col-1") */ @@ -3460,6 +3459,7 @@ const PREF_FAVICONS_ENABLED = "discoverystream.publisherFavicon.enabled"; /** * READ TIME FROM WORD COUNT + * * @param {int} wordCount number of words in an article * @returns {int} number of words per minute in minutes */ @@ -9754,6 +9754,7 @@ function topSiteIconType(link) { /** * Iterates through TopSites and counts types of images. + * * @param acc Accumulator for reducer. * @param topsite Entry in TopSites. */ diff --git a/browser/extensions/newtab/lib/AdsFeed.sys.mjs b/browser/extensions/newtab/lib/AdsFeed.sys.mjs @@ -168,6 +168,7 @@ export class AdsFeed { /** * Normalize new Unified Ads API response into * previous Contile ads response + * * @param {array} - Array of UAPI placement objects ("newtab_tile_1", etc.) * @returns {object} - Object containing array of formatted UAPI objects to match legacy Contile system */ @@ -200,6 +201,7 @@ export class AdsFeed { /** * Return object of supported ad types to query from MARS API from the AdsFeed file + * * @returns {object} */ getSupportedAdTypes() { @@ -218,6 +220,7 @@ export class AdsFeed { /** * Get ads data either from cache or from API and * broadcast the data via at.ADS_UPDATE_{DATA_TYPE} event + * * @param {boolean} isStartup=false - This is only used for reporting * and is passed to the update functions meta attribute * @returns {void} @@ -266,6 +269,7 @@ export class AdsFeed { /** * Fetch data from the Mozilla Ad Routing Service (MARS) unified ads API * This function is designed to get whichever ads types are needed (tiles, spocs) + * * @param {array} supportedAdTypes * @returns {object} Response object containing ad information from MARS */ @@ -418,6 +422,7 @@ export class AdsFeed { /** * Init function that runs only from onAction at.INIT call. + * * @param {boolean} isStartup=false * @returns {void} */ @@ -429,6 +434,7 @@ export class AdsFeed { /** * Sets cached data and dispatches at.ADS_UPDATE_{DATA_TYPE} event to update store with new ads data + * * @param {boolean} isStartup * @returns {void} */ diff --git a/browser/extensions/newtab/lib/DiscoveryStreamFeed.sys.mjs b/browser/extensions/newtab/lib/DiscoveryStreamFeed.sys.mjs @@ -557,6 +557,7 @@ export class DiscoveryStreamFeed { /** * Returns true if data in the cache for a particular key has expired or is missing. + * * @param {object} cachedData data returned from cache.get() * @param {string} key a cache key * @param {string?} url for "feed" only, the URL of the feed. diff --git a/browser/extensions/newtab/lib/HighlightsFeed.sys.mjs b/browser/extensions/newtab/lib/HighlightsFeed.sys.mjs @@ -110,6 +110,7 @@ export class HighlightsFeed { /** * Chronologically sort highlights of all types except 'visited'. Then just append * the rest at the end of highlights. + * * @param {Array} pages The full list of links to order. * @return {Array} A sorted array of highlights */ @@ -130,6 +131,7 @@ export class HighlightsFeed { /** * Refresh the highlights data for content. + * * @param {bool} options.broadcast Should the update be broadcasted. */ async fetchHighlights(options = {}) { diff --git a/browser/extensions/newtab/lib/InferredModel/FeatureModel.sys.mjs b/browser/extensions/newtab/lib/InferredModel/FeatureModel.sys.mjs @@ -19,6 +19,7 @@ const MAX_INT_32 = 2 ** 32; /** * Divides numerator fields by the denominator. Value is set to 0 if denominator is missing or 0. * Adds 0 value for all situations where there is a denominator but no numerator value. + * * @param {Object.<string, number>} numerator * @param {Object.<string, number>} denominator * returns {Object.<string, number>} @@ -39,6 +40,7 @@ export function divideDict(numerator, denominator) { /** * Unary encoding with randomized response for differential privacy. * The output must be decoded to back to an integer when aggregating a historgram on a server + * * @param {number} x - Integer input (0 <= x < N) * @param {number} N - Number of values (see ablove) * @param {number} p - Probability of keeping a 1-bit as 1 (after one-hot encoding the output) @@ -63,6 +65,7 @@ export function unaryEncodeDiffPrivacy(x, N, p, q) { /** * Adds value to all a particular key in a dictionary. If the key is missing it sets the value. + * * @param {Object} dict - The dictionary to modify. * @param {string} key - The key whose value should be added or set. * @param {number} value - The value to add to the key. @@ -77,6 +80,7 @@ export function dictAdd(dict, key, value) { /** * Apply function to all keys in dictionary, returning new dictionary. + * * @param {Object} obj - The object whose values should be transformed. * @param {Function} fn - The function to apply to each value. * @returns {Object} A new object with the transformed values. @@ -93,6 +97,7 @@ export function dictApply(obj, fn) { export class DayTimeWeighting { /** * Instantiate class based on a series of day periods in the past. + * * @param {int[]} pastDays Series of number of days, indicating days ago intervals in reverse chonological order. * Intervals are added: If the first value is 1 and the second is 5, then the first inteval is 0-1 and second interval is between 1 and 6. * @param {number[]} relativeWeight Relative weight of each period. Must be same length as pastDays @@ -108,6 +113,7 @@ export class DayTimeWeighting { /** * Get a series of interval pairs in the past based on the pastDays. + * * @param {number} curTimeMs Base time time in MS. Usually current time. * @returns */ @@ -126,6 +132,7 @@ export class DayTimeWeighting { /** * Get relative weight of current index. + * * @param {int} weightIndex Index * @returns {number} Weight at index, or 0 if index out of range. */ @@ -168,6 +175,7 @@ export class InterestFeatures { /** * Quantize a feature value based on the thresholds specified in the class. + * * @param {number} inValue Value computed by model for the feature. * @returns Quantized value. A value between 0 and number of thresholds specified (inclusive) */ @@ -187,6 +195,7 @@ export class InterestFeatures { * Applies Differential Privacy Unary Encoding method, outputting a one-hot encoded vector with randomizaiton. * Accurate historgrams of values can be computed with reasonable accuracy. * If the class has no or 0 p/q values set for differential privacy, then response is original number non-encoded. + * * @param {number} inValue Value to randomize * @returns Bitfield as a string, that is the same as the thresholds length + 1 */ @@ -311,6 +320,7 @@ export class FeatureModel { /** * Computes an interest vector or aggregate based on the model and raw sql inout. + * * @param {Object} config * @param {Array.<Array.<string|number>>} config.dataForIntervals Raw aggregate output from SQL query. Could be clicks or impressions * @param {Object.<string, number>} config.indexSchema Map of keys to indices in each sub-array in dataForIntervals diff --git a/browser/extensions/newtab/lib/InferredPersonalizationFeed.sys.mjs b/browser/extensions/newtab/lib/InferredPersonalizationFeed.sys.mjs @@ -99,6 +99,7 @@ export class InferredPersonalizationFeed { /** * Get Inferrred model raw data + * * @returns JSON of inferred model */ async getInferredModelData() { @@ -305,6 +306,7 @@ export class InferredPersonalizationFeed { /** * Deletes older data from a table + * * @param {int} preserveAgeDays Number of days to preserve * @param {*} table Table to clear */ @@ -325,6 +327,7 @@ export class InferredPersonalizationFeed { /** * Deletes older data from impression and click tables + * * @param {int} preserveAgeDays Number of days to preserve (defaults to 6 months) */ async clearOldData(preserveAgeDays) { diff --git a/browser/extensions/newtab/lib/NewTabAttributionService.sys.mjs b/browser/extensions/newtab/lib/NewTabAttributionService.sys.mjs @@ -217,6 +217,7 @@ export class NewTabAttributionService { /** * findImpression queries the local events to find an attributable event. + * * @param {string} partnerId - Partner the event must be associated with. * @param {number} lookbackDays - Maximum number of days ago that the event occurred for it to * be eligible. @@ -256,6 +257,7 @@ export class NewTabAttributionService { * getImpression searches existing events for the partner and retuns the event * if it is found, defaulting to the passed in impression if there are none. This * enables timestamp fields of the stored event to be updated or carried forward. + * * @param {ObjectStore} impressionStore - Promise-based wrapped IDBObjectStore. * @param {string} partnerId - partner this event is associated with. * @param {impression} defaultImpression - event to use if it has not been seen previously. @@ -276,6 +278,7 @@ export class NewTabAttributionService { /** * updateImpression stores the passed event, either updating the record * if this event was already seen, or appending to the list of events if it is new. + * * @param {ObjectStore} impressionStore - Promise-based wrapped IDBObjectStore. * @param {string} partnerId - partner this event is associated with. * @param {impression} impression - event to update. @@ -333,6 +336,7 @@ export class NewTabAttributionService { /** * updateBudget updates the stored budget to indicate some has been used. + * * @param {budget} budget - current budget to be modified. * @param {number} value - amount of budget that has been used. * @param {string} partnerId - partner this budget is for. diff --git a/browser/extensions/newtab/lib/NewTabContentPing.sys.mjs b/browser/extensions/newtab/lib/NewTabContentPing.sys.mjs @@ -38,6 +38,7 @@ export class NewTabContentPing { /** * Set the maximum number of events to send in a 24 hour period + * * @param {int} maxEvents */ setMaxEventsPerDay(maxEvents) { @@ -106,6 +107,7 @@ export class NewTabContentPing { /** * Randomly shuffles the elements of an array in place using the Fisher–Yates algorithm. + * * @param {Array} array - The array to shuffle. This array will be modified. * @returns {Array} The same array instance, shuffled randomly. */ @@ -229,6 +231,7 @@ export class NewTabContentPing { /** * Returns a secure random number between 0 and range + * * @param {int} range Integer value range * @returns {int} Random value between 0 and range non-inclusive */ @@ -252,6 +255,7 @@ export class NewTabContentPing { /** * Returns true or false with a certain proability specified + * * @param {Number} prob Probability * @returns {boolean} Random boolean result of probability prob */ diff --git a/browser/extensions/newtab/lib/NewTabGleanUtils.sys.mjs b/browser/extensions/newtab/lib/NewTabGleanUtils.sys.mjs @@ -120,6 +120,7 @@ export const NewTabGleanUtils = { /** * Registers a metric in Glean if it doesn't already exist. + * * @param {Object} options - The metric configuration options * @param {string} options.type - The type of metric (e.g., "text", "counter") * @param {string} options.category - The category the metric belongs to @@ -181,6 +182,7 @@ export const NewTabGleanUtils = { /** * Registers a ping in Glean if it doesn't already exist. + * * @param {Object} options - The ping configuration options * @param {string} options.name - The name of the ping * @param {boolean} [options.includeClientId] - Whether to include client ID @@ -245,6 +247,7 @@ export const NewTabGleanUtils = { /** * Converts a dotted snake case string to camel case. * Example: "foo.bar_baz" becomes "fooBarBaz" + * * @param {string} metricNameOrCategory - The string in dotted snake case format * @returns {string} The converted camel case string */ @@ -279,6 +282,7 @@ export const NewTabGleanUtils = { /** * Converts a kebab case string to camel case. * Example: "foo-bar-baz" becomes "fooBarBaz" + * * @param {string} pingName - The string in kebab case format * @returns {string} The converted camel case string */ diff --git a/browser/extensions/newtab/lib/NewTabMessaging.sys.mjs b/browser/extensions/newtab/lib/NewTabMessaging.sys.mjs @@ -103,6 +103,7 @@ export class NewTabMessaging { /** * Send impression to ASRouter + * * @param {Object} message */ handleImpression(message) { diff --git a/browser/extensions/newtab/lib/PlacesFeed.sys.mjs b/browser/extensions/newtab/lib/PlacesFeed.sys.mjs @@ -293,6 +293,7 @@ export class PlacesFeed { /** * Sends an attribution request for Top Sites interactions. + * * @param {object} data * Attribution paramters from a Top Site. */ diff --git a/browser/extensions/newtab/lib/SmartShortcutsRanker/RankShortcuts.mjs b/browser/extensions/newtab/lib/SmartShortcutsRanker/RankShortcuts.mjs @@ -585,6 +585,7 @@ export async function fetchHourlyVisitsAll(table) { /** * Build weights object only for the requested features. + * * @param {object} prefValues - contains trainhopConfig.smartShortcuts * @param {string[]} features - e.g. ["thom","frec"] (bias optional) */ diff --git a/browser/extensions/newtab/lib/TelemetryFeed.sys.mjs b/browser/extensions/newtab/lib/TelemetryFeed.sys.mjs @@ -298,6 +298,7 @@ export class TelemetryFeed { /** * Retrieves most recently followed sections (maximum 2 sections) + * * @returns {String[]} comma separated string of section UUID's */ getFollowedSections() { @@ -385,6 +386,7 @@ export class TelemetryFeed { /** * Removes fields that link to any user content preference. * Redactions only occur if the appropriate pref is enabled. + * * @param {*} pingDict Input dictionary * @param {boolean} isSponsored Is this in ad, in which case there is nothing we can redact currently * @returns {*} Possibly redacted dictionary @@ -801,6 +803,7 @@ export class TelemetryFeed { /** * Occasionally replaces a content item with another that is in the feed. + * * @param {*} item * @returns Same item, but another item occasionally based on probablility setting. * Sponsored items are unchanged @@ -1965,7 +1968,6 @@ export class TelemetryFeed { * * @param {String} port The session port with which this is associated * @param {Object} data The impression data structured as {source: "SOURCE", tiles: [{id: 123}]} - * */ handleDiscoveryStreamImpressionStats(port, data) { let session = this.sessions.get(port); diff --git a/browser/extensions/newtab/lib/TopSitesFeed.sys.mjs b/browser/extensions/newtab/lib/TopSitesFeed.sys.mjs @@ -1656,6 +1656,7 @@ export class TopSitesFeed { /** * Refresh the top sites data for content. + * * @param {bool} options.broadcast Should the update be broadcasted. * @param {bool} options.isStartup Being called while TopSitesFeed is initting. */ @@ -1798,6 +1799,7 @@ export class TopSitesFeed { /** * Fetch, cache and broadcast a screenshot for a specific topsite. + * * @param link cached topsite object * @param url where to fetch the image from * @param isStartup Whether the screenshot is fetched while initting TopSitesFeed. @@ -1829,6 +1831,7 @@ export class TopSitesFeed { /** * Dispatch screenshot preview to target or notify if request failed. + * * @param customScreenshotURL {string} The URL used to capture the screenshot * @param target {string} Id of content process where to dispatch the result */ @@ -1865,6 +1868,7 @@ export class TopSitesFeed { /** * Pin a site at a specific position saving only the desired keys. + * * @param customScreenshotURL {string} User set URL of preview image for site * @param label {string} User set string of custom site name */ diff --git a/browser/extensions/newtab/test/browser/browser_highlights_section.js b/browser/extensions/newtab/test/browser/browser_highlights_section.js @@ -8,6 +8,7 @@ add_setup(async function () { /** * Helper for setup and cleanup of Highlights section tests. + * * @param bookmarkCount Number of bookmark higlights to add * @param test The test case */ diff --git a/browser/extensions/newtab/test/browser/head.js b/browser/extensions/newtab/test/browser/head.js @@ -105,6 +105,7 @@ function clearHighlightsBookmarks() { /** * Helper to populate the Highlights section with bookmark cards. + * * @param count Number of items to add. */ async function addHighlightsBookmarks(count) { diff --git a/browser/modules/BrowserUsageTelemetry.sys.mjs b/browser/modules/BrowserUsageTelemetry.sys.mjs @@ -1253,6 +1253,7 @@ export let BrowserUsageTelemetry = { /** * Adds listeners to a single chrome window. + * * @param {Window} win */ _registerWindow(win) { @@ -1307,6 +1308,7 @@ export let BrowserUsageTelemetry = { /** * Updates the tab counts. + * * @param {CustomEvent} [event] * `TabOpen` event */ @@ -1712,6 +1714,7 @@ export let BrowserUsageTelemetry = { /** * Tracks the window count and registers the listeners for the tab count. + * * @param{Object} win The window object. */ _onWindowOpen(win) { diff --git a/browser/modules/BrowserWindowTracker.sys.mjs b/browser/modules/BrowserWindowTracker.sys.mjs @@ -431,6 +431,7 @@ export const BrowserWindowTracker = { /** * Array of browser windows ordered by z-index, in reverse order. * This means that the top-most browser window will be the first item. + * * @param {object} options * @param {boolean} [options.private] * If set, returns only windows with the specified privateness. i.e. `true` diff --git a/browser/modules/PopupAndRedirectBlockerObserver.sys.mjs b/browser/modules/PopupAndRedirectBlockerObserver.sys.mjs @@ -37,6 +37,7 @@ export var PopupAndRedirectBlockerObserver = { /** * Handles a "DOMUpdateBlockedPopups" or "DOMUpdateBlockedRedirect" event * received from the JSWindowActorParent. + * * @param {*} aEvent */ onDOMUpdateBlockedPopupsAndRedirect(aEvent) { @@ -132,6 +133,7 @@ export var PopupAndRedirectBlockerObserver = { /** * Event handler that is triggered when a user clicks on the "options" * button in the notification which opens a popup. + * * @param {*} aEvent */ async onPopupShowing(aEvent) { @@ -263,6 +265,7 @@ export var PopupAndRedirectBlockerObserver = { /** * Event handler that is triggered when the "options" popup of the * notification closes. + * * @param {*} aEvent */ onPopupHiding(aEvent) { @@ -296,6 +299,7 @@ export var PopupAndRedirectBlockerObserver = { /** * Event handler that is triggered when a user clicks on one of the * fields in the "options" popup of the notification. + * * @param {*} aEvent */ onCommand(aEvent) { diff --git a/browser/modules/Sanitizer.sys.mjs b/browser/modules/Sanitizer.sys.mjs @@ -1179,6 +1179,7 @@ function extractMatchingPrincipals(principals, matchHost) { /** * This method receives a list of principals and it checks if some of them or * some of their sub-domain need to be sanitize. + * * @param {Object} progress - Object to keep track of the sanitization progress, prefs and mode * @param {nsIPrincipal[]} principals - The principals generated by the PrincipalsCollector * @param {int} flags - The cleaning categories that need to be cleaned for the principals. @@ -1252,6 +1253,7 @@ function cookiesAllowedForDomainOrSubDomain(principal, permissions) { /** * Checks if a cookie permission is set for a given principal + * * @returns {boolean} - true: cookie permission "ACCESS_ALLOW", false: cookie permission "ACCESS_DENY"/"ACCESS_SESSION" * @returns {null} - No cookie permission is set for this principal */ @@ -1306,6 +1308,7 @@ function sanitizeNewTabSegregation() { /** * Gets an array of items to clear from the given pref branch. + * * @param branch The pref branch to fetch. * @return Array of items to clear */ @@ -1323,6 +1326,7 @@ function getItemsToClearFromPrefBranch(branch) { /** * These functions are used to track pending sanitization on the next startup * in case of a crash before a sanitization could happen. + * * @param id A unique id identifying the sanitization * @param itemsToClear The items to clear * @param options The Sanitize options diff --git a/browser/modules/SiteDataManager.sys.mjs b/browser/modules/SiteDataManager.sys.mjs @@ -68,6 +68,7 @@ export var SiteDataManager = { /** * Get the base domain of a host on a best-effort basis. + * * @param {string} host - Host to convert. * @returns {string} Computed base domain. If the base domain cannot be * determined, because the host is an IP address or does not have enough diff --git a/browser/modules/SitePermissions.sys.mjs b/browser/modules/SitePermissions.sys.mjs @@ -61,6 +61,7 @@ const TemporaryPermissions = { /** * Generate keys to store temporary permissions under. The strict key is * origin, non-strict is baseDomain. + * * @param {nsIPrincipal} principal - principal to derive keys from. * @returns {Object} keys - Object containing the generated permission keys. * @returns {string} keys.strict - Key to be used for strict matching. @@ -74,6 +75,7 @@ const TemporaryPermissions = { /** * Sets a new permission for the specified browser. + * * @returns {boolean} whether the permission changed, effectively. */ set( @@ -159,6 +161,7 @@ const TemporaryPermissions = { /** * Removes a permission with the specified id for the specified browser. + * * @returns {boolean} whether the permission was removed. */ remove(browser, id) { @@ -264,6 +267,7 @@ const TemporaryPermissions = { * Clear temporary permissions for the specified browser. Unlike other * methods, this does NOT clear only for the currentURI but the whole browser * state. + * * @param {Browser} browser - Browser to clear permissions for. * @param {Number} [filterState] - Only clear permissions with the given state * value. Defaults to all permissions. @@ -592,6 +596,7 @@ export var SitePermissions = { /** * Checks whether we support managing permissions for a specific scheme. + * * @param {string} scheme - Scheme to test. * @returns {boolean} Whether the scheme is supported. */ @@ -613,6 +618,7 @@ export var SitePermissions = { /** * Test whether a permission is managed by SitePermissions. + * * @param {string} type - Permission type. * @returns {boolean} */ diff --git a/browser/modules/test/browser/head.js b/browser/modules/test/browser/head.js @@ -43,6 +43,7 @@ function waitForCondition(condition, nextTest, errorMsg) { /** * An utility function to write some text in the search input box * in a content page. + * * @param {Object} browser * The browser that contains the content. * @param {String} text diff --git a/browser/modules/webrtcUI.sys.mjs b/browser/modules/webrtcUI.sys.mjs @@ -597,6 +597,7 @@ export var webrtcUI = { /** * Clears permissions and stops sharing (if active) for a list of device types * and a specific tab. + * * @param {("camera"|"microphone"|"screen")[]} types - Device types to stop * and clear permissions for. * @param tab - Tab of the devices to stop and clear permissions. @@ -700,6 +701,7 @@ export var webrtcUI = { * child frames. * Note: activePerms is an internal WebRTC UI permission map and does not * reflect the PermissionManager or SitePermissions state. + * * @param aBrowser - Browser to clear active permissions for. */ forgetActivePermissionsFromBrowser(aBrowser) { @@ -714,6 +716,7 @@ export var webrtcUI = { /** * Shows the Permission Panel for the tab associated with the provided * active stream. + * * @param aActiveStream - The stream that the user wants to see permissions for. * @param aEvent - The user input event that is invoking the panel. This can be * undefined / null if no such event exists. diff --git a/devtools/client/aboutdebugging/test/browser/helper-addons.js b/devtools/client/aboutdebugging/test/browser/helper-addons.js @@ -107,6 +107,7 @@ function createTemporaryXPI(xpiData) { /** * Remove the existing temporary XPI file generated by ExtensionTestCommon and create a * new one at the same location. + * * @return {File} the temporary extension XPI file created */ function updateTemporaryXPI(xpiData, existingXPI) { @@ -130,6 +131,7 @@ function updateTemporaryXPI(xpiData, existingXPI) { /** * Install a fake temporary extension by creating a temporary in-memory XPI file. + * * @return {File} the temporary extension XPI file created */ async function installTemporaryExtensionFromXPI(xpiData, document) { diff --git a/devtools/client/aboutdebugging/test/browser/helper-mocks.js b/devtools/client/aboutdebugging/test/browser/helper-mocks.js @@ -132,6 +132,7 @@ class Mocks { /** * Creates a USB runtime for which a client conenction can be established. + * * @param {String} id * The id of the runtime. * @param {Object} optional object used to create the fake runtime & device diff --git a/devtools/client/accessibility/accessibility-proxy.js b/devtools/client/accessibility/accessibility-proxy.js @@ -184,6 +184,7 @@ class AccessibilityProxy { /** * Look up accessibility fronts (get an existing one or create a new one) for * all existing target fronts and run a task with each one of them. + * * @param {Function} task * Function to execute with each accessiblity front. */ @@ -210,6 +211,7 @@ class AccessibilityProxy { * Look up accessibility walker fronts (get an existing one or create a new * one using accessibility front) for all existing target fronts and run a * task with each one of them. + * * @param {Function} task * Function to execute with each accessiblity walker front. */ @@ -242,6 +244,7 @@ class AccessibilityProxy { /** * Start picking and add walker listeners. + * * @param {Boolean} doFocus * If true, move keyboard focus into content. */ diff --git a/devtools/client/accessibility/actions/accessibles.js b/devtools/client/accessibility/actions/accessibles.js @@ -12,6 +12,7 @@ const { /** * Fetch child accessibles for a given accessible object. + * * @param {Object} accessible front */ exports.fetchChildren = diff --git a/devtools/client/accessibility/components/AccessibilityRow.js b/devtools/client/accessibility/components/AccessibilityRow.js @@ -201,6 +201,7 @@ class AccessibilityRow extends Component { /** * Scroll the node that corresponds to a current accessible object into view. + * * @param {Object} * Accessible front that is rendered for this node. * @@ -288,6 +289,7 @@ class AccessibilityRow extends Component { /** * Render accessible row component. + * * @returns acecssible-row React component. */ render() { diff --git a/devtools/client/accessibility/components/AccessibilityTree.js b/devtools/client/accessibility/components/AccessibilityTree.js @@ -127,6 +127,7 @@ class AccessibilityTree extends Component { * Handle accessible reorder event. If the accessible is cached and rendered * within the accessibility tree, re-fetch its children and re-render the * corresponding subtree. + * * @param {Object} accessibleFront * accessible front that had its subtree reordered. */ @@ -159,6 +160,7 @@ class AccessibilityTree extends Component { * Handle accessible name change event. If the name of an accessible changes * and that accessible is cached and rendered within the accessibility tree, * re-fetch its parent's children and re-render the corresponding subtree. + * * @param {Object} accessibleFront * accessible front that had its name changed. * @param {Object} parentFront @@ -184,6 +186,7 @@ class AccessibilityTree extends Component { * an accessible changes and that accessible is cached and rendered within the * accessibility tree, re-fetch its children and re-render the corresponding * subtree. + * * @param {Object} accessibleFront * accessible front that had its child text changed. */ diff --git a/devtools/client/accessibility/components/Accessible.js b/devtools/client/accessibility/components/Accessible.js @@ -400,6 +400,7 @@ class Accessible extends Component { /** * Match accessibility object from relations targets to the grip that's being activated. + * * @param {Object} relations Object containing relations grouped by type and targets. * @param {String} actorID Actor ID to match to the relation target. * @return {Object} Accessible front that matches the relation target. @@ -420,6 +421,7 @@ const findAccessibleTarget = (relations, actorID) => { /** * Find an item based on a given path. + * * @param {String} path * Key of the item to be looked up. * @param {Array} items @@ -443,6 +445,7 @@ const findByPath = (path, items) => { /** * Check if a given property is a DOMNode front. + * * @param {Object?} value A property to check for being a DOMNode. * @return {Boolean} A flag that indicates whether a property is a DOMNode. */ @@ -450,6 +453,7 @@ const isNodeFront = value => value && value.typeName === "domnode"; /** * Check if a given property is an Accessible front. + * * @param {Object?} value A property to check for being an Accessible. * @return {Boolean} A flag that indicates whether a property is an Accessible. */ @@ -482,6 +486,7 @@ const translateNodeFrontToGripWrapper = nodeFront => ({ /** * Build props ingestible by VirtualizedTree component. + * * @param {Object} props Component properties to be processed. * @param {String} parentPath Unique path that is used to identify a Tree Node. * @return {Object} Processed properties. diff --git a/devtools/client/accessibility/components/AuditProgressOverlay.js b/devtools/client/accessibility/components/AuditProgressOverlay.js @@ -16,6 +16,7 @@ const Localized = React.createFactory(FluentReact.Localized); /** * Helper functional component to render an accessible text progressbar. + * * @param {Object} props * - id for the progressbar element * - fluentId: localized string id diff --git a/devtools/client/accessibility/picker.js b/devtools/client/accessibility/picker.js @@ -48,6 +48,7 @@ class Picker { /** * Select accessible object in the tree. + * * @param {Object} accessible * Accessiblle object to be selected in the inspector tree. */ @@ -57,6 +58,7 @@ class Picker { /** * Highlight accessible object in the tree. + * * @param {Object} accessible * Accessiblle object to be selected in the inspector tree. */ @@ -83,6 +85,7 @@ class Picker { /** * Handle an event when a new accessible object is hovered over. + * * @param {Object} accessible * newly hovered accessible object */ @@ -95,6 +98,7 @@ class Picker { /** * Handle an event when a new accessible is picked by the user. + * * @param {Object} accessible * newly picked accessible object */ @@ -107,6 +111,7 @@ class Picker { /** * Handle an event when a new accessible is previewed by the user. + * * @param {Object} accessible * newly previewed accessible object */ @@ -149,6 +154,7 @@ class Picker { /** * Start picking. + * * @param {Boolean} doFocus * If true, move keyboard focus into content. */ @@ -174,6 +180,7 @@ class Picker { /** * Toggle between starting and canceling the picker. + * * @param {Boolean} doFocus * If true, move keyboard focus into content. */ diff --git a/devtools/client/accessibility/provider.js b/devtools/client/accessibility/provider.js @@ -10,6 +10,7 @@ const { /** * Data provider that is responsible for mapping of an accessibles cache to the * data format that is supported by the TreeView component. + * * @param {Map} accessibles accessibles object cache * @param {Function} dispatch react dispatch function that triggers a redux * action. @@ -25,6 +26,7 @@ class Provider { /** * Get accessible's cached children if available, if not fetch them from * backend. + * * @param {Object} accessible accessible object whose children to get. * @returns {Array} arraof of accessible children. */ @@ -43,6 +45,7 @@ class Provider { /** * Return a flag indicating if an accessible object has any children. + * * @param {Object} accessible accessible object whose children to get. * @returns {Boolean} idicator of whether accessible object has children. */ @@ -54,6 +57,7 @@ class Provider { * Get a value for an accessible object. Used to render the second (value) * column of the accessible tree. Corresponds to an accesible object name, if * available. + * * @param {Object} accessible accessible object * @returns {String} accessible object value. */ @@ -64,6 +68,7 @@ class Provider { /** * Get a label for an accessible object. Used to render the first column of * the accessible tree. Corresponds to an accessible object role. + * * @param {Object} accessible accessible object * @returns {String} accessible object label. */ @@ -74,6 +79,7 @@ class Provider { /** * Get a unique key for an accessible object. Corresponds to an accessible * front's actorID. + * * @param {Object} accessible accessible object * @returns {String} a key for an accessible object. */ @@ -84,6 +90,7 @@ class Provider { /** * Get a type of an accesible object. Corresponds to the type of an accessible * front. + * * @param {Object} accessible accessible object * @returns {String} accessible object type */ diff --git a/devtools/client/accessibility/reducers/accessibles.js b/devtools/client/accessibility/reducers/accessibles.js @@ -44,6 +44,7 @@ function getActorID(accessible) { /** * If accessible is cached recursively remove all its children and remove itself * from cache. + * * @param {Map} cache Previous state maintaining a cache of previously * fetched accessibles. * @param {Object} accessible Accessible object to remove from cache. @@ -66,6 +67,7 @@ function cleanupChild(cache, accessible) { * Determine if accessible in cache is stale. Accessible object is stale if its * cached children array has the size other than the value of its childCount * property that updates on accessible actor event. + * * @param {Map} cache Previous state maintaining a cache of previously * fetched accessibles. * @param {Object} accessible Accessible object to test for staleness. @@ -111,6 +113,7 @@ function updateAncestry(cache, ancestry) { /** * Handles fetching of accessible children. + * * @param {Map} cache Previous state maintaining a cache of previously * fetched accessibles. * @param {Object} action Redux action object. diff --git a/devtools/client/accessibility/reducers/details.js b/devtools/client/accessibility/reducers/details.js @@ -31,6 +31,7 @@ function details(state = getInitialState(), action) { /** * Handle details update for an accessible object + * * @param {Object} state Current accessible object details. * @param {Object} action Redux action object * @return {Object} updated state diff --git a/devtools/client/accessibility/reducers/ui.js b/devtools/client/accessibility/reducers/ui.js @@ -142,6 +142,7 @@ function onSelect(state, { accessible, response: ancestry, error }) { /** * Handle "canBeDisabled" flag update for accessibility service + * * @param {Object} state Current ui state * @param {Object} action Redux action object * @return {Object} updated state @@ -152,6 +153,7 @@ function onCanBeDisabledChange(state, { canBeDisabled }) { /** * Handle "canBeEnabled" flag update for accessibility service + * * @param {Object} state Current ui state. * @param {Object} action Redux action object * @return {Object} updated state @@ -162,6 +164,7 @@ function onCanBeEnabledChange(state, { canBeEnabled }) { /** * Handle pref update for accessibility panel. + * * @param {Object} state Current ui state. * @param {Object} action Redux action object * @return {Object} updated state @@ -175,6 +178,7 @@ function onPrefChange(state, { name, value }) { /** * Handle reset action for the accessibility panel UI. + * * @param {Object} state Current ui state. * @param {Object} action Redux action object * @return {Object} updated state @@ -193,6 +197,7 @@ function onReset(state, { enabled, canBeDisabled, canBeEnabled, supports }) { /** * Handle accessibilty service enabling/disabling. + * * @param {Object} state Current accessibility services enabled state. * @param {Object} action Redux action object * @param {Boolean} enabled New enabled state. diff --git a/devtools/client/accessibility/test/browser/head.js b/devtools/client/accessibility/test/browser/head.js @@ -83,6 +83,7 @@ const EXPANDABLE_PROPS = ["actions", "states", "attributes"]; /** * Add a new test tab in the browser and load the given url. + * * @param {String} url * The url to be loaded in the new tab * @param {Object} options @@ -144,6 +145,7 @@ async function initAccessibilityPanel(tab = gBrowser.selectedTab) { /** * Compare text within the list of potential badges rendered for accessibility * tree row when its accessible object has accessibility failures. + * * @param {DOMNode} badges * Container element that contains badge elements. * @param {Array|null} expected @@ -200,6 +202,7 @@ function isVisible(element) { /** * Check selected styling and visibility for a given row in the accessibility * tree. + * * @param {DOMNode} row * DOMNode for a given accessibility row. * @param {Boolean} expected @@ -222,6 +225,7 @@ function checkSelected(row, expected) { /** * Check level for a given row in the accessibility tree. + * * @param {DOMNode} row * DOMNode for a given accessibility row. * @param {Boolean} expected @@ -240,6 +244,7 @@ function checkLevel(row, expected) { /** * Check the state of the accessibility tree. + * * @param {document} doc panel documnent. * @param {Array} expected an array that represents an expected row list. */ @@ -269,6 +274,7 @@ async function checkTreeState(doc, expected) { /** * Check if relations object matches what is expected. Note: targets are matched by their * name and role. + * * @param {Object} relations Relations to test. * @param {Object} expected Expected relations. * @return {Boolean} True if relation types and their targers match what is @@ -301,6 +307,7 @@ function relationsMatch(relations, expected) { /** * When comparing numerical values (for example contrast), we only care about the 2 * decimal points. + * * @param {String} _ * Key of the property that is parsed. * @param {Any} value @@ -318,6 +325,7 @@ function parseNumReplacer(_, value) { /** * Check the state of the accessibility sidebar audit(checks). + * * @param {Object} store React store for the panel (includes store for * the audit). * @param {Object} expectedState Expected state of the sidebar audit(checks). @@ -348,6 +356,7 @@ async function checkAuditState(store, expectedState) { /** * Check the state of the accessibility sidebar. + * * @param {Object} store React store for the panel (includes store for * the sidebar). * @param {Object} expectedState Expected state of the sidebar. @@ -383,6 +392,7 @@ async function checkSidebarState(store, expectedState) { /** * Check the state of the accessibility related prefs. + * * @param {Document} doc * accessibility inspector panel document. * @param {Object} toolbarPrefValues @@ -420,6 +430,7 @@ async function checkToolbarPrefsState(doc, toolbarPrefValues, store) { /** * Check the state of the accessibility checks toolbar. + * * @param {Object} store * React store for the panel (includes store for the sidebar). * @param {Object} activeToolbarFilters @@ -444,6 +455,7 @@ async function checkToolbarState(doc, activeToolbarFilters) { /** * Check the state of the simulation button and menu components. + * * @param {Object} doc Panel document. * @param {Object} toolboxDoc Toolbox document. * @param {Object} expected Expected states of the simulation components: @@ -518,6 +530,7 @@ async function focusAccessibleProperties(doc) { /** * Select accessibility property in the sidebar. + * * @param {Document} doc accessibility inspector panel document. * @param {String} id id of the property to be selected. * @return {DOMNode} Node that corresponds to the selected accessibility property. @@ -556,6 +569,7 @@ async function selectProperty(doc, id) { /** * Select tree row. + * * @param {document} doc panel documnent. * @param {Number} rowNumber number of the row/tree node to be selected. */ @@ -575,6 +589,7 @@ function selectRow(doc, rowNumber) { /** * Toggle an expandable tree row. + * * @param {document} doc panel documnent. * @param {Number} rowNumber number of the row/tree node to be toggled. */ @@ -603,6 +618,7 @@ async function toggleRow(doc, rowNumber) { /** * Toggle a specific menu item based on its index in the menu. + * * @param {document} toolboxDoc * toolbox document. * @param {document} doc @@ -720,6 +736,7 @@ async function selectAccessibleForNode(env, selector) { /** * Iterate over setups/tests structure and test the state of the * accessibility panel. + * * @param {JSON} tests * test data that has the format of: * { @@ -787,6 +804,7 @@ async function runA11yPanelTests(tests, env) { /** * Build a valid URL from an HTML snippet. + * * @param {String} uri HTML snippet * @param {Object} options options for the test * @return {String} built URL @@ -812,6 +830,7 @@ function buildURL(uri, options = {}) { /** * Add a test task based on the test structure and a test URL. + * * @param {JSON} tests test data that has the format of: * { * desc {String} description for better logging @@ -832,6 +851,7 @@ function addA11yPanelTestsTask(tests, uri, msg, options) { /** * Borrowed from framework's shared head. Close toolbox, completely disable * accessibility and remove the tab. + * * @param {Tab} * tab The tab to close. * @return {Promise} @@ -850,6 +870,7 @@ async function closeTabToolboxAccessibility(tab = gBrowser.selectedTab) { /** * A wrapper function around add_task that sets up the test environment, runs * the test and then disables accessibility tools. + * * @param {String} msg a message that is printed for the test * @param {String} uri absolute test URL or HTML snippet * @param {Function} task task function containing the tests. diff --git a/devtools/client/accessibility/test/node/helpers.js b/devtools/client/accessibility/test/node/helpers.js @@ -24,6 +24,7 @@ function setupStore({ preloadedState } = {}) { /** * Build a mock accessible object. + * * @param {Object} form * Data similar to what accessible actor passes to accessible front. */ diff --git a/devtools/client/anti-tracking/debugger-fsm-context.js b/devtools/client/anti-tracking/debugger-fsm-context.js @@ -36,6 +36,7 @@ class DebuggerFSMContext { /** * Transition to a new FSM state. + * * @param {object} state - The new state instance. */ changeState(state) { @@ -71,6 +72,7 @@ class DebuggerFSMContext { class FSMState { /** * Base class for FSM states. + * * @param {DebuggerFSMContext} debuggerFSMContext - The FSM context. */ constructor(debuggerFSMContext) { @@ -164,6 +166,7 @@ class DomainStageState extends FSMState { /** * Group trackers by their top-level domain. + * * @param {string[]} trackers - List of tracker hostnames. */ groupByDomain(trackers) { diff --git a/devtools/client/anti-tracking/webcompat-tracker-debugger.js b/devtools/client/anti-tracking/webcompat-tracker-debugger.js @@ -173,6 +173,7 @@ class WebcompatTrackerDebugger { /** * Block or unblock all selected trackers. + * * @param {boolean} blocked - If true, block the selected trackers; if false, unblock them. */ async blockOrUnblockSelected(blocked) { @@ -217,6 +218,7 @@ class WebcompatTrackerDebugger { /** * Create the table head for the tracker table. + * * @return {HTMLTableSectionElement} The table head element containing the header row. */ createTableHead() { @@ -247,6 +249,7 @@ class WebcompatTrackerDebugger { /** * Handler for select all checkbox change event. + * * @param {Event} e - The change event. */ onSelectAllChange(e) { @@ -262,6 +265,7 @@ class WebcompatTrackerDebugger { /** * Create the table body for the tracker table. + * * @return {HTMLTableSectionElement} The table body element containing tracker rows. */ createTableBody() { @@ -274,6 +278,7 @@ class WebcompatTrackerDebugger { /** * Create a row for a tracker. + * * @param {string} hostname - The hostname of the tracker. * @param {Object} trackerData - The data associated with the tracker. * @param {string} trackerData.trackerType - The type of tracker (e.g., "tracking", "fingerprinting"). @@ -307,6 +312,7 @@ class WebcompatTrackerDebugger { /** * Create a checkbox cell for a tracker row. + * * @param {string} tracker - The tracker identifier (hostname). * @returns {HTMLTableCellElement} The checkbox cell element. */ @@ -324,6 +330,7 @@ class WebcompatTrackerDebugger { /** * Handler for individual row checkbox change event. + * * @param {Event} e - The change event. */ onRowCheckboxChange(e) { @@ -337,6 +344,7 @@ class WebcompatTrackerDebugger { /** * Create an action cell (block/unblock button) for a tracker row. + * * @param {string} tracker - The tracker identifier (hostname). * @param {boolean} isBlocked - Whether the tracker is currently blocked. * @returns {HTMLTableCellElement} The action cell element containing the button. @@ -355,6 +363,7 @@ class WebcompatTrackerDebugger { /** * Handler for individual action button click event. + * * @param {string} tracker - The tracker identifier (hostname). * @param {boolean} isBlocked - Whether the tracker is currently blocked. */ diff --git a/devtools/client/application/test/browser/head.js b/devtools/client/application/test/browser/head.js @@ -126,6 +126,7 @@ async function waitForWorkerRegistration(swTab) { function selectPage(panel, page) { /** * Select a page by simulating a user click in the sidebar. + * * @param {string} page The page we want to select (see `PAGE_TYPES`) */ info(`Selecting application page: ${page}`); diff --git a/devtools/client/debugger/panel.js b/devtools/client/debugger/panel.js @@ -234,6 +234,7 @@ class DebuggerPanel { /** * Return the source-mapped variables for the current scope. + * * @returns {{[String]: String} | null} A dictionary mapping original variable names to generated * variable names if map scopes is enabled, otherwise null. */ diff --git a/devtools/client/debugger/src/actions/ast/setInScopeLines.js b/devtools/client/debugger/src/actions/ast/setInScopeLines.js @@ -12,6 +12,7 @@ import { isFulfilled } from "../../utils/async-value"; /** * Get and store the in scope lines in the reducer + * * @param {Object} editor - The editor provides an API to retrieve the in scope location * details based on lezer in CM6. * @returns diff --git a/devtools/client/debugger/src/actions/breakpoints/index.js b/devtools/client/debugger/src/actions/breakpoints/index.js @@ -4,6 +4,7 @@ /** * Redux actions for breakpoints + * * @module actions/breakpoints */ diff --git a/devtools/client/debugger/src/actions/navigation.js b/devtools/client/debugger/src/actions/navigation.js @@ -9,6 +9,7 @@ import { getEditor } from "../utils/editor/index"; /** * Redux actions for the navigation state + * * @module actions/navigation */ diff --git a/devtools/client/debugger/src/actions/pause/index.js b/devtools/client/debugger/src/actions/pause/index.js @@ -4,6 +4,7 @@ /** * Redux actions for the pause state + * * @module actions/pause */ diff --git a/devtools/client/debugger/src/actions/pause/mapFrames.js b/devtools/client/debugger/src/actions/pause/mapFrames.js @@ -169,6 +169,7 @@ export function updateAllFrameDisplayNames(thread) { * e.g. * 1. When the debuggee pauses * 2. When a source is pretty printed + * * @memberof actions/pause * @static */ diff --git a/devtools/client/debugger/src/actions/project-text-search.js b/devtools/client/debugger/src/actions/project-text-search.js @@ -4,6 +4,7 @@ /** * Redux actions for the search state + * * @module actions/search */ diff --git a/devtools/client/debugger/src/actions/sources/blackbox.js b/devtools/client/debugger/src/actions/sources/blackbox.js @@ -4,6 +4,7 @@ /** * Redux actions for the sources state + * * @module actions/sources */ diff --git a/devtools/client/debugger/src/actions/sources/loadSourceText.js b/devtools/client/debugger/src/actions/sources/loadSourceText.js @@ -161,6 +161,7 @@ async function onSourceTextContentAvailable( /** * Loads the source text for the generated source based of the source actor + * * @param {Object} sourceActor * There can be more than one source actor per source * so the source actor needs to be specified. This is @@ -201,6 +202,7 @@ export const loadGeneratedSourceText = memoizeableAction( /** * Loads the source text for an original source and source actor + * * @param {Object} source * The original source to load the source text */ diff --git a/devtools/client/debugger/src/actions/sources/newSources.js b/devtools/client/debugger/src/actions/sources/newSources.js @@ -4,6 +4,7 @@ /** * Redux actions for the sources state + * * @module actions/sources */ import { insertSourceActors } from "../../actions/source-actors"; diff --git a/devtools/client/debugger/src/actions/sources/select.js b/devtools/client/debugger/src/actions/sources/select.js @@ -4,6 +4,7 @@ /** * Redux actions for the sources state + * * @module actions/sources */ import { prettyPrintSource } from "./prettyPrint"; diff --git a/devtools/client/debugger/src/reducers/ast.js b/devtools/client/debugger/src/reducers/ast.js @@ -4,6 +4,7 @@ /** * Ast reducer + * * @module reducers/ast */ diff --git a/devtools/client/debugger/src/reducers/breakpoints.js b/devtools/client/debugger/src/reducers/breakpoints.js @@ -4,6 +4,7 @@ /** * Breakpoints reducer + * * @module reducers/breakpoints */ diff --git a/devtools/client/debugger/src/reducers/exceptions.js b/devtools/client/debugger/src/reducers/exceptions.js @@ -4,6 +4,7 @@ /** * Exceptions reducer + * * @module reducers/exceptionss */ diff --git a/devtools/client/debugger/src/reducers/expressions.js b/devtools/client/debugger/src/reducers/expressions.js @@ -4,6 +4,7 @@ /** * Expressions reducer + * * @module reducers/expressions */ diff --git a/devtools/client/debugger/src/reducers/index.js b/devtools/client/debugger/src/reducers/index.js @@ -4,6 +4,7 @@ /** * Reducer index + * * @module reducers/index */ diff --git a/devtools/client/debugger/src/reducers/pause.js b/devtools/client/debugger/src/reducers/pause.js @@ -6,6 +6,7 @@ /** * Pause reducer + * * @module reducers/pause */ diff --git a/devtools/client/debugger/src/reducers/quick-open.js b/devtools/client/debugger/src/reducers/quick-open.js @@ -4,6 +4,7 @@ /** * Quick Open reducer + * * @module reducers/quick-open */ diff --git a/devtools/client/debugger/src/reducers/sources-tree.js b/devtools/client/debugger/src/reducers/sources-tree.js @@ -501,6 +501,7 @@ function addSource(threadItems, source, sourceActor) { } /** * Find all the source items in tree + * * @param {Object} item - Current item node in the tree * @param {Function} callback */ diff --git a/devtools/client/debugger/src/reducers/sources.js b/devtools/client/debugger/src/reducers/sources.js @@ -4,6 +4,7 @@ /** * Sources reducer + * * @module reducers/sources */ diff --git a/devtools/client/debugger/src/reducers/threads.js b/devtools/client/debugger/src/reducers/threads.js @@ -4,6 +4,7 @@ /** * Threads reducer + * * @module reducers/threads */ diff --git a/devtools/client/debugger/src/reducers/ui.js b/devtools/client/debugger/src/reducers/ui.js @@ -6,6 +6,7 @@ /** * UI reducer + * * @module reducers/ui */ diff --git a/devtools/client/debugger/src/selectors/breakpoints.js b/devtools/client/debugger/src/selectors/breakpoints.js @@ -31,6 +31,7 @@ export function getBreakpoint(state, location) { /** * Gets the breakpoints on a line or within a range of lines + * * @param {Object} state * @param {Number} source * @param {Number|Object} lines - line or an object with a start and end range of lines diff --git a/devtools/client/debugger/src/selectors/sources.js b/devtools/client/debugger/src/selectors/sources.js @@ -203,7 +203,6 @@ export function getShouldScrollToSelectedLocation(state) { * @param {String} [threadId] * The thread to check, this is optional. * @param {Object} sourceActor - * */ export function getFirstSourceActorForGeneratedSource( state, diff --git a/devtools/client/debugger/src/utils/editor/index.js b/devtools/client/debugger/src/utils/editor/index.js @@ -39,6 +39,7 @@ export function toWasmSourceLine(offset) { /** * Convert source lines / WASM line offsets to Codemirror lines + * * @param {Object} source * @param {Number} lineOrOffset * @returns diff --git a/devtools/client/debugger/src/utils/editor/tokens.js b/devtools/client/debugger/src/utils/editor/tokens.js @@ -98,6 +98,7 @@ function _invalidLeaveTarget(target) { /** * Wraps the codemirror mouse events to generate token events + * * @param {Object} editor * @returns {Function} */ diff --git a/devtools/client/debugger/src/utils/memoizableAction.js b/devtools/client/debugger/src/utils/memoizableAction.js @@ -25,7 +25,6 @@ import { validateContext } from "./context"; * action: ({ a }, thunkArgs) => doSetItem(a, thunkArgs) * } * ); - * */ export function memoizeableAction(name, { getValue, createKey, action }) { const requests = new Map(); diff --git a/devtools/client/debugger/src/utils/pause/scopes.js b/devtools/client/debugger/src/utils/pause/scopes.js @@ -221,6 +221,7 @@ function _getFrameExceptionOrReturnedValueVariables(why, path) { /** * Generates the scope items (for scopes related to selected frame) to be rendered in the scope panel + * * @param {*} why * @param {*} selectedFrame * @param {*} frameScopes diff --git a/devtools/client/debugger/src/utils/source.js b/devtools/client/debugger/src/utils/source.js @@ -4,6 +4,7 @@ /** * Utils for working with Source URLs + * * @module utils/source */ @@ -118,6 +119,7 @@ export function findBlackBoxRange(source, blackboxedRanges, lineRange) { /** * Checks if a source line is blackboxed + * * @param {Array} ranges - Line ranges that are blackboxed * @param {Number} line * @param {Boolean} isSourceOnIgnoreList - is the line in a source that is on diff --git a/devtools/client/debugger/src/utils/test-head.js b/devtools/client/debugger/src/utils/test-head.js @@ -4,6 +4,7 @@ /** * Utils for Jest + * * @module utils/test-head */ diff --git a/devtools/client/debugger/src/utils/text.js b/devtools/client/debugger/src/utils/text.js @@ -4,6 +4,7 @@ /** * Utils for keyboard command strings + * * @module utils/text */ @@ -11,6 +12,7 @@ * Truncates the received text to the maxLength in the format: * Original: 'this is a very long text and ends here' * Truncated: 'this is a ver...and ends here' + * * @param {String} sourceText - Source text * @param {Number} maxLength - Max allowed length * @memberof utils/text diff --git a/devtools/client/debugger/src/utils/utils.js b/devtools/client/debugger/src/utils/utils.js @@ -6,6 +6,7 @@ const DevToolsUtils = require("resource://devtools/shared/DevToolsUtils.js"); /** * Utils for utils, by utils + * * @module utils/utils */ diff --git a/devtools/client/debugger/test/mochitest/browser_dbg-blackbox.js b/devtools/client/debugger/test/mochitest/browser_dbg-blackbox.js @@ -507,6 +507,7 @@ async function assertContextMenuDisabled(dbg, selector, shouldBeDisabled) { /** * Asserts that the gutter blackbox context menu items which are visible are correct + * * @params {Object} dbg * @params {Array} testFixtures * Details needed for the assertion. Any blackboxed/nonBlackboxed lines @@ -564,6 +565,7 @@ async function assertGutterBlackBoxBoxContextMenuItems(dbg, testFixtures) { /** * Asserts that the source tree blackbox context menu items which are visible are correct + * * @params {Object} dbg * @params {Array} testFixtures * Details needed for the assertion. Any blackboxed/nonBlackboxed sources @@ -596,6 +598,7 @@ async function assertSourceTreeBlackBoxBoxContextMenuItems(dbg, testFixtures) { /** * Asserts that the editor blackbox context menu items which are visible are correct + * * @params {Object} dbg * @params {Array} testFixtures * Details needed for the assertion. Any blackboxed/nonBlackboxed lines diff --git a/devtools/client/debugger/test/mochitest/shared-head.js b/devtools/client/debugger/test/mochitest/shared-head.js @@ -1619,6 +1619,7 @@ async function scrollAndGetEditorLineGutterElement(dbg, line) { /** * Gets node at a specific line in the editor + * * @param {*} dbg * @param {Number} line * @returns {Element} DOM Element @@ -1630,6 +1631,7 @@ async function getNodeAtEditorLine(dbg, line) { /** * Gets node at a specific line in the gutter + * * @param {*} dbg * @param {Number} line * @returns {Element} DOM Element @@ -1655,6 +1657,7 @@ async function waitForConditionalPanelFocus(dbg) { /** * Opens the debugger editor context menu in either codemirror or the * the debugger gutter. + * * @param {Object} dbg * @param {String} elementName * The element to select @@ -1670,6 +1673,7 @@ async function openContextMenuInDebugger(dbg, elementName, line) { /** * Select a range of lines in the editor and open the contextmenu + * * @param {Object} dbg * @param {Object} lines * @param {String} elementName @@ -1687,6 +1691,7 @@ async function selectEditorLinesAndOpenContextMenu( /** * Asserts that the styling for ignored lines are applied + * * @param {Object} dbg * @param {Object} options * lines {null | Number[]} [lines] Line(s) to assert. @@ -2361,6 +2366,7 @@ async function waitForCursorPosition(dbg, expectedLine) { /** * Set the cursor at a specific location in the editor + * * @param {*} dbg * @param {Number} line * @param {Number} column @@ -2691,6 +2697,7 @@ async function getTokenElAtLine(dbg, expression, line, column = 0) { /** * Wait for a few ms and assert that a tooltip preview was not displayed. + * * @param {*} dbg */ async function assertNoTooltip(dbg) { @@ -2701,6 +2708,7 @@ async function assertNoTooltip(dbg) { /** * Hovers and asserts tooltip previews with simple text expressions (i.e numbers and strings) + * * @param {*} dbg * @param {Number} line * @param {Number} column @@ -2741,6 +2749,7 @@ async function assertPreviewTextValue( /** * Asserts multiple previews + * * @param {*} dbg * @param {Array} previews */ @@ -2821,6 +2830,7 @@ async function assertPreviews(dbg, previews) { /** * Asserts the inline expression preview value + * * @param {*} dbg * @param {Number} line * @param {Number} column @@ -2882,6 +2892,7 @@ async function assertInlineExceptionPreview( /** * Wait until a preview popup containing the given result is shown + * * @param {*} dbg * @param {String} result */ @@ -2895,6 +2906,7 @@ async function waitForPreviewWithResult(dbg, result) { /** * Expand or collapse a node in the preview popup + * * @param {*} dbg * @param {Number} index */ @@ -3045,6 +3057,7 @@ async function assertNodeIsFocused(dbg, index) { /** * Asserts that the debugger is paused and the debugger tab is * highlighted. + * * @param {*} toolbox * @returns */ @@ -3443,6 +3456,7 @@ if (protocolHandler.hasSubstitution("testing-common")) { /** * Selects the specific black box context menu item + * * @param {Object} dbg * @param {String} itemName * The name of the context menu item. diff --git a/devtools/client/devtools-client.js b/devtools/client/devtools-client.js @@ -401,6 +401,7 @@ DevToolsClient.prototype = { /** * Send a request. + * * @throws Error if there is already an active request in flight for the same * actor. */ @@ -857,6 +858,7 @@ DevToolsClient.prototype = { /** * Creates an object front for this DevToolsClient and the grip in parameter, + * * @param {Object} grip: The grip to create the ObjectFront for. * @param {ThreadFront} threadFront * @param {Front} parentFront: Optional front that will manage the object front. diff --git a/devtools/client/dom/test/head.js b/devtools/client/dom/test/head.js @@ -18,6 +18,7 @@ const constants = require("resource://devtools/client/dom/content/constants.js") /** * Add a new test tab in the browser and load the given url. + * * @param {String} url * The url to be loaded in the new tab * @return a promise that resolves to the tab object when diff --git a/devtools/client/framework/browser-toolbox/Launcher.sys.mjs b/devtools/client/framework/browser-toolbox/Launcher.sys.mjs @@ -69,6 +69,7 @@ export class BrowserToolboxLauncher extends EventEmitter { /** * Figure out if there are any open Browser Toolboxes that'll need to be restored. + * * @return {boolean} */ static getBrowserToolboxSessionState() { @@ -439,6 +440,7 @@ export class BrowserToolboxLauncher extends EventEmitter { /** * Helper method for debugging. + * * @param string */ function dumpn(str) { diff --git a/devtools/client/framework/devtools-browser.js b/devtools/client/framework/devtools-browser.js @@ -490,7 +490,6 @@ var gDevToolsBrowser = (exports.gDevToolsBrowser = { * The chrome window containing about:devtools-toolbox. Will match * toolbox.topWindow. * @return {Toolbox} The toolbox instance loaded in about:devtools-toolbox - * */ _getAboutDevtoolsToolbox(win) { if (!gDevToolsBrowser._isAboutDevtoolsToolbox(win)) { diff --git a/devtools/client/framework/devtools.js b/devtools/client/framework/devtools.js @@ -944,6 +944,7 @@ DevTools.prototype = { /** * Either the DevTools Loader has been destroyed or firefox is shutting down. + * * @param {boolean} shuttingDown * True if firefox is currently shutting down. We may prevent doing * some cleanups to speed it up. Otherwise everything need to be diff --git a/devtools/client/framework/test/browser_toolbox_select_event.js b/devtools/client/framework/test/browser_toolbox_select_event.js @@ -46,6 +46,7 @@ add_task(async function () { /** * Assert that selecting the given toolId raises a select event + * * @param {toolId} Id of the tool to test */ async function testSelectEvent(toolId) { @@ -58,6 +59,7 @@ add_task(async function () { /** * Assert that selecting the given toolId raises its corresponding * selected event + * * @param {toolId} Id of the tool to test */ async function testToolSelectEvent(toolId) { diff --git a/devtools/client/framework/test/head.js b/devtools/client/framework/test/head.js @@ -73,6 +73,7 @@ function getSourceActor(sources, url) { /** * Synthesize a keypress from a <key> element, taking into account * any modifiers. + * * @param {Element} el the <key> element to synthesize */ function synthesizeKeyElement(el) { @@ -88,6 +89,7 @@ function synthesizeKeyElement(el) { /** * Check the toolbox host type and prefs to make sure they match the * expected values + * * @param {Toolbox} * @param {HostType} hostType * One of {SIDE, BOTTOM, WINDOW} from Toolbox.HostType @@ -112,6 +114,7 @@ function checkHostType(toolbox, hostType, previousHostType) { /** * Create a new <script> referencing URL. Return a promise that * resolves when this has happened + * * @param {String} url * the url * @return {Promise} a promise that resolves when the element has been created @@ -129,6 +132,7 @@ function createScript(url) { /** * Wait for the toolbox to notice that a given source is loaded + * * @param {Toolbox} toolbox * @param {String} url * the url to wait for diff --git a/devtools/client/framework/toolbox.js b/devtools/client/framework/toolbox.js @@ -639,6 +639,7 @@ Toolbox.prototype = { /** * Get the enabled split console setting, and if it's not set, set it with updateIsSplitConsoleEnabled + * * @returns {boolean} devtools.toolbox.splitconsole.enabled option */ isSplitConsoleEnabled() { @@ -1890,6 +1891,7 @@ Toolbox.prototype = { /** * Handle any custom key events. Returns true if there was a custom key * binding run. + * * @param {string} toolId Which tool to run the command on (skip if not * current) */ @@ -2093,6 +2095,7 @@ Toolbox.prototype = { * Reset tabindex attributes across all focusable elements inside the toolbar. * Only have one element with tabindex=0 at a time to make sure that tabbing * results in navigating away from the toolbar container. + * * @param {FocusEvent} event */ _onToolbarFocus(id) { @@ -2105,6 +2108,7 @@ Toolbox.prototype = { * as it is difficult to coordinate between different component elements. * The components are responsible for setting the correct tabindex value * for if they are the focused element. + * * @param {KeyboardEvent} event */ _onToolbarArrowKeypress(event) { @@ -2659,7 +2663,6 @@ Toolbox.prototype = { * the id of the tool to test for existence. * * @return {boolean} - * */ hasAdditionalTool(toolId) { return this.additionalToolDefinitions.has(toolId); @@ -2935,6 +2938,7 @@ Toolbox.prototype = { /** * Mark all in collection as unselected; and id as selected + * * @param {string} collection * DOM collection of items * @param {string} id @@ -3158,6 +3162,7 @@ Toolbox.prototype = { /** * Focus a tool's panel by id + * * @param {string} id * The id of tool to focus */ @@ -4038,6 +4043,7 @@ Toolbox.prototype = { /** * Handler for the tool-registered event. + * * @param {string} toolId * Id of the tool that was registered */ @@ -4068,6 +4074,7 @@ Toolbox.prototype = { /** * Handler for the tool-unregistered event. + * * @param {string} toolId * id of the tool that was unregistered */ @@ -4098,7 +4105,6 @@ Toolbox.prototype = { * - {AsyncFunction} waitForHighlighterHidden: Returns a promise which resolves with * the "highlighter-hidden" event data once the highlighter is * hidden. - * */ getHighlighter() { let pendingHighlight; @@ -4548,6 +4554,7 @@ Toolbox.prototype = { * Open the textbox context menu at given coordinates. * Panels in the toolbox can call this on contextmenu events with event.screenX/Y * instead of having to implement their own copy/paste/selectAll menu. + * * @param {Number} x * @param {Number} y */ @@ -4754,6 +4761,7 @@ Toolbox.prototype = { /** * Opens source in plain "view-source:". + * * @see devtools/client/shared/source-utils.js */ viewSource(sourceURL, sourceLine, sourceColumn) { @@ -4850,6 +4858,7 @@ Toolbox.prototype = { * List the subset of the active WebExtensions which have a devtools_page (used by * toolbox-options.js to create the list of the tools provided by the enabled * WebExtensions). + * * @see devtools/client/framework/toolbox-options.js */ listWebExtensions() { @@ -4866,6 +4875,7 @@ Toolbox.prototype = { * a unique id assigned to an extension when it is installed, and its name), * and emit a "webextension-registered" event to allow toolbox-options.js * to refresh the listed tools accordingly. + * * @see browser/components/extensions/ext-devtools.js */ registerWebExtension(extensionUUID, { name, pref }) { @@ -4881,6 +4891,7 @@ Toolbox.prototype = { * extension UUID, a unique id assigned to an extension when it is installed, and its * name), and emit a "webextension-unregistered" event to allow toolbox-options.js * to refresh the listed tools accordingly. + * * @see browser/components/extensions/ext-devtools.js */ unregisterWebExtension(extensionUUID) { @@ -4894,6 +4905,7 @@ Toolbox.prototype = { * A helper function which returns true if the extension with the given UUID is listed * as active for the toolbox and has its related devtools about:config preference set * to true. + * * @see browser/components/extensions/ext-devtools.js */ isWebExtensionEnabled(extensionUUID) { diff --git a/devtools/client/fronts/accessibility.js b/devtools/client/fronts/accessibility.js @@ -193,6 +193,7 @@ class AccessibleFront extends FrontClassWithSpec(accessibleSpec) { * accessibility tree starting at the level of current accessible front. It * accumulates subtrees from possible out of process frames that are children * of the current accessible front. + * * @param {JSON} snapshot * Snapshot of the current accessible front or one of its in process * children when recursing. @@ -292,6 +293,7 @@ class AccessibleWalkerFront extends FrontClassWithSpec(accessibleWalkerSpec) { /** * Get the accessible object ancestry starting from the given accessible to * the top level document. The top level document is in the top level content process. + * * @param {Object} accessible * Accessible front to determine the ancestry for. * @@ -345,6 +347,7 @@ class AccessibleWalkerFront extends FrontClassWithSpec(accessibleWalkerSpec) { * cases when the document is in the OOP frame), this method also updates * relative ancestries of audited accessible objects all the way up to the top * level document for the toolbox. + * * @param {Object} options * - {Array} types * types of the accessibility issues to audit for diff --git a/devtools/client/fronts/css-properties.js b/devtools/client/fronts/css-properties.js @@ -178,6 +178,7 @@ function normalizeCssData(db) { /** * Color values are omitted to save on space. Add them back here. + * * @param {Object} The CSS database. */ function reattachCssColorValues(db) { diff --git a/devtools/client/fronts/inspector/rule-rewriter.js b/devtools/client/fronts/inspector/rule-rewriter.js @@ -310,6 +310,7 @@ class RuleRewriter { * backward in |string|. Return the index of the first * non-whitespace character, or -1 if the entire string was * whitespace. + * * @param {String} string the input string * @param {Number} index the index at which to start * @return {Number} index of the first non-whitespace character, or -1 diff --git a/devtools/client/fronts/perf.js b/devtools/client/fronts/perf.js @@ -50,6 +50,7 @@ class PerfFront extends FrontClassWithSpec(perfSpec) { /** * This implements the retrieval of the profile data using the bulk protocol. + * * @param {number} handle THe handle returned by startCaptureAndStopProfiler */ async getPreviouslyCapturedProfileDataBulk(handle) { diff --git a/devtools/client/fronts/root.js b/devtools/client/fronts/root.js @@ -48,6 +48,7 @@ class RootFront extends FrontClassWithSpec(rootSpec) { } /** * Retrieve all service worker registrations with their corresponding workers. + * * @param {Array} [workerTargets] (optional) * Array containing the result of a call to `listAllWorkerTargets`. * (this exists to avoid duplication of calls to that method) @@ -320,6 +321,7 @@ class RootFront extends FrontClassWithSpec(rootSpec) { /** * This function returns true if the root actor has a registered global actor * with a given name. + * * @param {String} actorName * The name of a global actor. * diff --git a/devtools/client/fronts/style-rule.js b/devtools/client/fronts/style-rule.js @@ -218,6 +218,7 @@ registerFront(StyleRuleFront); class RuleModificationList { /** * Initialize a RuleModificationList. + * * @param {StyleRuleFront} rule the associated rule */ constructor(rule) { diff --git a/devtools/client/fronts/walker.js b/devtools/client/fronts/walker.js @@ -436,6 +436,7 @@ class WalkerFront extends FrontClassWithSpec(walkerSpec) { /** * Start the element picker on the debuggee target. + * * @param {Boolean} doFocus - Optionally focus the content area once the picker is * activated. */ diff --git a/devtools/client/inspector/animation/test/summary-graph_computed-timing-path_head.js b/devtools/client/inspector/animation/test/summary-graph_computed-timing-path_head.js @@ -7,6 +7,7 @@ /** * Test for computed timing path on summary graph using given test data. + * * @param {Array} testData */ // eslint-disable-next-line no-unused-vars diff --git a/devtools/client/inspector/boxmodel/test/head.js b/devtools/client/inspector/boxmodel/test/head.js @@ -12,6 +12,7 @@ Services.scriptloader.loadSubScript( /** * Is the given node visible in the page (rendered in the frame tree). + * * @param {DOMNode} * @return {Boolean} */ diff --git a/devtools/client/inspector/breadcrumbs.js b/devtools/client/inspector/breadcrumbs.js @@ -71,6 +71,7 @@ ArrowScrollBox.prototype = { /** * Scroll to the specified element using the current scroll behavior + * * @param {Element} element element to scroll * @param {String} block desired alignment of element after scrolling */ @@ -81,6 +82,7 @@ ArrowScrollBox.prototype = { /** * Call the given function once; then continuously * while the mouse button is held + * * @param {Function} repeatFn the function to repeat while the button is held */ clickOrHold(repeatFn) { @@ -208,6 +210,7 @@ ArrowScrollBox.prototype = { /** * Check whether the element is to the left of its container but does * not also span the entire container. + * * @param {Number} left the left scroll point of the container * @param {Number} right the right edge of the container * @param {Number} elementLeft the left edge of the element @@ -222,6 +225,7 @@ ArrowScrollBox.prototype = { /** * Check whether the element is to the right of its container but does * not also span the entire container. + * * @param {Number} left the left scroll point of the container * @param {Number} right the right edge of the container * @param {Number} elementLeft the left edge of the element @@ -256,6 +260,7 @@ ArrowScrollBox.prototype = { /** * Find the first element that matches the given predicate, called with bounds * information + * * @param {Array} elements an ordered list of elements * @param {Function} predicate a function to be called with bounds * information @@ -315,6 +320,7 @@ ArrowScrollBox.prototype = { /** * Create an XHTML element with the given class name, and append it to the * parent. + * * @param {String} tagName name of the tag to create * @param {String} className class of the element * @param {DOMNode} parent the parent node to which it should be appended @@ -428,6 +434,7 @@ HTMLBreadcrumbs.prototype = { /** * Build a string that represents the node: tagName#id.class1.class2. + * * @param {NodeFront} node The node to pretty-print * @return {String} */ @@ -535,6 +542,7 @@ HTMLBreadcrumbs.prototype = { /** * Generic event handler. + * * @param {DOMEvent} event. */ handleEvent(event) { @@ -553,6 +561,7 @@ HTMLBreadcrumbs.prototype = { * Focus event handler. When breadcrumbs container gets focus, * aria-activedescendant needs to be updated to currently selected * breadcrumb. Ensures that the focus stays on the container at all times. + * * @param {DOMEvent} event. */ handleFocus(event) { @@ -570,6 +579,7 @@ HTMLBreadcrumbs.prototype = { /** * On click navigate to the correct node. + * * @param {DOMEvent} event. */ handleClick(event) { @@ -581,6 +591,7 @@ HTMLBreadcrumbs.prototype = { /** * On mouse over, highlight the corresponding content DOM Node. + * * @param {DOMEvent} event. */ handleMouseOver(event) { @@ -675,6 +686,7 @@ HTMLBreadcrumbs.prototype = { /** * Set which button represent the selected node. + * * @param {Number} index Index of the displayed-button to select. */ setCursor(index) { @@ -699,6 +711,7 @@ HTMLBreadcrumbs.prototype = { /** * Get the index of the node in the cache. + * * @param {NodeFront} node. * @returns {Number} The index for this node or -1 if not found. */ @@ -714,6 +727,7 @@ HTMLBreadcrumbs.prototype = { /** * Remove all the buttons and their references in the cache after a given * index. + * * @param {Number} index. */ cutAfter(index) { @@ -725,6 +739,7 @@ HTMLBreadcrumbs.prototype = { /** * Build a button representing the node. + * * @param {NodeFront} node The node from the page. * @return {DOMNode} The <button> for this node. */ @@ -757,6 +772,7 @@ HTMLBreadcrumbs.prototype = { /** * Connecting the end of the breadcrumbs to a node. + * * @param {NodeFront} node The node to reach. */ expand(node) { @@ -785,6 +801,7 @@ HTMLBreadcrumbs.prototype = { /** * Find the "youngest" ancestor of a node which is already in the breadcrumbs. + * * @param {NodeFront} node. * @return {Number} Index of the ancestor in the cache, or -1 if not found. */ @@ -840,6 +857,7 @@ HTMLBreadcrumbs.prototype = { * decide whether or not they are "interesting" to the current state of the * breadcrumbs widget, i.e. at least one of them should cause part of the * widget to be updated. + * * @param {Array} mutations The mutations array. * @return {Boolean} */ @@ -884,6 +902,7 @@ HTMLBreadcrumbs.prototype = { /** * Update the breadcrumbs display when a new node is selected and there are * mutations. + * * @param {Array} mutations An array of mutations in case this was called as * the "markupmutation" event listener. */ @@ -893,6 +912,7 @@ HTMLBreadcrumbs.prototype = { /** * Update the breadcrumbs display when a new node is selected. + * * @param {String} reason The reason for the update, if any. * @param {Array} mutations An array of mutations in case this was called as * the "markupmutation" event listener. diff --git a/devtools/client/inspector/changes/ChangesView.js b/devtools/client/inspector/changes/ChangesView.js @@ -250,6 +250,7 @@ class ChangesView { /** * Event handler for the "contextmenu" event fired when the context menu is requested. + * * @param {Event} e */ onContextMenu(e) { diff --git a/devtools/client/inspector/compatibility/test/browser/browser_compatibility_dynamic_markup-dom-change.js b/devtools/client/inspector/compatibility/test/browser/browser_compatibility_dynamic_markup-dom-change.js @@ -77,6 +77,7 @@ add_task(async function () { * that corresponds to the selector passed. * This overrides the definition in inspector/test/head.js which times * out when the container to be clicked is already the selected node. + * * @param {String|NodeFront} selector * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox diff --git a/devtools/client/inspector/computed/computed.js b/devtools/client/inspector/computed/computed.js @@ -759,6 +759,7 @@ class CssComputedView { /** * Set the filter style search value. + * * @param {String} value * The search value. */ @@ -1635,6 +1636,7 @@ class SelectorView { /** * Decode for cssInfo.rule.status + * * @see SelectorView.prototype.#cacheStatusNames * @see CssLogic.STATUS */ @@ -1649,6 +1651,7 @@ class SelectorView { * * These statuses are localized inside the styleinspector.properties string * bundle. + * * @see css-logic.js - the CssLogic.STATUS array. */ #cacheStatusNames() { diff --git a/devtools/client/inspector/fonts/components/FontPropertyValue.js b/devtools/client/inspector/fonts/components/FontPropertyValue.js @@ -173,6 +173,7 @@ class FontPropertyValue extends PureComponent { * * Number inputs in Firefox can't be trusted to filter out non-digit characters, * therefore we must implement our own validation. + * * @see https://bugzilla.mozilla.org/show_bug.cgi?id=1398528 * * @param {Event} e diff --git a/devtools/client/inspector/fonts/test/head.js b/devtools/client/inspector/fonts/test/head.js @@ -55,6 +55,7 @@ selectNode = async function (node, inspector, reason) { /** * Adds a new tab with the given URL, opens the inspector and selects the * font-inspector tab. + * * @return {Promise} resolves to a {tab, toolbox, inspector, view} object */ var openFontInspectorForURL = async function (url) { diff --git a/devtools/client/inspector/grids/grid-inspector.js b/devtools/client/inspector/grids/grid-inspector.js @@ -429,7 +429,6 @@ class GridInspector { /** * Get all GridFront instances from the server(s). * - * * @return {Array} The list of GridFronts */ async getGrids() { diff --git a/devtools/client/inspector/inspector.js b/devtools/client/inspector/inspector.js @@ -1612,6 +1612,7 @@ class Inspector extends EventEmitter { /** * Can a new HTML element be inserted into the currently selected element? + * * @return {Boolean} */ canAddHTMLChild() { @@ -1907,6 +1908,7 @@ class Inspector extends EventEmitter { /** * Show the eyedropper on the page. + * * @return {Promise} resolves when the eyedropper is visible. */ showEyeDropper() { @@ -1926,6 +1928,7 @@ class Inspector extends EventEmitter { /** * Hide the eyedropper. + * * @return {Promise} resolves when the eyedropper is hidden. */ hideEyeDropper() { diff --git a/devtools/client/inspector/markup/markup.js b/devtools/client/inspector/markup/markup.js @@ -847,7 +847,6 @@ class MarkupView extends EventEmitter { * Optional configuration passed to the highlighter when shown * {CustomHighlighterFront} data.highlighter * Highlighter instance - * */ handleHighlighterEvent(eventName, data) { switch (data.type) { @@ -2142,6 +2141,7 @@ class MarkupView extends EventEmitter { /** * Replace the innerHTML of any node displayed in the inspector with * some other HTML code + * * @param {Node} node * node which innerHTML will be replaced. * @param {String} newValue diff --git a/devtools/client/inspector/markup/test/head.js b/devtools/client/inspector/markup/test/head.js @@ -30,6 +30,7 @@ SimpleTest.requestCompleteLog(); * is either not common-enough to be in head.js, or that is located in a * separate directory. * The script will be loaded synchronously and in the test's scope. + * * @param {String} filePath The file path, relative to the current directory. * Examples: * - "helper_attributes_test_runner.js" @@ -42,6 +43,7 @@ function loadHelperScript(filePath) { /** * Get the MarkupContainer object instance that corresponds to the given * NodeFront + * * @param {NodeFront} nodeFront * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox @@ -54,6 +56,7 @@ function getContainerForNodeFront(nodeFront, { markup }) { /** * Get the MarkupContainer object instance that corresponds to the given * selector + * * @param {String|NodeFront} selector * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox @@ -97,6 +100,7 @@ function getFirstChildNodeValue(selector) { /** * Using the markupview's _waitForChildren function, wait for all queued * children updates to be handled. + * * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox * @return a promise that resolves when all queued children updates have been @@ -114,6 +118,7 @@ function waitForChildrenUpdated({ markup }) { /** * Simulate a click on the markup-container (a line in the markup-view) * that corresponds to the selector passed. + * * @param {String|NodeFront} selector * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox @@ -143,6 +148,7 @@ var clickContainer = async function (selector, inspector) { /** * Focus a given editable element, enter edit mode, set value, and commit + * * @param {DOMNode} field The element that gets editable after receiving focus * and <ENTER> keypress * @param {String} value The string value to be set into the edited field @@ -162,6 +168,7 @@ function setEditableFieldValue(field, value, inspector) { * Focus the new-attribute inplace-editor field of a node's markup container * and enters the given text, then wait for it to be applied and the for the * node to mutates (when new attribute(s) is(are) created) + * * @param {String} selector The selector for the node to edit. * @param {String} text The new attribute text to be entered (e.g. "id='test'") * @param {InspectorPanel} inspector The instance of InspectorPanel currently @@ -212,6 +219,7 @@ var assertAttributes = async function (selector, expected) { /** * Undo the last markup-view action and wait for the corresponding mutation to * occur + * * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox * @return a promise that resolves when the markup-mutation has been treated or @@ -232,6 +240,7 @@ function undoChange(inspector) { /** * Redo the last markup-view action and wait for the corresponding mutation to * occur + * * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox * @return a promise that resolves when the markup-mutation has been treated or @@ -252,6 +261,7 @@ function redoChange(inspector) { /** * Check to see if the inspector menu items for editing are disabled. * Things like Edit As HTML, Delete Node, etc. + * * @param {NodeFront} nodeFront * @param {InspectorPanel} inspector * @param {Boolean} assert Should this function run assertions inline. @@ -293,6 +303,7 @@ var isEditingMenuDisabled = async function ( /** * Check to see if the inspector menu items for editing are enabled. * Things like Edit As HTML, Delete Node, etc. + * * @param {NodeFront} nodeFront * @param {InspectorPanel} inspector * @param {Boolean} assert Should this function run assertions inline. @@ -393,6 +404,7 @@ function collapseSelectionAndShiftTab(inspector) { /** * Check that the current focused element is an attribute element in the markup * view. + * * @param {String} attrName The attribute name expected to be found * @param {Boolean} editMode Whether or not the attribute should be in edit mode */ @@ -430,6 +442,7 @@ var getAttributesFromEditor = async function (selector, inspector) { /** * Simulate dragging a MarkupContainer by calling its mousedown and mousemove * handlers. + * * @param {InspectorPanel} inspector The current inspector-panel instance. * @param {String|MarkupContainer} selector The selector to identify the node or * the MarkupContainer for this node. @@ -477,6 +490,7 @@ async function simulateNodeDrag( /** * Simulate dropping a MarkupContainer by calling its mouseup handler. This is * meant to be called after simulateNodeDrag has been called. + * * @param {InspectorPanel} inspector The current inspector-panel instance. * @param {String|MarkupContainer} selector The selector to identify the node or * the MarkupContainer for this node. @@ -494,6 +508,7 @@ async function simulateNodeDrop(inspector, selector) { /** * Simulate drag'n'dropping a MarkupContainer by calling its mousedown, * mousemove and mouseup handlers. + * * @param {InspectorPanel} inspector The current inspector-panel instance. * @param {String|MarkupContainer} selector The selector to identify the node or * the MarkupContainer for this node. diff --git a/devtools/client/inspector/markup/test/helper_attributes_test_runner.js b/devtools/client/inspector/markup/test/helper_attributes_test_runner.js @@ -12,6 +12,7 @@ * new-attribute field and check that the given attributes have been created. * After each test has run, the markup-view's undo command will be called and * the test runner will check if all the new attributes are gone. + * * @param {Array} tests See runAddAttributesTest for the structure * @param {DOMNode|String} nodeOrSelector The node or node selector * corresponding to an element on the current test page that has *no attributes* @@ -35,6 +36,7 @@ function runAddAttributesTests(tests, nodeOrSelector, inspector) { /** * Run a single add-attribute test. * See runAddAttributesTests for a description. + * * @param {Object} test A test object should contain the following properties: * - desc {String} a textual description for that test, to help when * reading logs @@ -86,6 +88,7 @@ async function runAddAttributesTest(test, selector, inspector) { * value to be set into it, and then check if the new attributes are correct. * After each test has run, the markup-view's undo and redo commands will be * called and the test runner will assert again that the attributes are correct. + * * @param {Array} tests See runEditAttributesTest for the structure * @param {InspectorPanel} inspector The instance of InspectorPanel currently * opened @@ -106,6 +109,7 @@ function runEditAttributesTests(tests, inspector) { /** * Run a single edit-attribute test. * See runEditAttributesTests for a description. + * * @param {Object} test A test object should contain the following properties: * - desc {String} a textual description for that test, to help when * reading logs diff --git a/devtools/client/inspector/markup/test/helper_outerhtml_test_runner.js b/devtools/client/inspector/markup/test/helper_outerhtml_test_runner.js @@ -13,6 +13,7 @@ * This test runner will wait for the mutation event to be fired and will check * a few things. Each test may also provide its own validate function to perform * assertions and verify that the new outer html is correct. + * * @param {Array} tests See runEditOuterHTMLTest for the structure * @param {InspectorPanel} inspector The instance of InspectorPanel currently * opened @@ -30,6 +31,7 @@ function runEditOuterHTMLTests(tests, inspector) { /** * Run a single edit-outer-html test. * See runEditOuterHTMLTests for a description. + * * @param {Object} test A test object should contain the following properties: * - selector {String} a css selector targeting the node to edit * - oldHTML {String} diff --git a/devtools/client/inspector/markup/test/helper_style_attr_test_runner.js b/devtools/client/inspector/markup/test/helper_style_attr_test_runner.js @@ -72,6 +72,7 @@ async function runStyleAttributeAutocompleteTests(inspector, testData) { /** * Process a test data entry. + * * @param {Array} data * test data - click or key - to enter * @param {InplaceEditor} editor diff --git a/devtools/client/inspector/markup/views/markup-container.js b/devtools/client/inspector/markup/views/markup-container.js @@ -37,6 +37,7 @@ function MarkupContainer() {} /** * Unique identifier used to set markup container node id. + * * @type {Number} */ let markupContainerID = 0; diff --git a/devtools/client/inspector/markup/views/root-container.js b/devtools/client/inspector/markup/views/root-container.js @@ -28,6 +28,7 @@ RootContainer.prototype = { /** * If the node has children, return the list of containers for all these children. + * * @return {Array} An array of child containers or null. */ getChildContainers() { @@ -38,6 +39,7 @@ RootContainer.prototype = { /** * Set the expanded state of the container node. + * * @param {Boolean} value */ setExpanded() {}, diff --git a/devtools/client/inspector/node-picker.js b/devtools/client/inspector/node-picker.js @@ -19,7 +19,6 @@ loader.lazyRequireGetter( * - invoke actions to start and stop picking nodes on all walkers * - listen to node picker events from all walkers and relay them to subscribers * - * * @param {Commands} commands * The commands object with all interfaces defined from devtools/shared/commands/ */ diff --git a/devtools/client/inspector/rules/models/rule.js b/devtools/client/inspector/rules/models/rule.js @@ -195,6 +195,7 @@ class Rule { /** * Get the declaration block issues from the compatibility actor + * * @returns A promise that resolves with an array of objects in following form: * { * // Type of compatibility issue @@ -908,6 +909,7 @@ class Rule { /** * See whether this rule has any non-invisible properties. + * * @return {Boolean} true if there is any visible property, or false * if all properties are invisible */ diff --git a/devtools/client/inspector/rules/rules.js b/devtools/client/inspector/rules/rules.js @@ -828,6 +828,7 @@ CssRuleView.prototype = { /** * Set the filter style search value. + * * @param {String} value * The search value. */ diff --git a/devtools/client/inspector/rules/test/head.js b/devtools/client/inspector/rules/test/head.js @@ -30,6 +30,7 @@ const STYLE_INSPECTOR_L10N = new LocalizationHelper( * setting the value of the corresponding css property in the rule-view. * Use this function to close the tooltip and make sure the test waits for the * ruleview-changed event. + * * @param {SwatchBasedEditorTooltip} editorTooltip * @param {CSSRuleView} view */ @@ -523,6 +524,7 @@ async function sendKeysAndWaitForFocus(view, element, keys) { /** * Wait for a markupmutation event on the inspector that is for a style modification. + * * @param {InspectorPanel} inspector * @return {Promise} */ @@ -603,6 +605,7 @@ async function clickSelectorIcon(view, selectorText, index = 0) { /** * Toggle one of the checkboxes inside the class-panel. Resolved after the DOM mutation * has been recorded. + * * @param {CssRuleView} view The rule-view instance. * @param {String} name The class name to find the checkbox. */ @@ -622,6 +625,7 @@ async function toggleClassPanelCheckBox(view, name) { /** * Verify the content of the class-panel. + * * @param {CssRuleView} view The rule-view instance * @param {Array} classes The list of expected classes. Each item in this array is an * object with the following properties: {name: {String}, state: {Boolean}} @@ -651,6 +655,7 @@ function checkClassPanelContent(view, classes) { /** * Opens the eyedropper from the colorpicker tooltip * by selecting the colorpicker and then selecting the eyedropper icon + * * @param {view} ruleView * @param {swatch} color swatch of a particular property */ diff --git a/devtools/client/inspector/rules/utils/utils.js b/devtools/client/inspector/rules/utils/utils.js @@ -312,7 +312,6 @@ function getShapePoint(node) { * CSS property value (e.g. "1px solid var(--color, blue)") * @return {Array} * List of variable names (e.g. ["--color"]) - * */ function getCSSVariables(propertyValue = "") { const variables = []; diff --git a/devtools/client/inspector/rules/views/text-property-editor.js b/devtools/client/inspector/rules/views/text-property-editor.js @@ -1860,6 +1860,7 @@ class TextPropertyEditor { /** * Validate the name of this property. + * * @return {Boolean} true if the property name is valid, false otherwise. */ #isNameValid() { diff --git a/devtools/client/inspector/test/browser_inspector_pseudoclass-lock.js b/devtools/client/inspector/test/browser_inspector_pseudoclass-lock.js @@ -219,6 +219,7 @@ async function assertPseudoRemovedFromView( /** * Check that an element currently has a pseudo-class lock. + * * @param {String} selector The node selector to get the pseudo-class from * @param {String} pseudo The pseudoclass to check for * @return {Promise<Boolean>} diff --git a/devtools/client/inspector/test/head.js b/devtools/client/inspector/test/head.js @@ -41,6 +41,7 @@ registerCleanupFunction(function () { /** * Start the element picker and focus the content window. + * * @param {Toolbox} toolbox * @param {Boolean} skipFocus - Allow tests to bypass the focus event. */ @@ -59,6 +60,7 @@ var startPicker = async function (toolbox, skipFocus) { /** * Stop the element picker using the Escape keyboard shortcut + * * @param {Toolbox} toolbox */ var stopPickerWithEscapeKey = async function (toolbox) { @@ -69,6 +71,7 @@ var stopPickerWithEscapeKey = async function (toolbox) { /** * Start the eye dropper tool. + * * @param {Toolbox} toolbox */ var startEyeDropper = async function (toolbox) { @@ -213,6 +216,7 @@ async function getBrowsingContextForNestedFrame(selectorArray = []) { /** * Highlight a node and set the inspector's current selection to the node or * the first match of the given css selector. + * * @param {String|NodeFront} selector * @param {InspectorPanel} inspector * The instance of InspectorPanel currently loaded in the toolbox @@ -233,6 +237,7 @@ async function selectAndHighlightNode(selector, inspector) { /** * Select node for a given selector, make it focusable and set focus in its * container element. + * * @param {String|NodeFront} selector * @param {InspectorPanel} inspector The current inspector-panel instance. * @return {MarkupContainer} @@ -262,6 +267,7 @@ function clearCurrentNodeSelection(inspector) { /** * Right click on a node in the test page and click on the inspect menu item. + * * @param {String} selector The selector for the node to click on in the page. * @return {Promise} Resolves to the inspector when it has opened and is updated */ @@ -372,6 +378,7 @@ var focusSearchBoxUsingShortcut = async function (panelWin, callback) { /** * Get the MarkupContainer object instance that corresponds to the given * NodeFront + * * @param {NodeFront} nodeFront * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox @@ -384,6 +391,7 @@ function getContainerForNodeFront(nodeFront, { markup }) { /** * Get the MarkupContainer object instance that corresponds to the given * selector + * * @param {String|NodeFront} selector * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox @@ -411,6 +419,7 @@ var getContainerForSelector = async function ( /** * Simulate a mouse-over on the markup-container (a line in the markup-view) * that corresponds to the selector passed. + * * @param {String|NodeFront} selector * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox @@ -438,6 +447,7 @@ var hoverContainer = async function (selector, inspector) { /** * Simulate a click on the markup-container (a line in the markup-view) * that corresponds to the selector passed. + * * @param {String|NodeFront} selector * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox @@ -465,6 +475,7 @@ var clickContainer = async function (selector, inspector) { /** * Simulate the mouse leaving the markup-view area + * * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox * @return a promise when done @@ -498,6 +509,7 @@ function fireCopyEvent(element) { /** * Undo the last markup-view action and wait for the corresponding mutation to * occur + * * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox * @return a promise that resolves when the markup-mutation has been treated or @@ -518,6 +530,7 @@ function undoChange(inspector) { /** * Redo the last markup-view action and wait for the corresponding mutation to * occur + * * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox * @return a promise that resolves when the markup-mutation has been treated or @@ -552,6 +565,7 @@ async function getNodeFrontForSelector(selector, inspector) { /** * A simple polling helper that executes a given function until it returns true. + * * @param {Function} check A generator function that is expected to return true at some * stage. * @param {String} desc A text description to be displayed when the polling starts. @@ -843,6 +857,7 @@ function waitForStyleEditor(toolbox, href) { /** * Checks if document's active element is within the given element. + * * @param {HTMLDocument} doc document with active element in question * @param {DOMNode} container element tested on focus containment * @return {Boolean} @@ -1524,6 +1539,7 @@ function reflowContentPage() { /** * Get all box-model regions' adjusted boxquads for the given element + * * @param {String|Array} selector The node selector to target a given element * @return {Promise<Object>} A promise that resolves with an object with each property of * a box-model region, each of them being an object with the p1/p2/p3/p4 properties. diff --git a/devtools/client/inspector/test/highlighter/browser_inspector_highlighter-iframes_02.js b/devtools/client/inspector/test/highlighter/browser_inspector_highlighter-iframes_02.js @@ -53,6 +53,7 @@ add_task(async function () { /** * Helper designed to switch context to another frame at the provided index. * Returns a promise that will resolve when the navigation is complete. + * * @return {Promise} */ async function switchToFrameContext(frameIndex, toolbox, inspector) { diff --git a/devtools/client/inspector/test/search/browser_inspector_search-05.js b/devtools/client/inspector/test/search/browser_inspector_search-05.js @@ -84,11 +84,11 @@ const checkCorrectButton = async function (inspector, frameSelector) { /** * Gets the currently selected nodefront. It also finds the * document node which contains the node. + * * @param {Object} inspector * @returns {Object} * nodeFront - The currently selected nodeFront * document - The document which contains the node. - * */ async function getSelectedNodeFrontInfo(inspector) { const { selection, commands } = inspector; diff --git a/devtools/client/inspector/test/shared-head.js b/devtools/client/inspector/test/shared-head.js @@ -17,6 +17,7 @@ var { /** * Open the toolbox, with the inspector tool visible. + * * @param {String} hostType Optional hostType, as defined in Toolbox.HostType * @return {Promise} A promise that resolves when the inspector is ready.The promise * resolves with an object containing the following properties: @@ -217,6 +218,7 @@ function selectLayoutView(inspector) { /** * Get the NodeFront for a node that matches a given css selector, via the * protocol. + * * @param {String|NodeFront} selector * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox @@ -269,6 +271,7 @@ var selectNode = async function ( /** * Using the markupview's _waitForChildren function, wait for all queued * children updates to be handled. + * * @param {InspectorPanel} inspector The instance of InspectorPanel currently * loaded in the toolbox * @return a promise that resolves when all queued children updates have been @@ -400,6 +403,7 @@ async function selectNodeInFrames( * Create a throttling function that can be manually "flushed". This is to replace the * use of the `debounce` function from `devtools/client/inspector/shared/utils.js`, which * has a setTimeout that can cause intermittents. + * * @return {Function} This function has the same function signature as debounce, but * the property `.flush()` has been added for flushing out any * debounced calls. @@ -813,6 +817,7 @@ function buildContextMenuItems(menu) { /** * Open the style editor context menu and return all of it's items in a flat array + * * @param {CssRuleView} view * The instance of the rule-view panel * @return An array of MenuItems @@ -824,6 +829,7 @@ function openStyleContextMenuAndGetAllItems(view, target) { /** * Open the inspector menu and return all of it's items in a flat array + * * @param {InspectorPanel} inspector * @param {Object} options to pass into openMenu * @return An array of MenuItems diff --git a/devtools/client/inspector/toolsidebar.js b/devtools/client/inspector/toolsidebar.js @@ -152,6 +152,7 @@ class ToolSidebar extends EventEmitter { /** * Remove an existing tab. + * * @param {String} tabId The ID of the tab that was used to register it, or * the tab id attribute value if the tab existed before the sidebar * got created. @@ -164,6 +165,7 @@ class ToolSidebar extends EventEmitter { /** * Show or hide a specific tab. + * * @param {Boolean} isVisible True to show the tab/tabpanel, False to hide it. * @param {String} id The ID of the tab to be hidden. */ @@ -187,6 +189,7 @@ class ToolSidebar extends EventEmitter { /** * Returns the requested tab panel based on the id. + * * @param {String} id * @return {DOMNode} */ diff --git a/devtools/client/jsonview/test/browser_jsonview_access_data.js b/devtools/client/jsonview/test/browser_jsonview_access_data.js @@ -68,6 +68,7 @@ async function getJSONViewData(json) { /** * Helper function to test that $json.data matches the original object. + * * @param {*} obj - The object to stringify, load, and verify * @param {string} dataDescription - Description of the data being tested */ diff --git a/devtools/client/jsonview/test/head.js b/devtools/client/jsonview/test/head.js @@ -23,6 +23,7 @@ registerCleanupFunction(() => { /** * Add a new test tab in the browser and load the given url. + * * @param {String} url * The url to be loaded in the new tab. * @@ -217,6 +218,7 @@ function getElementAttr(selector, attr) { /** * Return the text of a row given its index, e.g. `key: "value"` + * * @param {Number} rowIndex * @returns {Promise<String>} */ diff --git a/devtools/client/netmonitor/src/actions/http-custom-request.js b/devtools/client/netmonitor/src/actions/http-custom-request.js @@ -31,6 +31,7 @@ const { /** * Open the entire HTTP Custom Request panel + * * @returns {Function} */ function openHTTPCustomRequest(isOpen) { diff --git a/devtools/client/netmonitor/src/actions/search.js b/devtools/client/netmonitor/src/actions/search.js @@ -186,6 +186,7 @@ function clearSearchResults() { /** * Used to clear and cancel an ongoing search. + * * @returns {Function} */ function clearSearchResultAndCancel() { @@ -217,6 +218,7 @@ function closeSearch() { /** * Open the entire search panel + * * @returns {Function} */ function openSearch() { @@ -232,6 +234,7 @@ function openSearch() { /** * Toggles case sensitive search + * * @returns {Function} */ function toggleCaseSensitiveSearch() { diff --git a/devtools/client/netmonitor/src/api.js b/devtools/client/netmonitor/src/api.js @@ -201,6 +201,7 @@ NetMonitorAPI.prototype = { /** * Resends a given network request + * * @param {String} requestId * Id of the network request */ diff --git a/devtools/client/netmonitor/src/components/messages/ColumnTime.js b/devtools/client/netmonitor/src/components/messages/ColumnTime.js @@ -29,6 +29,7 @@ class ColumnTime extends Component { /** * Format a DOMHighResTimeStamp (in microseconds) as HH:mm:ss.SSS + * * @param {number} highResTimeStamp */ formatTime(highResTimeStamp) { diff --git a/devtools/client/netmonitor/src/components/request-details/CookiesPanel.js b/devtools/client/netmonitor/src/components/request-details/CookiesPanel.js @@ -132,6 +132,7 @@ class CookiesPanel extends Component { /** * Get the selected cookies path + * * @param {Object} searchResult * @returns {string} */ diff --git a/devtools/client/netmonitor/src/components/search/Toolbar.js b/devtools/client/netmonitor/src/components/search/Toolbar.js @@ -57,6 +57,7 @@ class Toolbar extends Component { /** * Handles what we do when key is pressed in search input. + * * @param event * @param conn */ diff --git a/devtools/client/netmonitor/src/connector/firefox-data-provider.js b/devtools/client/netmonitor/src/connector/firefox-data-provider.js @@ -376,6 +376,7 @@ class FirefoxDataProvider { * The handler for when the network event stacktrace resource is available. * The resource contains basic info, the actual stacktrace is fetched lazily * using requestData. + * * @param {object} resource The network event stacktrace resource */ async onStackTraceAvailable(resource) { @@ -764,6 +765,7 @@ class FirefoxDataProvider { /** * Handles additional information received for a "responseCache" packet. + * * @param {object} response the message received from the server. */ async onResponseCache(response) { diff --git a/devtools/client/netmonitor/src/connector/index.js b/devtools/client/netmonitor/src/connector/index.js @@ -151,7 +151,6 @@ class Connector { * @param {boolean} options.isExplicitClear * Set to true if the call to clear requests is explicitly requested by * the user, to false if this is an automated clear, eg on navigation. - * */ clear({ isExplicitClear }) { // Clear all the caches in the data provider @@ -486,6 +485,7 @@ class Connector { /** * Getter that returns the current toolbox instance. + * * @return {Toolbox} toolbox instance */ getToolbox() { @@ -494,6 +494,7 @@ class Connector { /** * Open a given source in Debugger + * * @param {string} sourceURL source url * @param {number} sourceLine source line number */ @@ -506,6 +507,7 @@ class Connector { /** * Fetch networkEventUpdate websocket message from back-end when * data provider is connected. + * * @param {object} request network request instance * @param {string} type NetworkEventUpdate type */ diff --git a/devtools/client/netmonitor/src/utils/request-utils.js b/devtools/client/netmonitor/src/utils/request-utils.js @@ -666,6 +666,7 @@ async function getMessagePayload(payload, getLongString) { * incoming network update packets. It makes sure the only valid * update properties and the values are correct. * It's used by Network and Console panel reducers. + * * @param {object} update * The new update payload * @param {object} request @@ -706,6 +707,7 @@ function isBase64(payload) { * This function also handles JSON with XSSI-escaping characters by stripping them * and returning the stripped chars in the strippedChars property * This function also handles Base64 encoded JSON. + * * @returns {Object} shape: * {Object} json: parsed JSON object * {Error} error: JSON parsing error @@ -765,6 +767,7 @@ function parseJSON(payloadUnclean) { /** * Removes XSSI prevention sequences from JSON payloads + * * @param {string} payloadUnclean: JSON payload that may or may have a * XSSI prevention sequence * @returns {Object} Shape: diff --git a/devtools/client/netmonitor/src/utils/sort-utils.js b/devtools/client/netmonitor/src/utils/sort-utils.js @@ -7,6 +7,7 @@ /** * Sorts object by keys in alphabetical order * If object has nested children, it sorts the child-elements also by keys + * * @param {object} which should be sorted by keys in alphabetical order */ function sortObjectKeys(object) { diff --git a/devtools/client/netmonitor/src/utils/tooltips.js b/devtools/client/netmonitor/src/utils/tooltips.js @@ -6,6 +6,7 @@ /** * Returns first 128 characters of value for use as a tooltip. + * * @param object * @returns {*} */ diff --git a/devtools/client/netmonitor/src/widgets/HeadersPanelContextMenu.js b/devtools/client/netmonitor/src/widgets/HeadersPanelContextMenu.js @@ -33,6 +33,7 @@ class HeadersPanelContextMenu { /** * Handle the context menu opening. + * * @param {Object} event open event * @param {Object} selection object representing the current selection */ @@ -80,6 +81,7 @@ class HeadersPanelContextMenu { /** * Copies all. + * * @param {Object} object the whole tree data * @param {Object} selection object representing the current selection */ @@ -104,6 +106,7 @@ class HeadersPanelContextMenu { /** * Copies the value of a single item. + * * @param {Object} object data object for specific node * @param {Object} selection object representing the current selection */ diff --git a/devtools/client/netmonitor/src/widgets/PropertiesViewContextMenu.js b/devtools/client/netmonitor/src/widgets/PropertiesViewContextMenu.js @@ -33,6 +33,7 @@ class PropertiesViewContextMenu { /** * Handle the context menu opening. + * * @param {Object} event open event * @param {Object} selection object representing the current selection * @param {Object} data object containing information @@ -64,6 +65,7 @@ class PropertiesViewContextMenu { /** * Copies all. + * * @param {Object} object the whole tree data * @param {Object} selection object representing the current selection */ @@ -88,6 +90,7 @@ class PropertiesViewContextMenu { /** * Copies the value of a single item. + * * @param {Object} member member of the right-clicked row * @param {Object} selection object representing the current selection */ diff --git a/devtools/client/netmonitor/src/workers/search/search.js b/devtools/client/netmonitor/src/workers/search/search.js @@ -120,6 +120,7 @@ function searchInResource(resource, query, modifiers) { /** * Concatenates all results + * * @param results * @returns {*[]} */ @@ -145,6 +146,7 @@ function find(query, modifiers, source) { /** * Find query matches in arrays, objects and strings. + * * @param resource * @param query * @param modifiers @@ -197,6 +199,7 @@ function searchInProperties(query, modifiers, obj, data) { /** * Get type of resource - deals with arrays as well. + * * @param resource * @returns {*} */ @@ -206,6 +209,7 @@ function getType(resource) { /** * Function returns the value of a key, included nested keys. + * * @param path * @param obj * @returns {*} @@ -217,6 +221,7 @@ function getValue(path, obj) { /** * Search text for specific string and return all matches found + * * @param query * @param modifiers * @param text @@ -268,6 +273,7 @@ function searchInText(query, modifiers, text, data) { /** * Search for query in array. * Iterates through each array item and handles item based on type. + * * @param query * @param modifiers * @param arr @@ -290,6 +296,7 @@ function searchInArray(query, modifiers, arr, data) { /** * Return query match and up to 50 characters on left and right. * (50) + [matched query] + (50) + * * @param value * @param query * @param startIndex @@ -308,6 +315,7 @@ function getTruncatedValue(value, query, startIndex) { /** * Iterates through object, including nested objects, returns all + * * @param query * @param modifiers * @param obj diff --git a/devtools/client/netmonitor/test/browser_net_image-tooltip.js b/devtools/client/netmonitor/test/browser_net_image-tooltip.js @@ -92,6 +92,7 @@ add_task(async function test() { /** * Trigger a tooltip over an element by sending mousemove event. + * * @return a promise that resolves when the tooltip is shown */ async function showTooltipOn(element) { diff --git a/devtools/client/netmonitor/test/head.js b/devtools/client/netmonitor/test/head.js @@ -442,6 +442,7 @@ function restartNetMonitor(monitor, { requestCount }) { /** * Clears the network requests in the UI + * * @param {Object} monitor * The netmonitor instance used for retrieving a context menu element. */ @@ -971,7 +972,6 @@ function testFilterButtonsCustom(monitor, isChecked) { * @return Promise A promise that's resolved with object * { status: XMLHttpRequest.status, * response: XMLHttpRequest.response } - * */ function promiseXHR(data) { return new Promise(resolve => { @@ -1018,7 +1018,6 @@ function promiseXHR(data) { * @return Promise A promise that's resolved with object * { status: websocket status(101), * response: empty string } - * */ function promiseWS(data) { return new Promise(resolve => { @@ -1517,6 +1516,7 @@ function compareValues(first, second) { /** * Click on the "Response" tab to open "Response" panel in the sidebar. + * * @param {Document} doc * Network panel document. * @param {String} name @@ -1619,6 +1619,7 @@ async function toggleUrlPreview(shouldExpand, monitor) { /** * Wait for the eager evaluated result from the split console + * * @param {Object} hud * @param {String} text - expected evaluation result */ @@ -1662,7 +1663,6 @@ function testAutocompleteContents(expected, document) { * A request element from the netmonitor requests list. * @return {boolean} * True if the size column contains a valid size, false otherwise. - * */ function hasValidSize(request) { const VALID_SIZE_RE = /^\d+(\.\d+)? \w+/; diff --git a/devtools/client/performance-new/components/aboutprofiling/AboutProfiling.js b/devtools/client/performance-new/components/aboutprofiling/AboutProfiling.js @@ -75,6 +75,7 @@ function encodeShellValue(value) { /** * This component implements the button that triggers the menu that makes it * possible to show more actions. + * * @extends {React.PureComponent<ButtonProps, ButtonState>} */ class MoreActionsButtonImpl extends PureComponent { @@ -114,6 +115,7 @@ class MoreActionsButtonImpl extends PureComponent { * https://searchfox.org/mozilla-central/rev/4bacdbc8ac088f2ee516daf42c535fab2bc24a04/toolkit/content/widgets/panel-list/README.stories.md * Strangely our React's type doesn't have the `detail` property for * MouseEvent, so we're defining it manually. + * * @param {React.MouseEvent & { detail: number }} e */ handleClickOrMousedown = e => { diff --git a/devtools/client/performance-new/components/aboutprofiling/Presets.js b/devtools/client/performance-new/components/aboutprofiling/Presets.js @@ -47,6 +47,7 @@ const Localized = createFactory( class Preset extends PureComponent { /** * Handle the checkbox change. + * * @param {React.ChangeEvent<HTMLInputElement>} event */ onChange = event => { @@ -114,6 +115,7 @@ class Preset extends PureComponent { class Presets extends PureComponent { /** * Handle the checkbox change. + * * @param {string} presetName */ onChange = presetName => { diff --git a/devtools/client/performance-new/components/aboutprofiling/Range.js b/devtools/client/performance-new/components/aboutprofiling/Range.js @@ -28,6 +28,7 @@ const { /** * Provide a numeric range slider UI that works off of custom numeric scales. + * * @extends React.PureComponent<Props> */ class Range extends PureComponent { diff --git a/devtools/client/performance-new/components/aboutprofiling/Settings.js b/devtools/client/performance-new/components/aboutprofiling/Settings.js @@ -215,6 +215,7 @@ const jvmThreadColumns = [ /** * This component manages the settings for recording a performance profile. + * * @extends {React.PureComponent<Props, State>} */ class Settings extends PureComponent { @@ -238,6 +239,7 @@ class Settings extends PureComponent { /** * Handle the checkbox change. + * * @param {React.ChangeEvent<HTMLInputElement>} event */ _handleThreadCheckboxChange = event => { @@ -255,6 +257,7 @@ class Settings extends PureComponent { /** * Handle the checkbox change. + * * @param {React.ChangeEvent<HTMLInputElement>} event */ _handleFeaturesCheckboxChange = event => { @@ -597,6 +600,7 @@ class Settings extends PureComponent { /** * Clean up the thread list string into a list of values. + * * @param {string} threads - Comma separated values. * @return {string[]} */ @@ -614,6 +618,7 @@ function _threadTextToList(threads) { /** * Format the interval number for display. + * * @param {number} value * @return {React.ReactNode} */ @@ -626,6 +631,7 @@ function _intervalTextDisplay(value) { /** * Format the entries number for display. + * * @param {number} value * @return {string} */ diff --git a/devtools/client/performance-new/components/panel/Description.js b/devtools/client/performance-new/components/panel/Description.js @@ -25,6 +25,7 @@ const Localized = createFactory( /** * This component provides a helpful description for what is going on in the component * and provides some external links. + * * @extends {React.PureComponent<Props>} */ class Description extends PureComponent { diff --git a/devtools/client/performance-new/components/panel/DevToolsPresetSelection.js b/devtools/client/performance-new/components/panel/DevToolsPresetSelection.js @@ -76,6 +76,7 @@ class DevToolsPresetSelection extends PureComponent { /** * Create an object map to easily look up feature description. + * * @type {{[key: string]: FeatureDescription}} */ this.featureDescriptionMap = {}; @@ -86,6 +87,7 @@ class DevToolsPresetSelection extends PureComponent { /** * Handle the select change. + * * @param {React.ChangeEvent<HTMLSelectElement>} event */ onPresetChange = event => { diff --git a/devtools/client/performance-new/components/panel/OnboardingMessage.js b/devtools/client/performance-new/components/panel/OnboardingMessage.js @@ -40,6 +40,7 @@ const ONBOARDING_PREF = "devtools.performance.new-panel-onboarding"; /** * This component provides a temporary onboarding message for users migrating * from the old DevTools performance panel. + * * @extends {React.PureComponent<Props>} */ class OnboardingMessage extends PureComponent { diff --git a/devtools/client/performance-new/components/panel/RecordingButton.js b/devtools/client/performance-new/components/panel/RecordingButton.js @@ -27,7 +27,6 @@ * @property {typeof actions.startRecording} startRecording * @property {typeof actions.getProfileAndStopProfiler} getProfileAndStopProfiler * @property {typeof actions.stopProfilerAndDiscardProfile} stopProfilerAndDiscardProfile - */ /** diff --git a/devtools/client/performance-new/panel/panel.js b/devtools/client/performance-new/panel/panel.js @@ -43,6 +43,7 @@ class PerformancePanel { /** * Open is effectively an asynchronous constructor. + * * @return {Promise<PerformancePanel>} Resolves when the Perf tool completes * opening. */ @@ -55,6 +56,7 @@ class PerformancePanel { /** * This function is the actual implementation of the open() method. + * * @returns Promise<PerformancePanel> */ async _doOpen() { diff --git a/devtools/client/performance-new/popup/logic.sys.mjs b/devtools/client/performance-new/popup/logic.sys.mjs @@ -311,6 +311,7 @@ function addPopupEventHandlers(state, elements, view) { /** * Initialize everything needed for the popup to work fine. + * * @param {State} panelState * @param {XULElement} panelview */ diff --git a/devtools/client/performance-new/popup/menu-button.sys.mjs b/devtools/client/performance-new/popup/menu-button.sys.mjs @@ -94,6 +94,7 @@ function ensureButtonInNavbar() { /** * Opens the popup for the profiler. + * * @param {Document} document */ function openPopup(document) { @@ -116,6 +117,7 @@ function openPopup(document) { /** * This function creates the widget definition for the CustomizableUI. It should * only be run if the profiler button is enabled. + * * @param {(isEnabled: boolean) => void} toggleProfilerKeyShortcuts * @return {void} */ diff --git a/devtools/client/performance-new/shared/background.sys.mjs b/devtools/client/performance-new/shared/background.sys.mjs @@ -93,6 +93,7 @@ const lazy = createLazyLoaders({ * This function is called when the profile is captured with the shortcut keys, * with the profiler toolbarbutton, with the button inside the popup, or with * the about:logging page. + * * @param {PageContext} pageContext * @return {Promise<void>} */ @@ -137,6 +138,7 @@ export async function captureProfile(pageContext) { * This function is called when the profiler is started with the shortcut * keys, with the profiler toolbarbutton, or with the button inside the * popup. + * * @param {PageContext} pageContext */ export function startProfiler(pageContext) { @@ -161,6 +163,7 @@ export function startProfiler(pageContext) { /** * This function is called directly by devtools/startup/DevToolsStartup.jsm when * using the shortcut keys to capture a profile. + * * @type {() => void} */ export function stopProfiler() { @@ -170,6 +173,7 @@ export function stopProfiler() { /** * This function is called directly by devtools/startup/DevToolsStartup.jsm when * using the shortcut keys to start and stop the profiler. + * * @param {PageContext} pageContext * @return {void} */ diff --git a/devtools/client/performance-new/shared/utils.js b/devtools/client/performance-new/shared/utils.js @@ -42,6 +42,7 @@ function clamp(val, min, max) { /** * Formats a file size. + * * @param {number} num - The number (in bytes) to format. * @returns {string} e.g. "10 B", "100 MiB" */ @@ -191,6 +192,7 @@ function makePowerOf2Scale(rangeStart, rangeEnd) { /** * Scale a source range to a destination range, but clamp it within the * destination range. + * * @param {number} val - The source range value to map to the destination range, * @param {number} sourceRangeStart, * @param {number} sourceRangeEnd, diff --git a/devtools/client/performance-new/store/actions.js b/devtools/client/performance-new/store/actions.js @@ -36,6 +36,7 @@ exports.reportProfilerReady = isActive => ({ /** * Dispatched when the profiler starting is observed. + * * @return {Action} */ exports.reportProfilerStarted = () => ({ @@ -44,6 +45,7 @@ exports.reportProfilerStarted = () => ({ /** * Dispatched when the profiler stopping is observed. + * * @return {Action} */ exports.reportProfilerStopped = () => ({ @@ -52,6 +54,7 @@ exports.reportProfilerStopped = () => ({ /** * Updates the recording settings for the interval. + * * @param {number} interval * @return {Action} */ @@ -62,6 +65,7 @@ exports.changeInterval = interval => ({ /** * Updates the recording settings for the entries. + * * @param {number} entries * @return {Action} */ @@ -72,6 +76,7 @@ exports.changeEntries = entries => ({ /** * Updates the recording settings for the features. + * * @param {string[]} features * @return {ThunkAction<void>} */ @@ -100,6 +105,7 @@ exports.changeFeatures = features => { /** * Updates the recording settings for the threads. + * * @param {string[]} threads * @return {Action} */ @@ -110,6 +116,7 @@ exports.changeThreads = threads => ({ /** * Change the preset. + * * @param {Presets} presets * @param {string} presetName * @return {Action} @@ -124,6 +131,7 @@ exports.changePreset = (presets, presetName) => ({ /** * Updates the recording settings for the objdirs. + * * @param {string[]} objdirs * @return {Action} */ @@ -135,6 +143,7 @@ exports.changeObjdirs = objdirs => ({ /** * Receive the values to initialize the store. See the reducer for what values * are expected. + * * @param {InitializeStoreValues} values * @return {Action} */ @@ -148,6 +157,7 @@ exports.initializeStore = values => { /** * Whenever the preferences are updated, this action is dispatched to update the * redux store. + * * @param {RecordingSettings} recordingSettingsFromPreferences * @return {Action} */ @@ -160,6 +170,7 @@ exports.updateSettingsFromPreferences = recordingSettingsFromPreferences => { /** * Start a new recording with the perfFront and update the internal recording state. + * * @param {PerfFront} perfFront * @return {ThunkAction<void>} */ @@ -176,6 +187,7 @@ exports.startRecording = perfFront => { /** * Stops the profiler, and opens the profile in a new window. + * * @param {PerfFront} perfFront * @return {ThunkAction<Promise<MockedExports.ProfileAndAdditionalInformation>>} */ @@ -191,6 +203,7 @@ exports.getProfileAndStopProfiler = perfFront => { /** * Stops the profiler, but does not try to retrieve the profile. + * * @param {PerfFront} perfFront * @return {ThunkAction<void>} */ diff --git a/devtools/client/performance-new/store/reducers.js b/devtools/client/performance-new/store/reducers.js @@ -19,6 +19,7 @@ /** * The current state of the recording. + * * @type {Reducer<RecordingState>} */ // eslint-disable-next-line complexity @@ -109,6 +110,7 @@ function recordingState(state = "not-yet-known", action) { /** * Whether or not the recording state unexpectedly stopped. This allows * the UI to display a helpful message. + * * @param {RecordingState | undefined} recState * @param {boolean} state * @param {Action} action @@ -134,6 +136,7 @@ function recordingUnexpectedlyStopped(recState, state = false, action) { /** * The profiler needs to be queried asynchronously on whether or not * it supports the user's platform. + * * @type {Reducer<boolean | null>} */ function isSupportedPlatform(state = null, action) { @@ -148,6 +151,7 @@ function isSupportedPlatform(state = null, action) { /** * This object represents the default recording settings. They should be * overriden by whatever is read from the Firefox preferences at load time. + * * @type {RecordingSettings} */ const DEFAULT_RECORDING_SETTINGS = { @@ -170,6 +174,7 @@ const DEFAULT_RECORDING_SETTINGS = { /** * This small utility returns true if the parameters contain the same values. * This is essentially a deepEqual operation specific to this structure. + * * @param {RecordingSettings} a * @param {RecordingSettings} b * @return {boolean} @@ -212,6 +217,7 @@ function areSettingsEquals(a, b) { /** * This handles all values used as recording settings. + * * @type {Reducer<RecordingSettings>} */ function recordingSettings(state = DEFAULT_RECORDING_SETTINGS, action) { @@ -308,6 +314,7 @@ function promptEnvRestart(state = null, action) { /** * The main reducer for the performance-new client. + * * @type {Reducer<State>} */ module.exports = (state = undefined, action) => { diff --git a/devtools/client/performance-new/test/browser/helpers.js b/devtools/client/performance-new/test/browser/helpers.js @@ -14,6 +14,7 @@ function tick() { * It can be confusing when waiting for something asynchronously. This function * logs out a message periodically (every 1 second) in order to create helpful * log messages. + * * @param {string} message * @returns {Function} */ @@ -45,6 +46,7 @@ function createPeriodicLogger() { /** * Wait until a condition is fullfilled. + * * @param {Function} condition * @param {string?} logMessage * @return The truthy result of the condition. @@ -89,6 +91,7 @@ function getElementByTooltip(container, tooltip) { /** * This function will select a node from the XPath. + * * @returns {HTMLElement?} */ function getElementByXPath(document, path) { @@ -127,6 +130,7 @@ async function getElementFromDocumentByText(document, text) { /** * This function is similar to getElementFromDocumentByText, but it immediately * returns and does not wait for an element to exist. + * * @param {HTMLDocument} document * @param {string} text * @returns {HTMLElement?} @@ -209,6 +213,7 @@ function waitForProfilerPopupEvent(window, eventName) { * * This function toggles the profiler menu button, and then uses user gestures * to click it open. It waits a tick to make sure it has a chance to initialize. + * * @param {Window} window * @return {Promise<void>} */ @@ -247,6 +252,7 @@ async function _toggleOpenProfilerPopup(window) { * Do not use this directly in a test. Prefer withPopupOpen. * * This function uses a keyboard shortcut to close the profiler popup. + * * @param {Window} window * @return {Promise<void>} */ @@ -264,6 +270,7 @@ async function _closePopup(window) { /** * Perform some action on the popup, and close it afterwards. + * * @param {Window} window * @param {() => Promise<void>} callback */ @@ -319,6 +326,7 @@ function setProfilerFrontendUrl(origin, pathname) { * test harness. This function runs in a loop every requestAnimationFrame, and * checks for a sucess title. In addition, an "initialTitle" and "errorTitle" * can be specified for nicer test output. + * * @param {object} * { * initialTitle: string, @@ -362,6 +370,7 @@ async function checkTabLoadedProfile({ * requestAnimationFrame, and checks for a initialTitle. Asserts as soon as it * finds that title. We don't have to look for success title or error title * since we only care about the url. + * * @param {{ * initialTitle: string, * successTitle: string, @@ -406,6 +415,7 @@ async function waitForTabUrl({ /** * This function checks the document title of a tab as an easy way to pass * messages from a content page to the mochitest. + * * @param {string} title */ async function waitForTabTitle(title) { @@ -606,6 +616,7 @@ async function devToolsActiveConfigurationHasFeature(document, feature) { /** * This adapts the expectation using the current build's available profiler * features. + * * @param {string} fixture It can be either already trimmed or untrimmed. * @returns {string} */ @@ -628,6 +639,7 @@ function _adaptCustomPresetExpectationToCustomBuild(fixture) { /** * Get the content of the preset description. + * * @param {Element} devtoolsDocument * @returns {string} */ @@ -639,6 +651,7 @@ function getDevtoolsCustomPresetContent(devtoolsDocument) { /** * This checks if the content of the preset description equals the fixture in * string form. + * * @param {Element} devtoolsDocument * @param {string} fixture */ @@ -752,6 +765,7 @@ async function makeSureProfilerPopupIsDisabled() { /** * Open the WebChannel test document, that will enable the profiler popup via * WebChannel. + * * @param {Function} callback */ function withWebChannelTestDocument(callback) { diff --git a/devtools/client/responsive/utils/e10s.js b/devtools/client/responsive/utils/e10s.js @@ -12,6 +12,7 @@ const REQUEST_DONE_SUFFIX = ":Done"; /** * Registers a message `listener` that is called every time messages of * specified `message` is emitted on the given message manager. + * * @param {nsIMessageListenerManager} mm * The Message Manager * @param {String} message @@ -27,6 +28,7 @@ exports.on = on; /** * Removes a message `listener` for the specified `message` on the given * message manager. + * * @param {nsIMessageListenerManager} mm * The Message Manager * @param {String} message @@ -42,6 +44,7 @@ exports.off = off; /** * Resolves a promise the next time the specified `message` is sent over the * given message manager. + * * @param {nsIMessageListenerManager} mm * The Message Manager * @param {String} message diff --git a/devtools/client/responsive/utils/window.js b/devtools/client/responsive/utils/window.js @@ -19,6 +19,7 @@ exports.getDOMWindowUtils = getDOMWindowUtils; /** * Check if the given browser window has finished the startup. + * * @params {nsIDOMWindow} window */ const isStartupFinished = window => window.gBrowserInit?.delayedStartupFinished; diff --git a/devtools/client/shared/autocomplete-popup.js b/devtools/client/shared/autocomplete-popup.js @@ -501,6 +501,7 @@ class AutocompletePopup extends EventEmitter { /** * Getter for the selected item. + * * @type Object */ get selectedItem() { @@ -610,6 +611,7 @@ class AutocompletePopup extends EventEmitter { /** * Getter for the number of items in the popup. + * * @type {Number} */ get itemCount() { diff --git a/devtools/client/shared/classnames.js b/devtools/client/shared/classnames.js @@ -12,7 +12,6 @@ * For example: `classnames("hi", null, undefined, false, { foo: true, bar: false })` will * return `"hi foo"` * - * * @param {...string|object} argss * @returns String */ diff --git a/devtools/client/shared/components/Accordion.js b/devtools/client/shared/components/Accordion.js @@ -132,6 +132,7 @@ class Accordion extends Component { /** * Expand or collapse an accordion list item. + * * @param {Object} item The item to be collapsed or expanded. */ toggleItem(item) { diff --git a/devtools/client/shared/components/Frame.js b/devtools/client/shared/components/Frame.js @@ -55,6 +55,7 @@ function savedFrameToDebuggerLocation(frame) { /** * Get the tooltip message. + * * @param {string|undefined} messageSource * @param {string} url * @returns {string} @@ -149,6 +150,7 @@ class Frame extends Component { /** * Get current location's source, line, and column. + * * @returns {{sourceURL: string, line: number|null, column: number|null}} */ #getCurrentLocationInfo = () => { @@ -171,6 +173,7 @@ class Frame extends Component { /** * Get unicode hostname of the source link. + * * @returns {string} */ #getCurrentLocationUnicodeHostName = () => { @@ -182,6 +185,7 @@ class Frame extends Component { /** * Check if the current location is linkable. + * * @returns {boolean} */ #isCurrentLocationLinkable = () => { @@ -284,6 +288,7 @@ class Frame extends Component { /** * Render the source elements. + * * @returns {React.ReactNode} */ #renderSourceElements = () => { @@ -320,6 +325,7 @@ class Frame extends Component { /** * Render the display source. + * * @returns {React.ReactNode} */ #renderDisplaySource = () => { @@ -357,6 +363,7 @@ class Frame extends Component { /** * Render the function display name. + * * @returns {React.ReactNode} */ #renderFunctionDisplayName = () => { diff --git a/devtools/client/shared/components/reps/reps/error.mjs b/devtools/client/shared/components/reps/reps/error.mjs @@ -126,6 +126,7 @@ function getErrorName(props) { * semicolon@debugger eval code:1:109 * jkl@debugger eval code:1:63 * asdf@debugger eval code:1:28 + * * @debugger eval code:1:227 * * Into a column layout: @@ -222,6 +223,7 @@ function getCauseElement(props, preview) { * Parse a string that should represent a stack trace and returns an array of * the frames. The shape of the frames are extremely important as they can then * be processed here or in the toolbox by other components. + * * @param {String} stack * @returns {Array} Array of frames, which are object with the following shape: * - {String} filename diff --git a/devtools/client/shared/components/test/chrome/head.js b/devtools/client/shared/components/test/chrome/head.js @@ -342,6 +342,7 @@ async function waitFor(condition = () => true, delay = 50) { /** * Matches a component tree rendererd using TestRenderer to a given expected JSON * snapshot. + * * @param {String} name * Name of the function derived from a test [step] name. * @param {Object} el diff --git a/devtools/client/shared/components/tree/TreeView.mjs b/devtools/client/shared/components/tree/TreeView.mjs @@ -170,6 +170,7 @@ class TreeView extends Component { /** * Creates a set with the paths of the nodes that should be expanded by default * according to the passed options. + * * @param {Object} The root node of the tree. * @param {Object} [optional] An object with the following optional parameters: * - maxLevel: nodes nested deeper than this level won't be expanded. @@ -569,6 +570,7 @@ class TreeView extends Component { /** * Filter out nodes that don't correspond to the current filter. + * * @return {Boolean} true if the node should be visible otherwise false. */ onFilter(object) { diff --git a/devtools/client/shared/events.js b/devtools/client/shared/events.js @@ -5,6 +5,7 @@ /** * Prevent event default behaviour and stop its propagation. + * * @param {Object} event * Event or react synthetic event. */ diff --git a/devtools/client/shared/fluent-l10n/fluent-l10n.js b/devtools/client/shared/fluent-l10n/fluent-l10n.js @@ -14,6 +14,7 @@ class FluentL10n { /** * Initializes the wrapper, generating the bundles for the given resource ids. * It can optionally add the right attributes to the document element. + * * @param {Array} resourceIds * @param {Object} [options] * @param {boolean} [options.setAttributesOnDocument] diff --git a/devtools/client/shared/node-attribute-parser.js b/devtools/client/shared/node-attribute-parser.js @@ -299,6 +299,7 @@ var parsers = { /** * Parse an attribute value. + * * @param {String} namespaceURI The namespaceURI of the node that has the * attribute. * @param {String} tagName The tagName of the node that has the attribute. @@ -337,6 +338,7 @@ function parseAttribute( /** * Get the type for links in this attribute if any. + * * @param {String} namespaceURI The node's namespaceURI. * @param {String} tagName The node's tagName. * @param {Array} attributes The node's attributes, as a list of {name, value} @@ -389,6 +391,7 @@ function getAttribute(attributes, attributeName) { * Split a string by a given character and return an array of objects parts. * The array will contain objects for the split character too, marked with * TYPE_STRING type. + * * @param {String} value The string to parse. * @param {String} splitChar A 1 length split character. * @return {Array} diff --git a/devtools/client/shared/screenshot.js b/devtools/client/shared/screenshot.js @@ -61,6 +61,7 @@ async function captureAndSaveScreenshot(targetFront, window, args = {}) { /** * Take a screenshot of a browser element matching the passed target + * * @param {TargetFront} targetFront: The targetFront of the frame we want to take a screenshot of. * @param {Object} args: See args param in captureAndSaveScreenshot */ diff --git a/devtools/client/shared/source-map-loader/source-map.js b/devtools/client/shared/source-map-loader/source-map.js @@ -6,6 +6,7 @@ /** * Source Map Worker + * * @module utils/source-map-worker */ diff --git a/devtools/client/shared/source-map-loader/utils/sourceMapRequests.js b/devtools/client/shared/source-map-loader/utils/sourceMapRequests.js @@ -30,6 +30,7 @@ function clearSourceMaps() { /** * For a given generated source, retrieve an object with many attributes: + * * @param {String} generatedSourceId * The id of the generated source * diff --git a/devtools/client/shared/source-utils.js b/devtools/client/shared/source-utils.js @@ -334,6 +334,7 @@ function isWASM(location, i = 0) { * A utility method to get the file name from a sourcemapped location * The sourcemap location can be in any form. This method returns a * formatted file name for different cases like Windows or OSX. + * * @param source * @returns String */ diff --git a/devtools/client/shared/sourceeditor/editor.js b/devtools/client/shared/sourceeditor/editor.js @@ -890,7 +890,6 @@ class Editor extends EventEmitter { * @returns {Object} The object contains an extension and effects which used to trigger updates to the extension * {Object} - lineContentMarkerExtension - The line content marker extension * {Object} - lineContentMarkerEffect - The effects to add and remove markers - * */ #createlineContentMarkersExtension() { const { @@ -1127,6 +1126,7 @@ class Editor extends EventEmitter { /** * Adds the DOM event handlers for the editor. + * * @param {Object} domEventHandlers - A dictionary of handlers for the DOM events * the handlers are getting called with the following arguments * - {Object} `event`: The DOM event @@ -1170,6 +1170,7 @@ class Editor extends EventEmitter { /** * Remove specified DOM event handlers for the editor. + * * @param {Object} domEventHandlers - A dictionary of handlers for the DOM events */ removeEditorDOMEventListeners(domEventHandlers) { @@ -1217,6 +1218,7 @@ class Editor extends EventEmitter { /** * This adds a marker used to add classes to editor line based on a condition. + * * @property {object} marker * The rule rendering a marker or class. * @property {object} marker.id @@ -1246,6 +1248,7 @@ class Editor extends EventEmitter { /** * This removes the marker which has the specified className + * * @param {string} markerId - The unique identifier for this marker */ removeLineContentMarker(markerId) { @@ -1537,6 +1540,7 @@ class Editor extends EventEmitter { /** * This adds a marker used to decorate token / content at a specific position . + * * @param {Object} marker * @param {String} marker.id * @param {Array<Object>} marker.positions - This includes the line / column and any optional positionData which defines each position. @@ -1560,6 +1564,7 @@ class Editor extends EventEmitter { /** * This removes the marker which has the specified id + * * @param {string} markerId - The unique identifier for this marker */ removePositionContentMarker(markerId) { @@ -1573,6 +1578,7 @@ class Editor extends EventEmitter { /** * Set event listeners for the line gutter + * * @param {Object} domEventHandlers * * example usage: @@ -1728,6 +1734,7 @@ class Editor extends EventEmitter { /** * This creates the extension used to manage the rendering of markers for * results for any search pattern + * * @param {RegExp} pattern - The search pattern * @param {String} className - The class used to decorate each result * @returns {Array<ViewPlugin>} An extension which is an array containing the view @@ -1891,6 +1898,7 @@ class Editor extends EventEmitter { /** * Gets the position information for the current selection + * * @returns {Object} cursor - The location information for the current selection * cursor.from - An object with the starting line / column of the selection * cursor.to - An object with the end line / column of the selection @@ -1920,6 +1928,7 @@ class Editor extends EventEmitter { /** * Gets the text content for the current selection + * * @returns {String} */ getSelectedText() { @@ -1935,6 +1944,7 @@ class Editor extends EventEmitter { * Given screen coordinates this should return the line and column * related. This used currently to determine the line and columns * for the tokens that are hovered over. + * * @param {Number} left - Horizontal position from the left * @param {Number} top - Vertical position from the top * @returns {Object} position - The line and column related to the screen coordinates. @@ -1968,6 +1978,7 @@ class Editor extends EventEmitter { /** * Check that text is selected + * * @returns {Boolean} */ isTextSelected() { @@ -3429,6 +3440,7 @@ class Editor extends EventEmitter { /** * Gets the element at the specified codemirror offset + * * @param {Number} offset * @return {Element|null} */ @@ -3449,6 +3461,7 @@ class Editor extends EventEmitter { /** * This checks if the specified position (line/column) is within the current viewport * bounds. it helps determine if scrolling should happen. + * * @param {Number} line - The line in the source * @param {Number} column - The column in the source * @returns {Boolean} @@ -3507,6 +3520,7 @@ class Editor extends EventEmitter { /** * Converts line/col to CM6 offset position + * * @param {Number} line - The line in the source * @param {Number} col - The column in the source * @returns {Number} @@ -3561,6 +3575,7 @@ class Editor extends EventEmitter { /** * Scrolls the editor to the specified line and column + * * @param {Number} line - The line in the source * @param {Number} column - The column in the source * @param {String|null} yAlign - Optional value for position of the line after the line is scrolled. @@ -3631,6 +3646,7 @@ class Editor extends EventEmitter { * Move CodeMirror cursor to a given location. * This will also scroll the editor to the specified position. * Used only for CM6 + * * @param {Number} line * @param {Number} column */ diff --git a/devtools/client/shared/sourceeditor/lezer-utils.js b/devtools/client/shared/sourceeditor/lezer-utils.js @@ -494,6 +494,7 @@ async function walkTree(view, language, options) { /** * This enables walking a specific part of the syntax tree using the cursor * provided by the node (which is the parent) + * * @param {Object} cursor - https://lezer.codemirror.net/docs/ref/#common.TreeCursor * @param {Object} options * {Function} options.enterVisitor - A function that is called when a node is entered diff --git a/devtools/client/shared/sourceeditor/test/head.js b/devtools/client/shared/sourceeditor/test/head.js @@ -80,6 +80,7 @@ function teardown(ed, win) { * is either not common-enough to be in head.js, or that is located in a * separate directory. * The script will be loaded synchronously and in the test's scope. + * * @param {String} filePath The file path, relative to the current directory. * Examples: * - "helper_attributes_test_runner.js" @@ -130,6 +131,7 @@ function read(url) { /** * This function is called by the CodeMirror test runner to report status * messages from the CM tests. + * * @see codemirror.html */ function codemirrorSetStatus(statusMsg, type, customMsg) { diff --git a/devtools/client/shared/telemetry.js b/devtools/client/shared/telemetry.js @@ -420,7 +420,6 @@ class Telemetry { * * @param {String} id * The ID of the tool that has been opened. - * */ // eslint-disable-next-line complexity function getChartsFromToolId(id) { diff --git a/devtools/client/shared/test/browser_filter-presets-01.js b/devtools/client/shared/test/browser_filter-presets-01.js @@ -104,6 +104,7 @@ add_task(async function () { /** * Call savePreset on widget and wait for the specified event to emit + * * @param {CSSFilterWidget} widget * @param {string} expectEvent="render" The event to listen on * @return {Promise} diff --git a/devtools/client/shared/test/head.js b/devtools/client/shared/test/head.js @@ -132,6 +132,7 @@ const createHost = async function ( /** * Open and close the toolbox in the current browser tab, several times, waiting * some amount of time in between. + * * @param {Number} nbOfTimes * @param {Number} usageTime in milliseconds * @param {String} toolId @@ -153,6 +154,7 @@ async function openAndCloseToolbox(nbOfTimes, usageTime, toolId) { /** * Show the presets list sidebar in the cssfilter widget popup + * * @param {CSSFilterWidget} widget * @return {Promise} */ @@ -164,6 +166,7 @@ function showFilterPopupPresets(widget) { /** * Show presets list and create a sample preset with the name and value provided + * * @param {CSSFilterWidget} widget * @param {string} name * @param {string} value diff --git a/devtools/client/shared/test/highlighter-test-actor.js b/devtools/client/shared/test/highlighter-test-actor.js @@ -47,6 +47,7 @@ const dumpn = msg => { * highlighter actor. * The instance provides methods to get/set attributes/text/style on nodes of * the highlighter, inserted into the nsCanvasFrame. + * * @see /devtools/server/actors/highlighters.js * @param {String} actorID */ @@ -221,6 +222,7 @@ class HighlighterTestActor extends protocol.Actor { /** * Helper to retrieve a DOM element. + * * @param {string | array} selector Either a regular selector string * or a selector array. If an array, each item, except the last one * are considered matching an iframe, so that we can query element @@ -269,6 +271,7 @@ class HighlighterTestActor extends protocol.Actor { /** * Get a value for a given attribute name, on one of the elements of the box * model highlighter, given its ID. + * * @param {String} nodeID The full ID of the element to get the attribute for * @param {String} name The name of the attribute to get * @param {String} actorID The highlighter actor ID @@ -304,6 +307,7 @@ class HighlighterTestActor extends protocol.Actor { /** * Get the computed style for a given property, on one of the elements of the * box model highlighter, given its ID. + * * @param {String} nodeID The full ID of the element to get the attribute for * @param {String} property The name of the property * @param {String} actorID The highlighter actor ID @@ -322,6 +326,7 @@ class HighlighterTestActor extends protocol.Actor { /** * Get the textcontent of one of the elements of the box model highlighter, * given its ID. + * * @param {String} nodeID The full ID of the element to get the attribute for * @param {String} actorID The highlighter actor ID * @return {String} The textcontent value @@ -337,6 +342,7 @@ class HighlighterTestActor extends protocol.Actor { /** * Get the number of box-model highlighters created by the SelectorHighlighter + * * @param {String} actorID The highlighter actor ID * @return {Number} The number of box-model highlighters created, or null if the * SelectorHighlighter was not found. @@ -354,6 +360,7 @@ class HighlighterTestActor extends protocol.Actor { * Subscribe to the box-model highlighter's update event, modify an attribute of * the currently highlighted node and send a message when the highlighter has * updated. + * * @param {String} the name of the attribute to be changed * @param {String} the new value for the attribute * @param {String} actorID The highlighter actor ID @@ -590,6 +597,7 @@ class HighlighterTestFront extends protocol.FrontClassWithSpec( /** * Get the value of an attribute on one of the highlighter's node. + * * @param {String} nodeID The Id of the node in the highlighter. * @param {String} name The name of the attribute. * @param {Object} highlighter Optional custom highlighter to target @@ -612,6 +620,7 @@ class HighlighterTestFront extends protocol.FrontClassWithSpec( /** * Get the computed style of a property on one of the highlighter's node. + * * @param {String} nodeID The Id of the node in the highlighter. * @param {String} property The name of the property. * @param {Object} highlighter Optional custom highlighter to target @@ -692,6 +701,7 @@ class HighlighterTestFront extends protocol.FrontClassWithSpec( /** * Check that the box-model highlighter is currently highlighting the node matching the * given selector. + * * @param {String} selector * @return {Boolean} */ @@ -704,6 +714,7 @@ class HighlighterTestFront extends protocol.FrontClassWithSpec( * Check that the box-model highlighter is currently highlighting the text node that can * be found at a given index within the list of childNodes of a parent element matching * the given selector. + * * @param {String} parentSelector * @param {Number} childNodeIndex * @return {Boolean} @@ -715,6 +726,7 @@ class HighlighterTestFront extends protocol.FrontClassWithSpec( /** * Check that the box-model highlighter is currently highlighting the given rect. + * * @param {Object} rect * @return {Boolean} */ @@ -825,6 +837,7 @@ class HighlighterTestFront extends protocol.FrontClassWithSpec( /** * Get the coordinates of the rectangle that is defined by the 4 guides displayed * in the toolbox box-model highlighter. + * * @return {Object} Null if at least one guide is hidden. Otherwise an object * with p1, p2, p3, p4 properties being {x, y} objects. */ @@ -854,6 +867,7 @@ class HighlighterTestFront extends protocol.FrontClassWithSpec( /** * Get the "d" attribute value for one of the box-model highlighter's region * <path> elements, and parse it to a list of points. + * * @param {String} region The box model region name. * @param {Front} highlighter The front of the highlighter. * @return {Object} The object returned has the following form: @@ -896,6 +910,7 @@ protocol.registerFront(HighlighterTestFront); * Check whether a point is included in a polygon. * Taken and tweaked from: * https://github.com/iominh/point-in-polygon-extended/blob/master/src/index.js#L30-L85 + * * @param {Array} point [x,y] coordinates * @param {Array} polygon An array of [x,y] points * @return {Boolean} diff --git a/devtools/client/shared/test/shared-head.js b/devtools/client/shared/test/shared-head.js @@ -543,6 +543,7 @@ function waitForAllTargetsToBeAttached(targetCommand) { /** * Add a new test tab in the browser and load the given url. + * * @param {String} url The url to be loaded in the new tab * @param {Object} options Object with various optional fields: * - {Boolean} background If true, open the tab in background @@ -589,6 +590,7 @@ async function addTab(url, options = {}) { /** * Remove the given tab. + * * @param {Object} tab The tab to be removed. * @return Promise<undefined> resolved when the tab is successfully removed. */ @@ -1025,6 +1027,7 @@ async function createAndAttachTargetForTab(tab) { /** * Open the inspector in a tab with given URL. + * * @param {string} url The URL to open. * @param {String} hostType Optional hostType, as defined in Toolbox.HostType * @return A promise that is resolved once the tab and inspector have loaded @@ -1070,6 +1073,7 @@ var waitForTime = DevToolsUtils.waitForTime; /** * Wait for a tick. + * * @return {Promise} */ function waitForTick() { @@ -1278,6 +1282,7 @@ function once(target, eventName, useCapture = false) { * is either not common-enough to be in head.js, or that is located in a * separate directory. * The script will be loaded synchronously and in the test's scope. + * * @param {String} filePath The file path, relative to the current directory. * Examples: * - "helper_attributes_test_runner.js" @@ -1289,6 +1294,7 @@ function loadHelperScript(filePath) { /** * Open the toolbox in a given tab. + * * @param {XULNode} tab The tab the toolbox should be opened in. * @param {String} toolId Optional. The ID of the tool to be selected. * @param {String} hostType Optional. The type of toolbox host to be used. @@ -1319,6 +1325,7 @@ async function openToolboxForTab(tab, toolId, hostType) { /** * Add a new tab and open the toolbox in it. + * * @param {String} url The URL for the tab to be opened. * @param {String} toolId Optional. The ID of the tool to be selected. * @param {String} hostType Optional. The type of toolbox host to be used. @@ -1332,6 +1339,7 @@ async function openNewTabAndToolbox(url, toolId, hostType) { /** * Close a tab and if necessary, the toolbox that belongs to it + * * @param {Tab} tab The tab to close. * @return {Promise} Resolves when the toolbox and tab have been destroyed and * closed. @@ -1348,6 +1356,7 @@ async function closeTabAndToolbox(tab = gBrowser.selectedTab) { /** * Close a toolbox and the current tab. + * * @param {Toolbox} toolbox The toolbox to close. * @return {Promise} Resolves when the toolbox and tab have been destroyed and * closed. @@ -1790,6 +1799,7 @@ function checkImageColorAt({ image, x = 0, y, expectedColor, label }) { /** * Wait until the store has reached a state that matches the predicate. + * * @param Store store * The Redux store being used. * @param function predicate @@ -2526,6 +2536,7 @@ async function toggleJsTracer(toolbox) { /** * Retrieve the context menu element corresponding to the provided id, for the * provided netmonitor instance. + * * @param {Object} monitor * The network monitor object * @param {String} id @@ -2539,6 +2550,7 @@ function getNetmonitorContextMenuItem(monitor, id) { /** * Selects and clicks the context menu item of the netmonitor, it should * also wait for the popup to close. + * * @param {Object} monitor * The network monitor object * @param {String} id diff --git a/devtools/client/shared/widgets/CubicBezierWidget.js b/devtools/client/shared/widgets/CubicBezierWidget.js @@ -39,6 +39,7 @@ const XHTML_NS = "http://www.w3.org/1999/xhtml"; /** * CubicBezier data structure helper * Accepts an array of coordinates and exposes a few useful getters + * * @param {Array} coordinates i.e. [.42, 0, .58, 1] */ function CubicBezier(coordinates) { @@ -87,6 +88,7 @@ CubicBezier.prototype = { /** * Bezier curve canvas plotting class + * * @param {DOMNode} canvas * @param {CubicBezier} bezier * @param {Array} padding Amount of horizontal,vertical padding around the graph @@ -112,6 +114,7 @@ exports.BezierCanvas = BezierCanvas; BezierCanvas.prototype = { /** * Get P1 and P2 current top/left offsets so they can be positioned + * * @return {Array} Returns an array of 2 {top:String,left:String} objects */ get offsets() { @@ -225,6 +228,7 @@ BezierCanvas.prototype = { /** * Cubic-bezier widget. Uses the BezierCanvas class to draw the curve and * adds the control points and user interaction + * * @param {DOMNode} parent The container where the graph should be created * @param {Array} coordinates Coordinates of the curve to be drawn * @@ -497,6 +501,7 @@ CubicBezierWidget.prototype = { /** * Redraw the curve + * * @param {Array} coordinates The array of control point coordinates */ _redraw(coordinates) { @@ -512,6 +517,7 @@ CubicBezierWidget.prototype = { /** * Set new coordinates for the control points and redraw the curve + * * @param {Array} coordinates */ set coordinates(coordinates) { @@ -527,6 +533,7 @@ CubicBezierWidget.prototype = { /** * Set new coordinates for the control point and redraw the curve + * * @param {String} value A string value. E.g. "linear", * "cubic-bezier(0,0,1,1)" */ @@ -568,6 +575,7 @@ CubicBezierWidget.prototype = { /** * CubicBezierPreset widget. * Builds a menu of presets from CubicBezierPresets + * * @param {DOMNode} parent The container where the preset panel should be * created * @@ -777,6 +785,7 @@ CubicBezierPresetWidget.prototype = { * the curve is modified via the canvas. * Attempts to match the new user setting with an * existing preset. + * * @param {Array} coordinates new coords [i, j, k, l] */ refreshMenu(coordinates) { @@ -818,6 +827,7 @@ CubicBezierPresetWidget.prototype = { /** * The TimingFunctionPreviewWidget animates a dot on a scale with a given * timing-function + * * @param {DOMNode} parent The container where this widget should go */ function TimingFunctionPreviewWidget(parent) { @@ -857,6 +867,7 @@ TimingFunctionPreviewWidget.prototype = { * Preview a new timing function. The current preview will only be stopped if * the supplied function value is different from the previous one. If the * supplied function is invalid, the preview will stop. + * * @param {String} value */ preview(value) { @@ -874,6 +885,7 @@ TimingFunctionPreviewWidget.prototype = { /** * Re-start the preview animation from the beginning. + * * @param {String} timingFunction The value for the timing-function. */ restartAnimation(timingFunction) { @@ -953,6 +965,7 @@ function distance(x1, y1, x2, y2) { * Parse a string to see whether it is a valid timing function. * If it is, return the coordinates as an array. * Otherwise, return undefined. + * * @param {String} value * @return {Array} of coordinates, or undefined */ @@ -1000,6 +1013,7 @@ exports.parseTimingFunction = parseTimingFunction; /** * Removes a class from a node and adds it to another. + * * @param {String} className the class to swap * @param {DOMNode} from the node to remove the class from * @param {DOMNode} to the node to add the class to @@ -1016,6 +1030,7 @@ function swapClassName(className, from, to) { /** * Compares two arrays of coordinates [i, j, k, l] + * * @param {Array} c1 first coordinate array to compare * @param {Array} c2 second coordinate array to compare * @return {Boolean} diff --git a/devtools/client/shared/widgets/LinearEasingFunctionWidget.js b/devtools/client/shared/widgets/LinearEasingFunctionWidget.js @@ -30,7 +30,6 @@ const percentFormatter = new Intl.NumberFormat("en", { * only handle points inside [0,0] [1,1] to represent most common use cases (even though * the line will properly link points outside of this range) * - * * @emits "updated" events whenever the line is changed, with the updated property value. */ class LinearEasingFunctionWidget extends EventEmitter { @@ -533,6 +532,7 @@ class TimingFunctionPreviewWidget { * Preview a new timing function. The current preview will only be stopped if * the supplied function value is different from the previous one. If the * supplied function is invalid, the preview will stop. + * * @param {Array} value */ preview(timingFunction) { @@ -545,6 +545,7 @@ class TimingFunctionPreviewWidget { /** * Re-start the preview animation from the beginning. + * * @param {Array} points */ #restartAnimation = throttle(timingFunction => { diff --git a/devtools/client/shared/widgets/tooltip/HTMLTooltip.js b/devtools/client/shared/widgets/tooltip/HTMLTooltip.js @@ -839,6 +839,7 @@ HTMLTooltip.prototype = { /** * Check if the tooltip is currently displayed. + * * @return {Boolean} true if the tooltip is visible */ isVisible() { diff --git a/devtools/client/shared/widgets/tooltip/TooltipToggle.js b/devtools/client/shared/widgets/tooltip/TooltipToggle.js @@ -151,6 +151,7 @@ TooltipToggle.prototype = { /** * Is the given target DOMNode a valid node for toggling the tooltip on hover. * This delegates to the user-defined _targetNodeCb callback. + * * @return {Promise} a promise that will resolve the anchor to use for the * tooltip or null if no valid target was found. */ diff --git a/devtools/client/shared/widgets/tooltip/css-compatibility-tooltip-helper.js b/devtools/client/shared/widgets/tooltip/css-compatibility-tooltip-helper.js @@ -251,7 +251,6 @@ class CssCompatibilityTooltipHelper { * * @param {DOMEvent} event * The click event originating from the tooltip. - * */ addTab(event) { // The XUL panel swallows click events so handlers can't be added directly diff --git a/devtools/client/shared/widgets/tooltip/inactive-css-tooltip-helper.js b/devtools/client/shared/widgets/tooltip/inactive-css-tooltip-helper.js @@ -90,7 +90,6 @@ class InactiveCssTooltipHelper { * * @param {DOMEvent} event * The click event originating from the tooltip. - * */ addTab(event) { // The XUL panel swallows click events so handlers can't be added directly diff --git a/devtools/client/shared/widgets/view-helpers.js b/devtools/client/shared/widgets/view-helpers.js @@ -32,6 +32,7 @@ exports.setNamedTimeout = setNamedTimeout; /** * Clears a named timeout. + * * @see setNamedTimeout * * @param string id @@ -407,6 +408,7 @@ Item.prototype = { /** * Returns a string representing the object. * Avoid using `toString` to avoid accidental JSONification. + * * @return string */ stringify() { diff --git a/devtools/client/storage/VariablesView.sys.mjs b/devtools/client/storage/VariablesView.sys.mjs @@ -195,6 +195,7 @@ VariablesView.prototype = { /** * Specifies if this view may be emptied lazily. + * * @see VariablesView.prototype.empty */ lazyEmpty: false, @@ -225,6 +226,7 @@ VariablesView.prototype = { /** * Specifies if enumerable properties and variables should be displayed. * These variables and properties are visible by default. + * * @param boolean aFlag */ set enumVisible(aFlag) { @@ -238,6 +240,7 @@ VariablesView.prototype = { /** * Specifies if non-enumerable properties and variables should be displayed. * These variables and properties are visible by default. + * * @param boolean aFlag */ set nonEnumVisible(aFlag) { @@ -251,6 +254,7 @@ VariablesView.prototype = { /** * Specifies if only enumerable properties and variables should be displayed. * Both types of these variables and properties are visible by default. + * * @param boolean aFlag */ set onlyEnumVisible(aFlag) { @@ -265,6 +269,7 @@ VariablesView.prototype = { /** * Sets if the variable and property searching is enabled. + * * @param boolean aFlag */ set searchEnabled(aFlag) { @@ -273,6 +278,7 @@ VariablesView.prototype = { /** * Gets if the variable and property searching is enabled. + * * @return boolean */ get searchEnabled() { @@ -737,6 +743,7 @@ VariablesView.prototype = { /** * Sets the text displayed in this container when there are no available items. + * * @param string aValue */ set emptyText(aValue) { @@ -777,6 +784,7 @@ VariablesView.prototype = { /** * Gets if all values should be aligned together. + * * @return boolean */ get alignedValues() { @@ -785,6 +793,7 @@ VariablesView.prototype = { /** * Sets if all values should be aligned together. + * * @param boolean aFlag */ set alignedValues(aFlag) { @@ -799,6 +808,7 @@ VariablesView.prototype = { /** * Gets if action buttons (like delete) should be placed at the beginning or * end of a line. + * * @return boolean */ get actionsFirst() { @@ -808,6 +818,7 @@ VariablesView.prototype = { /** * Sets if action buttons (like delete) should be placed at the beginning or * end of a line. + * * @param boolean aFlag */ set actionsFirst(aFlag) { @@ -821,6 +832,7 @@ VariablesView.prototype = { /** * Gets the parent node holding this view. + * * @return Node */ get parentNode() { @@ -829,6 +841,7 @@ VariablesView.prototype = { /** * Gets the owner document holding this view. + * * @return HTMLDocument */ get document() { @@ -837,6 +850,7 @@ VariablesView.prototype = { /** * Gets the default window holding this view. + * * @return nsIDOMWindow */ get window() { @@ -1270,6 +1284,7 @@ Scope.prototype = { /** * Gets the visibility state. + * * @return boolean */ get visible() { @@ -1278,6 +1293,7 @@ Scope.prototype = { /** * Gets the expanded state. + * * @return boolean */ get expanded() { @@ -1286,6 +1302,7 @@ Scope.prototype = { /** * Gets the header visibility state. + * * @return boolean */ get header() { @@ -1294,6 +1311,7 @@ Scope.prototype = { /** * Gets the twisty visibility state. + * * @return boolean */ get twisty() { @@ -1301,6 +1319,7 @@ Scope.prototype = { }, /** * Sets the visibility state. + * * @param boolean aFlag */ set visible(aFlag) { @@ -1309,6 +1328,7 @@ Scope.prototype = { /** * Sets the expanded state. + * * @param boolean aFlag */ set expanded(aFlag) { @@ -1317,6 +1337,7 @@ Scope.prototype = { /** * Sets the header visibility state. + * * @param boolean aFlag */ set header(aFlag) { @@ -1325,6 +1346,7 @@ Scope.prototype = { /** * Sets the twisty visibility state. + * * @param boolean aFlag */ set twisty(aFlag) { @@ -1333,6 +1355,7 @@ Scope.prototype = { /** * Specifies if this target node may be focused. + * * @return boolean */ get focusable() { @@ -1366,6 +1389,7 @@ Scope.prototype = { /** * Adds an event listener for a certain event on this scope's title. + * * @param string aName * @param function aCallback * @param boolean aCapture @@ -1376,6 +1400,7 @@ Scope.prototype = { /** * Removes an event listener for a certain event on this scope's title. + * * @param string aName * @param function aCallback * @param boolean aCapture @@ -1386,6 +1411,7 @@ Scope.prototype = { /** * Gets the id associated with this item. + * * @return string */ get id() { @@ -1394,6 +1420,7 @@ Scope.prototype = { /** * Gets the name associated with this item. + * * @return string */ get name() { @@ -1402,6 +1429,7 @@ Scope.prototype = { /** * Gets the displayed value for this item. + * * @return string */ get displayValue() { @@ -1410,6 +1438,7 @@ Scope.prototype = { /** * Gets the class names used for the displayed value. + * * @return string */ get displayValueClassName() { @@ -1418,6 +1447,7 @@ Scope.prototype = { /** * Gets the element associated with this item. + * * @return Node */ get target() { @@ -1527,6 +1557,7 @@ Scope.prototype = { /** * Specifies if enumerable properties and variables should be displayed. + * * @param boolean aFlag */ set _enumVisible(aFlag) { @@ -1546,6 +1577,7 @@ Scope.prototype = { /** * Specifies if non-enumerable properties and variables should be displayed. + * * @param boolean aFlag */ set _nonEnumVisible(aFlag) { @@ -1615,6 +1647,7 @@ Scope.prototype = { /** * Sets if this object instance is a matched or non-matched item. + * * @param boolean aStatus */ set _matched(aStatus) { @@ -1715,6 +1748,7 @@ Scope.prototype = { /** * Gets top level variables view instance. + * * @return VariablesView */ get _variablesView() { @@ -1734,6 +1768,7 @@ Scope.prototype = { /** * Gets the parent node holding this scope. + * * @return Node */ get parentNode() { @@ -1742,6 +1777,7 @@ Scope.prototype = { /** * Gets the owner document holding this scope. + * * @return HTMLDocument */ get document() { @@ -1750,6 +1786,7 @@ Scope.prototype = { /** * Gets the default window holding this scope. + * * @return nsIDOMWindow */ get window() { @@ -1987,6 +2024,7 @@ Variable.prototype = extend(Scope.prototype, { * Gets this variable's path to the topmost scope in the form of a string * meant for use via eval() or a similar approach. * For example, a symbolic name may look like "arguments['0']['foo']['bar']". + * * @return string */ get symbolicName() { @@ -1995,6 +2033,7 @@ Variable.prototype = extend(Scope.prototype, { /** * Gets full path to this variable, including name of the scope. + * * @return string */ get absoluteName() { @@ -2009,6 +2048,7 @@ Variable.prototype = extend(Scope.prototype, { /** * Gets this variable's symbolic path to the topmost scope. + * * @return array * @see Variable._buildSymbolicPath */ @@ -2024,6 +2064,7 @@ Variable.prototype = extend(Scope.prototype, { * Build this variable's path to the topmost scope in form of an array of * strings, one for each segment of the path. * For example, a symbolic path may look like ["0", "foo", "bar"]. + * * @return array */ _buildSymbolicPath(path = []) { @@ -2038,6 +2079,7 @@ Variable.prototype = extend(Scope.prototype, { /** * Returns this variable's value from the descriptor if available. + * * @return any */ get value() { @@ -2046,6 +2088,7 @@ Variable.prototype = extend(Scope.prototype, { /** * Returns this variable's getter from the descriptor if available. + * * @return object */ get getter() { @@ -2054,6 +2097,7 @@ Variable.prototype = extend(Scope.prototype, { /** * Returns this variable's getter from the descriptor if available. + * * @return object */ get setter() { diff --git a/devtools/client/storage/test/head.js b/devtools/client/storage/test/head.js @@ -539,6 +539,7 @@ async function selectTableItem(id) { /** * Wait for eventName on target. + * * @param {Object} target An observable object that either supports on/off or * addEventListener/removeEventListener * @param {String} eventName @@ -948,6 +949,7 @@ async function checkState(state) { /** * Checks if document's active element is within the given element. + * * @param {HTMLDocument} doc document with active element in question * @param {DOMNode} container element tested on focus containment * @return {Boolean} @@ -1031,6 +1033,7 @@ function sidebarParseTreeVisible(state) { /** * Add an item. + * * @param {Array} store * An array containing the path to the store to which we wish to add an * item. @@ -1096,6 +1099,7 @@ async function scroll() { /** * Asserts that the given tree path exists + * * @param {Document} doc * @param {Array} path * @param {Boolean} isExpected @@ -1110,6 +1114,7 @@ function checkTree(doc, path, isExpected = true) { /** * Returns whether a tree path exists + * * @param {Document} doc * @param {Array} path */ @@ -1120,6 +1125,7 @@ function isInTree(doc, path) { /** * Returns the label of the node for the provided tree path + * * @param {Document} doc * @param {Array} path * @returns {String} @@ -1132,6 +1138,7 @@ function getTreeNodeLabel(doc, path) { /** * Checks that the pair <name, value> is displayed at the data table + * * @param {String} name * @param {any} value */ @@ -1150,6 +1157,7 @@ async function waitForStorageData(name, value) { /** * Returns whether the pair <name, value> is displayed at the data table + * * @param {String} name * @param {any} value */ @@ -1159,6 +1167,7 @@ function hasStorageData(name, value) { /** * Returns an URL of a page that uses the document-builder to generate its content + * * @param {String} domain * @param {String} html * @param {String} protocol @@ -1169,6 +1178,7 @@ function buildURLWithContent(domain, html, protocol = "https") { /** * Asserts that the given cookie holds the provided value in the data table + * * @param {String} name * @param {String} value */ @@ -1181,6 +1191,7 @@ function checkCookieData(name, value) { /** * Returns whether the given cookie holds the provided value in the data table + * * @param {String} name * @param {String} value */ diff --git a/devtools/client/styleeditor/StyleEditorUtil.sys.mjs b/devtools/client/styleeditor/StyleEditorUtil.sys.mjs @@ -147,6 +147,7 @@ export function showFilePicker( /** * Returns a Popup Menu for the Options ("gear") Button + * * @param {function} toggleOrigSources * To toggle the original source pref * @param {function} toggleAtRulesSidebar diff --git a/devtools/client/styleeditor/StyleSheetEditor.sys.mjs b/devtools/client/styleeditor/StyleSheetEditor.sys.mjs @@ -417,6 +417,7 @@ StyleSheetEditor.prototype = { /** * Called when the stylesheet text changes. + * * @param {Object} update: The stylesheet resource update packet. */ async onStyleApplied(update) { @@ -481,6 +482,7 @@ StyleSheetEditor.prototype = { /** * Create source editor and load state into it. + * * @param {DOMElement} inputElement * Element to load source editor in * @param {CssProperties} cssProperties diff --git a/devtools/client/styleeditor/test/head.js b/devtools/client/styleeditor/test/head.js @@ -21,6 +21,7 @@ const TEST_HOST = "mochi.test:8888"; /** * Add a new test tab in the browser and load the given url. + * * @param {String} url The url to be loaded in the new tab * @param {Window} win The window to add the tab to (default: current window). * @return a promise that resolves to the tab object when the url is loaded diff --git a/devtools/client/webconsole/actions/autocomplete.js b/devtools/client/webconsole/actions/autocomplete.js @@ -95,6 +95,7 @@ function autocompleteUpdate(force, getterPath, expressionVars) { /** * Combine or replace authorizedEvaluations with the newly authorized getter path, if any. + * * @param {Array<Array<String>>} authorizedEvaluations Existing authorized evaluations (may * be updated in place) * @param {Array<String>} getterPath The new getter path @@ -146,6 +147,7 @@ function updateAuthorizedEvaluations( /** * Apply source mapping to the autocomplete input. + * * @param {String} rawInput The input to map. * @param {{[String]: String}} mappedVars Map of original to generated variable names. * @param {WebConsole} hud A reference to the webconsole hud. @@ -308,6 +310,7 @@ function autocompleteDataFetch({ /** * Replace generated variable names in an unsafe getter path with their original * counterparts. + * * @param {Array<String>} getterPath Array of properties leading up to and including the * unsafe getter. * @param {String} originalExpression The expression that was evaluated, before mapping. diff --git a/devtools/client/webconsole/components/Input/JSTerm.js b/devtools/client/webconsole/components/Input/JSTerm.js @@ -171,6 +171,7 @@ class JSTerm extends Component { /** * Last input value. + * * @type string */ this.lastInputValue = ""; @@ -764,6 +765,7 @@ class JSTerm extends Component { /** * Gets the value from the input field + * * @returns string */ _getValue() { @@ -1216,6 +1218,7 @@ class JSTerm extends Component { /** * Clear the current completion information, cancel any pending autocompletion update * and close the autocomplete popup, if needed. + * * @fires autocomplete-updated */ clearCompletion() { diff --git a/devtools/client/webconsole/reducers/messages.js b/devtools/client/webconsole/reducers/messages.js @@ -1110,6 +1110,7 @@ function getToplevelMessageCount(state) { /** * Check if a message should be visible in the console output, and if not, what * causes it to be hidden. + * * @param {Message} message: The message to check * @param {Object} option: An option object of the following shape: * - {MessageState} messagesState: The current messages state diff --git a/devtools/client/webconsole/test/browser/browser_webconsole_console_trace_distinct.js b/devtools/client/webconsole/test/browser/browser_webconsole_console_trace_distinct.js @@ -54,6 +54,7 @@ add_task(async function () { /** * Get all the stacktrace `.frames` elements displayed in the console output. + * * @returns {Array<HTMLElement>} */ function getFrames(hud) { @@ -62,6 +63,7 @@ function getFrames(hud) { /** * Given a stacktrace element, return an array of the frame names displayed in it. + * * @param {HTMLElement} traceEl * @returns {Array<String>} */ diff --git a/devtools/client/webconsole/test/browser/browser_webconsole_output_trimmed.js b/devtools/client/webconsole/test/browser/browser_webconsole_output_trimmed.js @@ -73,6 +73,7 @@ add_task(async function () { /** * Get the text content of the latest command logged in the console + * * @param {WebConsole} hud: The webconsole * @return {string|null} */ diff --git a/devtools/client/webconsole/test/browser/browser_webconsole_requestStorageAccess_errors.js b/devtools/client/webconsole/test/browser/browser_webconsole_requestStorageAccess_errors.js @@ -20,6 +20,7 @@ registerCleanupFunction(function () { /** * Run document.requestStorageAccess in an iframe. + * * @param {Object} options - Request / iframe options. * @param {boolean} [options.withUserActivation] - Whether the requesting iframe * should have user activation prior to calling rsA. diff --git a/devtools/client/webconsole/test/browser/head.js b/devtools/client/webconsole/test/browser/head.js @@ -1372,6 +1372,7 @@ function getConfirmDialog(toolbox) { /** * Returns true if the Confirm Dialog is opened. + * * @param toolbox * @returns {Boolean} */ @@ -1401,6 +1402,7 @@ async function pauseDebugger(dbg, options) { /** * Check that the passed HTMLElement vertically overflows. + * * @param {HTMLElement} container * @returns {Boolean} */ @@ -1410,6 +1412,7 @@ function hasVerticalOverflow(container) { /** * Check that the passed HTMLElement is scrolled to the bottom. + * * @param {HTMLElement} container * @returns {Boolean} */ @@ -1547,6 +1550,7 @@ async function checkConsoleOutputForWarningGroup(hud, expectedMessages) { /** * Check that there is a message with the specified text that has the specified * stack information. Self-hosted frames are ignored. + * * @param {WebConsole} hud * @param {string} text * message substring to look for @@ -1600,6 +1604,7 @@ async function checkMessageStack(hud, text, expectedFrameLines) { /** * Reload the content page. + * * @returns {Promise} A promise that will return when the page is fully loaded (i.e., the * `load` event was fired). */ @@ -1777,6 +1782,7 @@ function selectTargetInContextSelector(hud, targetLabel) { /** * A helper that returns the size of the image that was just put into the clipboard by the * :screenshot command. + * * @return The {width, height} dimension object. */ async function getImageSizeFromClipboard() { diff --git a/devtools/client/webconsole/utils/messages.js b/devtools/client/webconsole/utils/messages.js @@ -928,6 +928,7 @@ function replaceURL(text, replacementText = "") { /** * Get the warningGroup type in which the message could be in. + * * @param {ConsoleMessage} message * @returns {String|null} null if the message can't be part of a warningGroup. */ @@ -988,6 +989,7 @@ function getParentWarningGroupMessageId(message) { /** * Returns true if the message is a warningGroup message (i.e. the "Header"). + * * @param {ConsoleMessage} message * @returns {Boolean} */ @@ -1004,6 +1006,7 @@ function isWarningGroup(message) { /** * Returns true if the message is an Enhanced Tracking Protection message. + * * @param {ConsoleMessage} message * @returns {Boolean} */ @@ -1019,6 +1022,7 @@ function isEnhancedTrackingProtectionMessage(message) { /** * Returns true if the message is a storage isolation message. + * * @param {ConsoleMessage} message * @returns {Boolean} */ @@ -1029,6 +1033,7 @@ function isStorageIsolationMessage(message) { /** * Returns true if the message is a tracking protection message. + * * @param {ConsoleMessage} message * @returns {Boolean} */ @@ -1039,6 +1044,7 @@ function isTrackingProtectionMessage(message) { /** * Returns true if the message is a cookie message. + * * @param {ConsoleMessage} message * @returns {Boolean} */ @@ -1054,6 +1060,7 @@ function isCookieMessage(message) { /** * Returns true if the message is a Content Security Policy (CSP) message. + * * @param {ConsoleMessage} message * @returns {Boolean} */ diff --git a/devtools/client/webconsole/webconsole-ui.js b/devtools/client/webconsole/webconsole-ui.js @@ -91,6 +91,7 @@ class WebConsoleUI { /** * Initialize the WebConsoleUI instance. + * * @return {Object} * A promise object that resolves once the frame is ready to use. */ @@ -730,6 +731,7 @@ class WebConsoleUI { /** * Sets the focus to JavaScript input field when the web console tab is * selected or when there is a split console present. + * * @private */ _onPanelSelected() { diff --git a/devtools/client/webconsole/webconsole-wrapper.js b/devtools/client/webconsole/webconsole-wrapper.js @@ -80,7 +80,6 @@ class WebConsoleWrapper { * @param {WebConsoleUI} webConsoleUI * @param {Toolbox} toolbox * @param {Document} document - * */ constructor(parentNode, webConsoleUI, toolbox, document) { EventEmitter.decorate(this); diff --git a/devtools/client/webconsole/webconsole.js b/devtools/client/webconsole/webconsole.js @@ -109,6 +109,7 @@ class WebConsole { * most cases, this will be |this.browserWindow|, but in some uses (such as * the Browser Toolbox), there is no browser window, so an alternative window * hosts the utilities there. + * * @type nsIDOMWindow */ get chromeUtilsWindow() { @@ -147,6 +148,7 @@ class WebConsole { /** * The JSTerm object that manages the console's input. + * * @see webconsole.js::JSTerm * @type object */ @@ -156,6 +158,7 @@ class WebConsole { /** * Get the value from the input field. + * * @returns {String|null} returns null if there's no input. */ getInputValue() { diff --git a/devtools/server/actors/accessibility/accessible.js b/devtools/server/actors/accessibility/accessible.js @@ -87,6 +87,7 @@ const CSS_TEXT_SELECTOR = "#text"; /** * Get node inforamtion such as nodeType and the unique CSS selector for the node. + * * @param {DOMNode} node * Node for which to get the information. * @return {Object} @@ -112,6 +113,7 @@ function getNodeDescription(node) { /** * Get a snapshot of the nsIAccessible object including its subtree. None of the subtree * queried here is cached via accessible walker's refMap. + * * @param {nsIAccessible} acc * Accessible object to take a snapshot of. * @param {nsIAccessibilityService} a11yService @@ -190,6 +192,7 @@ function getSnapshot(acc, a11yService, targetActor) { * An ARIA role token will be returned unless the role can't be mapped to an * ARIA role (e.g. <iframe>), in which case a Gecko role string will be * returned. + * * @param {nsIAccessible} acc * Accessible object to take a snapshot of. * @param {nsIAccessibilityService} a11yService @@ -552,6 +555,7 @@ class AccessibleActor extends Actor { /** * Run an accessibility audit for a given audit type. + * * @param {String} type * Type of an audit (Check AUDIT_TYPE in devtools/shared/constants * to see available audit types). diff --git a/devtools/server/actors/accessibility/audit/contrast.js b/devtools/server/actors/accessibility/audit/contrast.js @@ -65,6 +65,7 @@ loader.lazyGetter(this, "worker", () => new lazy.DevToolsWorker(WORKER_URL)); /** * Get canvas rendering context for the current target window bound by the bounds of the * accessible objects. + * * @param {Object} win * Current target window. * @param {Object} bounds diff --git a/devtools/server/actors/accessibility/audit/text-label.js b/devtools/server/actors/accessibility/audit/text-label.js @@ -35,6 +35,7 @@ const { /** * Check if the accessible is visible to the assistive technology. + * * @param {nsIAccessible} accessible * Accessible object to be tested for visibility. * @@ -50,6 +51,7 @@ function isVisible(accessible) { /** * Get related accessible objects that are targets of labelled by relation e.g. * labels. + * * @param {nsIAccessible} accessible * Accessible objects to get labels for. * @@ -422,6 +424,7 @@ const RULES = { /** * Perform audit for WCAG 1.1 criteria related to providing alternative text * depending on the type of content. + * * @param {nsIAccessible} accessible * Accessible object to be tested to determine if it requires and has * an appropriate text alternative. diff --git a/devtools/server/actors/accessibility/walker.js b/devtools/server/actors/accessibility/walker.js @@ -473,6 +473,7 @@ class AccessibleWalkerActor extends Actor { /** * Get an accessible actor for a domnode actor. + * * @param {Object} domNode * domnode actor for which accessible actor is being created. * @return {Promse} @@ -496,6 +497,7 @@ class AccessibleWalkerActor extends Actor { /** * Get a raw accessible object for a raw node. + * * @param {DOMNode} rawNode * Raw node for which accessible object is being retrieved. * @return {nsIAccessible} @@ -746,6 +748,7 @@ class AccessibleWalkerActor extends Actor { * (CSS, overlays) by load accessibility highlighter style sheet used for * preventing transitions and applying transparency when calculating colour * contrast as well as temporarily hiding accessible highlighter overlay. + * * @param {Object} win * Window where highlighting happens. */ @@ -770,6 +773,7 @@ class AccessibleWalkerActor extends Actor { * accessible object by unloading accessibility highlighter style sheet used * for preventing transitions and applying transparency when calculating * colour contrast and potentially restoring accessible highlighter overlay. + * * @param {Object} win * Window where highlighting was happenning. */ @@ -886,6 +890,7 @@ class AccessibleWalkerActor extends Actor { /** * Check if the DOM event received when picking shold be ignored. + * * @param {Event} event */ _ignoreEventWhenPicking(event) { diff --git a/devtools/server/actors/accessibility/worker.js b/devtools/server/actors/accessibility/worker.js @@ -42,6 +42,7 @@ function calculateLuminance(rgba) { * Get RGBA or a range of RGBAs for the background pixels under the text. If luminance is * uniform, only return one value of RGBA, otherwise return values that correspond to the * min and max luminances. + * * @param {ImageData} dataTextBuf * pixel data for the accessible object with text visible. * @param {ImageData} dataBackgroundBuf diff --git a/devtools/server/actors/animation.js b/devtools/server/actors/animation.js @@ -218,6 +218,7 @@ class AnimationPlayerActor extends Actor { * Get the name of this animation. This can be either the animation.id * property if it was set, or the keyframe rule name or the transition * property. + * * @return {String} */ getName() { @@ -234,6 +235,7 @@ class AnimationPlayerActor extends Actor { /** * Get the animation duration from this player, in milliseconds. + * * @return {Number} */ getDuration() { @@ -242,6 +244,7 @@ class AnimationPlayerActor extends Actor { /** * Get the animation delay from this player, in milliseconds. + * * @return {Number} */ getDelay() { @@ -250,6 +253,7 @@ class AnimationPlayerActor extends Actor { /** * Get the animation endDelay from this player, in milliseconds. + * * @return {Number} */ getEndDelay() { @@ -259,6 +263,7 @@ class AnimationPlayerActor extends Actor { /** * Get the animation iteration count for this player. That is, how many times * is the animation scheduled to run. + * * @return {Number} The number of iterations, or null if the animation repeats * infinitely. */ @@ -270,6 +275,7 @@ class AnimationPlayerActor extends Actor { /** * Get the animation iterationStart from this player, in ratio. * That is offset of starting position of the animation. + * * @return {Number} */ getIterationStart() { @@ -278,6 +284,7 @@ class AnimationPlayerActor extends Actor { /** * Get the animation easing from this player. + * * @return {String} */ getEasing() { @@ -286,6 +293,7 @@ class AnimationPlayerActor extends Actor { /** * Get the animation fill mode from this player. + * * @return {String} */ getFill() { @@ -294,6 +302,7 @@ class AnimationPlayerActor extends Actor { /** * Get the animation direction from this player. + * * @return {String} */ getDirection() { @@ -302,6 +311,7 @@ class AnimationPlayerActor extends Actor { /** * Get animation-timing-function from animated element if CSS Animations. + * * @return {String} */ getAnimationTimingFunction() { @@ -332,6 +342,7 @@ class AnimationPlayerActor extends Actor { /** * Return the current start of the Animation. + * * @return {Object} */ getState() { @@ -381,6 +392,7 @@ class AnimationPlayerActor extends Actor { * This protocol method only returns a trimed down version of this state in * case some properties haven't changed since last time (since the front can * reconstruct those). If you want the full state, use the getState method. + * * @return {Object} */ getCurrentState() { @@ -454,6 +466,7 @@ class AnimationPlayerActor extends Actor { /** * Get data about the animated properties of this animation player. + * * @return {Array} Returns a list of animated properties. * Each property contains a list of values, their offsets and distances. */ @@ -552,6 +565,7 @@ class AnimationPlayerActor extends Actor { /** * Get the animation types for a given list of CSS property names. + * * @param {Array} propertyNames - CSS property names (e.g. background-color) * @return {Object} Returns animation types (e.g. {"background-color": "rgb(0, 0, 0)"}. */ @@ -565,6 +579,7 @@ class AnimationPlayerActor extends Actor { /** * Returns the distance of between value1, value2. + * * @param {Object} target - dom element * @param {String} propertyName - e.g. transform * @param {String} value1 - e.g. translate(0px) @@ -626,6 +641,7 @@ exports.AnimationsActor = class AnimationsActor extends Actor { * NodeActor IDs when the corresponding NodeActors do exist. * This, in turns, is helpful for clients to avoid having to go back once more * to the server to get a NodeActor for a particular animation. + * * @param {WalkerActor} walker */ setWalkerActor(walker) { @@ -639,6 +655,7 @@ exports.AnimationsActor = class AnimationsActor extends Actor { * retrieved AnimationPlayerActors. Indeed, the lifecycle of these actors * is managed here on the server and tied to getAnimationPlayersForNode * being called. + * * @param {NodeActor} nodeActor The NodeActor as defined in * /devtools/server/actors/inspector */ @@ -803,6 +820,7 @@ exports.AnimationsActor = class AnimationsActor extends Actor { /** * Set the current time of several animations at the same time. + * * @param {Array} players A list of AnimationPlayerActor. * @param {Number} time The new currentTime. * @param {Boolean} shouldPause Should the players be paused too. @@ -827,6 +845,7 @@ exports.AnimationsActor = class AnimationsActor extends Actor { /** * Set the playback rate of several animations at the same time. + * * @param {Array} actors A list of AnimationPlayerActor. * @param {Number} rate The new rate. */ diff --git a/devtools/server/actors/blackboxing.js b/devtools/server/actors/blackboxing.js @@ -24,7 +24,6 @@ const { BLACKBOXING } = SUPPORTED_DATA; * all DevTools targets. * * @constructor - * */ class BlackboxingActor extends Actor { constructor(watcherActor) { diff --git a/devtools/server/actors/breakpoint-list.js b/devtools/server/actors/breakpoint-list.js @@ -24,7 +24,6 @@ const { BREAKPOINTS, XHR_BREAKPOINTS, EVENT_BREAKPOINTS } = SUPPORTED_DATA; * all DevTools targets. * * @constructor - * */ class BreakpointListActor extends Actor { constructor(watcherActor) { diff --git a/devtools/server/actors/compatibility/compatibility.js b/devtools/server/actors/compatibility/compatibility.js @@ -94,6 +94,7 @@ class CompatibilityActor extends Actor { /** * Responsible for computing the compatibility issues in the * CSS declaration of the given node. + * * @param NodeActor node * @param targetBrowsers Array * An Array of JSON object of target browser to check compatibility against in following form: diff --git a/devtools/server/actors/highlighters/auto-refresh.js b/devtools/server/actors/highlighters/auto-refresh.js @@ -114,6 +114,7 @@ class AutoRefreshHighlighter extends EventEmitter { /** * Show the highlighter on a given node + * * @param {DOMNode} node * @param {Object} options * Object used for passing options @@ -169,6 +170,7 @@ class AutoRefreshHighlighter extends EventEmitter { * Whether the current node is valid for this highlighter type. * This is implemented by default to check if the node is an element node. Highlighter * sub-classes should override this method if they want to highlight other node types. + * * @param {DOMNode} node * @return {Boolean} */ @@ -228,6 +230,7 @@ class AutoRefreshHighlighter extends EventEmitter { /** * Update the knowledge we have of the current node's boxquads and return true * if any of the points x/y or bounds have change since. + * * @return {Boolean} */ _hasMoved() { @@ -240,6 +243,7 @@ class AutoRefreshHighlighter extends EventEmitter { /** * Update the knowledge we have of the current window's scrolling offset, both * horizontal and vertical, and return `true` if they have changed since. + * * @return {Boolean} */ _hasWindowScrolled() { @@ -259,6 +263,7 @@ class AutoRefreshHighlighter extends EventEmitter { /** * Update the knowledge we have of the current window's dimensions and return `true` * if they have changed since. + * * @return {Boolean} */ _haveWindowDimensionsChanged() { diff --git a/devtools/server/actors/highlighters/box-model.js b/devtools/server/actors/highlighters/box-model.js @@ -318,6 +318,7 @@ class BoxModelHighlighter extends AutoRefreshHighlighter { /** * Override the AutoRefreshHighlighter's _isNodeValid method to also return true for * text nodes since these can also be highlighted. + * * @param {DOMNode} node * @return {Boolean} */ @@ -464,6 +465,7 @@ class BoxModelHighlighter extends AutoRefreshHighlighter { * This is useful to position the guides and infobar. * This may happen if the BoxModelHighlighter is used to highlight an inline * element that spans line breaks. + * * @param {String} region The box-model region to get the outer quad for. * @return {Object} A quad-like object {p1,p2,p3,p4,bounds} */ @@ -662,6 +664,7 @@ class BoxModelHighlighter extends AutoRefreshHighlighter { /** * Can the current node be highlighted? Does it have quads. + * * @return {Boolean} */ _nodeNeedsHighlighting() { @@ -704,6 +707,7 @@ class BoxModelHighlighter extends AutoRefreshHighlighter { /** * We only want to show guides for horizontal and vertical edges as this helps * to line them up. This method finds these edges and displays a guide there. + * * @param {String} region The region around which the guides should be shown. */ _showGuides(region) { diff --git a/devtools/server/actors/highlighters/eye-dropper.js b/devtools/server/actors/highlighters/eye-dropper.js @@ -538,6 +538,7 @@ class EyeDropper { /** * Copy the currently inspected color to the clipboard. + * * @return {Promise} Resolves when the copy has been done (after a delay that is used to * let users know that something was copied). */ @@ -563,6 +564,7 @@ exports.EyeDropper = EyeDropper; /** * Draw the visible portion of the window on a canvas and get the resulting ImageData. + * * @param {Window} win * @return {ImageData} The image data for the window. */ @@ -588,6 +590,7 @@ function getWindowAsImageData(win) { /** * Get a formatted CSS color string from a color value. + * * @param {array} rgb Rgb values of a color to format. * @param {string} format Format of string. One of "hex", "rgb", "hsl", "name". * @return {string} Formatted color value, e.g. "#FFF" or "hsl(20, 10%, 10%)". @@ -613,6 +616,7 @@ function toColorString(rgb, format) { /** * Produce a hex-formatted color string from rgb values. + * * @param {array} rgb Rgb values of color to stringify. * @return {string} Hex formatted string for color, e.g. "#FFEE00". */ diff --git a/devtools/server/actors/highlighters/fonts.js b/devtools/server/actors/highlighters/fonts.js @@ -61,6 +61,7 @@ class FontsHighlighter { /** * Show the highlighter for a given node. + * * @param {DOMNode} node The node in which we want to search for text runs. * @param {Object} options A bunch of options that can be set: * - {String} name The actual font name to look for in the node. diff --git a/devtools/server/actors/highlighters/node-tabbing-order.js b/devtools/server/actors/highlighters/node-tabbing-order.js @@ -229,6 +229,7 @@ class NodeTabbingOrderHighlighter extends AutoRefreshHighlighter { /** * Calculate border bounds based on the quads returned by getAdjustedQuads. + * * @return {Object} A bounds object {bottom,height,left,right,top,width,x,y} */ _getBorderBounds() { @@ -290,6 +291,7 @@ class NodeTabbingOrderHighlighter extends AutoRefreshHighlighter { /** * Can the current node be highlighted? Does it have quads. + * * @return {Boolean} */ _nodeNeedsHighlighting() { diff --git a/devtools/server/actors/highlighters/shapes.js b/devtools/server/actors/highlighters/shapes.js @@ -608,6 +608,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Handle a mouse click in transform mode. + * * @param {Number} pageX the x coordinate of the mouse * @param {Number} pageY the y coordinate of the mouse */ @@ -634,6 +635,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Handle a click in transform mode while highlighting a polygon. + * * @param {Number} pageX the x coordinate of the mouse. * @param {Number} pageY the y coordinate of the mouse. * @param {String} type the type of transform handle that was clicked. @@ -666,6 +668,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Handle a click in transform mode while highlighting a circle. + * * @param {Number} pageX the x coordinate of the mouse. * @param {Number} pageY the y coordinate of the mouse. * @param {String} type the type of transform handle that was clicked. @@ -711,6 +714,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Handle a click in transform mode while highlighting an ellipse. + * * @param {Number} pageX the x coordinate of the mouse. * @param {Number} pageY the y coordinate of the mouse. * @param {String} type the type of transform handle that was clicked. @@ -762,6 +766,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Handle a click in transform mode while highlighting an inset. + * * @param {Number} pageX the x coordinate of the mouse. * @param {Number} pageY the y coordinate of the mouse. * @param {String} type the type of transform handle that was clicked. @@ -792,6 +797,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Handle mouse movement after a click on a handle in transform mode. + * * @param {Number} pageX the x coordinate of the mouse * @param {Number} pageY the y coordinate of the mouse */ @@ -810,6 +816,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Translates a shape based on the current mouse position. + * * @param {Number} pageX the x coordinate of the mouse. * @param {Number} pageY the y coordinate of the mouse. */ @@ -832,6 +839,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Scales a shape according to the current mouse position. + * * @param {Number} pageX the x coordinate of the mouse. * @param {Number} pageY the y coordinate of the mouse. */ @@ -928,6 +936,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Rotates a polygon based on the current mouse position. + * * @param {Number} pageX the x coordinate of the mouse. * @param {Number} pageY the y coordinate of the mouse. */ @@ -993,6 +1002,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Transform a circle depending on the current transformation matrix. + * * @param {Number} transX the number of pixels the shape is translated on the x axis * before scaling */ @@ -1023,6 +1033,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Transform an ellipse depending on the current transformation matrix. + * * @param {Number} transX the number of pixels the shape is translated on the x axis * before scaling * @param {Number} transY the number of pixels the shape is translated on the y axis @@ -1103,6 +1114,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Handle a click when highlighting a polygon. + * * @param {Number} pageX the x coordinate of the click * @param {Number} pageY the y coordinate of the click */ @@ -1145,6 +1157,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Update the dragged polygon point with the given x/y coords and update * the element style. + * * @param {Number} pageX the new x coordinate of the point * @param {Number} pageY the new y coordinate of the point */ @@ -1196,6 +1209,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Remove point from polygon defintion and update the element style. + * * @param {Number} point the index of the point to delete */ _deletePolygonPoint(point) { @@ -1215,6 +1229,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { } /** * Handle a click when highlighting a circle. + * * @param {Number} pageX the x coordinate of the click * @param {Number} pageY the y coordinate of the click */ @@ -1269,6 +1284,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Set the center/radius of the circle according to the mouse position and * update the element style. + * * @param {String} point either "center" or "radius" * @param {Number} pageX the x coordinate of the mouse position, in terms of % * relative to the element @@ -1318,6 +1334,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Handle a click when highlighting an ellipse. + * * @param {Number} pageX the x coordinate of the click * @param {Number} pageY the y coordinate of the click */ @@ -1380,6 +1397,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Set center/rx/ry of the ellispe according to the mouse position and update the * element style. + * * @param {String} point "center", "rx", or "ry" * @param {Number} pageX the x coordinate of the mouse position, in terms of % * relative to the element @@ -1441,6 +1459,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Handle a click when highlighting an inset. + * * @param {Number} pageX the x coordinate of the click * @param {Number} pageY the y coordinate of the click */ @@ -1470,6 +1489,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Set the top/left/right/bottom of the inset shape according to the mouse position * and update the element style. + * * @param {String} point "top", "left", "right", or "bottom" * @param {Number} pageX the x coordinate of the mouse position, in terms of % * relative to the element @@ -1550,6 +1570,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Change the appearance of the given marker when the mouse hovers over it. + * * @param {String|Number} point if the shape is a polygon, the integer index of the * point being hovered. Otherwise, a string identifying the point being hovered. * Integers < 0 and falsey values excluding 0 indicate no point is being hovered. @@ -1693,6 +1714,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Convert the given coordinates on the page to percentages relative to the current * element. + * * @param {Number} pageX the x coordinate on the page * @param {Number} pageY the y coordinate on the page * @returns {Object} object of form {percentX, percentY}, which are the x/y coords @@ -1712,6 +1734,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Convert the given x/y coordinates, in percentages relative to the current element, * to pixel coordinates relative to the page + * * @param {Number} x the x coordinate * @param {Number} y the y coordinate * @returns {Object} object of form {x, y}, which are the x/y coords in pixels @@ -1731,6 +1754,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Get which transformation should be applied based on the mouse position. + * * @param {Number} pageX the x coordinate of the mouse. * @param {Number} pageY the y coordinate of the mouse. * @returns {String} a string describing the transformation that should be applied @@ -1790,6 +1814,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Get the id of the point on the polygon highlighter at the given coordinate. + * * @param {Number} pageX the x coordinate on the page, in % relative to the element * @param {Number} pageY the y coordinate on the page, in % relative to the element * @returns {Number} the index of the point that was clicked on in this.coordinates, @@ -1820,6 +1845,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Check if the mouse clicked on a line of the polygon, and if so, add a point near * the click. + * * @param {Number} pageX the x coordinate on the page, in % relative to the element * @param {Number} pageY the y coordinate on the page, in % relative to the element */ @@ -1853,6 +1879,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Check if the center point or radius of the circle highlighter is at given coords + * * @param {Number} pageX the x coordinate on the page, in % relative to the element * @param {Number} pageY the y coordinate on the page, in % relative to the element * @returns {String} "center" if the center point was clicked, "radius" if the radius @@ -1892,6 +1919,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Check if the center or rx/ry points of the ellipse highlighter is at given point + * * @param {Number} pageX the x coordinate on the page, in % relative to the element * @param {Number} pageY the y coordinate on the page, in % relative to the element * @returns {String} "center" if the center point was clicked, "rx" if the x-radius @@ -1922,6 +1950,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Check if the edges of the inset highlighter is at given coords + * * @param {Number} pageX the x coordinate on the page, in % relative to the element * @param {Number} pageY the y coordinate on the page, in % relative to the element * @returns {String} "top", "left", "right", or "bottom" if any of those edges were @@ -1999,6 +2028,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Parses the CSS definition given and returns the shape type associated * with the definition and the coordinates necessary to draw the shape. + * * @param {String} definition the input CSS definition * @returns {Object} null if the definition is not of a known shape type, * or an object of the type { shapeType, coordinates }, where @@ -2069,6 +2099,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Parses the definition of the CSS polygon() function and returns its points, * converted to percentages. + * * @param {String} definition the arguments of the polygon() function * @returns {Array} an array of the points of the polygon, with all values * evaluated and converted to percentages @@ -2113,6 +2144,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Parse the raw (non-computed) definition of the CSS polygon. + * * @returns {Array} an array of the points of the polygon, with units preserved. */ polygonRawPoints() { @@ -2140,6 +2172,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Parses the definition of the CSS circle() function and returns the x/y radiuses and * center coordinates, converted to percentages. + * * @param {String} definition the arguments of the circle() function * @returns {Object} an object of the form { rx, ry, cx, cy }, where rx and ry are the * radiuses for the x and y axes, and cx and cy are the x/y coordinates for the @@ -2206,6 +2239,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Parse the raw (non-computed) definition of the CSS circle. + * * @returns {Object} an object of the points of the circle (cx, cy, radius), * with units preserved. */ @@ -2231,6 +2265,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Parses the computed style definition of the CSS ellipse() function and returns the * x/y radii and center coordinates, converted to percentages. + * * @param {String} definition the arguments of the ellipse() function * @returns {Object} an object of the form { rx, ry, cx, cy }, where rx and ry are the * radiuses for the x and y axes, and cx and cy are the x/y coordinates for the @@ -2279,6 +2314,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Parse the raw (non-computed) definition of the CSS ellipse. + * * @returns {Object} an object of the points of the ellipse (cx, cy, rx, ry), * with units preserved. */ @@ -2309,6 +2345,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { * Parses the definition of the CSS inset() function and returns the x/y offsets and * width/height of the shape, converted to percentages. Border radiuses (given after * "round" in the definition) are currently ignored. + * * @param {String} definition the arguments of the inset() function * @returns {Object} an object of the form { x, y, width, height }, which are the top/ * left positions and width/height of the shape. @@ -2360,6 +2397,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Parse the raw (non-computed) definition of the CSS inset. + * * @returns {Object} an object of the points of the inset (top, right, bottom, left), * with units preserved. */ @@ -2406,6 +2444,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { * This uses the index to decide whether to use width or height for the * computation. See `convertCoordsToPercentFromCurrentDimension()` if you * need to specify width or height. + * * @param {Number} coord a single coordinate * @param {Number} i the index of its position in the function * @returns {Number} the coordinate as a percentage value @@ -2421,6 +2460,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Converts a value to percent based on the specified dimension. + * * @param {Number} coord a single coordinate * @param {Number} currentDimensionProperty the dimension ("width" or * "height") to base the calculation off of @@ -2451,6 +2491,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Get the element in the highlighter markup with the given id + * * @param {String} id * @returns {Object} the element with the given id */ @@ -2460,6 +2501,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Return whether all the elements used to draw shapes are hidden. + * * @returns {Boolean} */ areShapesHidden() { @@ -2565,6 +2607,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Update the highlighter for the current node. Called whenever the element's quads * or CSS shape has changed. + * * @returns {Boolean} whether the highlighter was successfully updated */ _update() { @@ -2624,6 +2667,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Update the SVGs to render the current CSS shape and add markers depending on shape * type and transform mode. + * * @param {Number} width the width of the element quads * @param {Number} height the height of the element quads * @param {Number} zoom the zoom level of the window @@ -2681,6 +2725,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Update the SVGs for transform mode to fit the new shape. + * * @param {Number} width the width of the element quads * @param {Number} height the height of the element quads * @param {Number} zoom the zoom level of the window @@ -2791,6 +2836,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Draw markers for the given coordinates. + * * @param {Array} coords an array of coordinate arrays, of form [[x, y] ...] * @param {Number} width the width of the element markers are being drawn for * @param {Number} height the height of the element markers are being drawn for @@ -2815,6 +2861,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Calculate the bounding box of the shape after it is transformed according to * the transformation matrix. + * * @returns {Object} of form { nw, ne, sw, se, n, s, w, e, rotatePoint, center }. * Each element in the object is an array of form [x,y], denoting the x/y * coordinates of the given point. @@ -2889,6 +2936,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { * If the handle is roughly vertical relative to the anchor, return "ns" * If the handle is roughly above/right or below/left, return "nesw" * If the handle is roughly above/left or below/right, return "nwse" + * * @param {String} pointName the name of the point being hovered * @param {String} anchor the name of the anchor point * @returns {String} The rough direction of the point relative to the anchor @@ -2964,6 +3012,7 @@ class ShapesHighlighter extends AutoRefreshHighlighter { /** * Get the "raw" (i.e. non-computed) shape definition on the given node. + * * @param {Node} node the node to analyze * @param {String} property the CSS property for which a value should be retrieved. * @returns {String} the value of the given CSS property on the given node. @@ -2995,6 +3044,7 @@ function getDefinedShapeProperties(node, property) { /** * Split coordinate pairs separated by a space and return an array. + * * @param {String} coords the coordinate pair, where each coord is separated by a space. * @returns {Array} a 2 element array containing the coordinates. */ @@ -3014,6 +3064,7 @@ exports.splitCoords = splitCoords; /** * Convert a coordinate to a percentage value. + * * @param {String} coord a single coordinate * @param {Number} size the size of the element (width or height) that the percentages * are relative to @@ -3037,6 +3088,7 @@ exports.coordToPercent = coordToPercent; /** * Evaluates a CSS calc() expression (only handles addition) + * * @param {String} expression the arguments to the calc() function * @param {Number} size the size of the element (width or height) that percentage values * are relative to @@ -3056,6 +3108,7 @@ exports.evalCalcExpression = evalCalcExpression; /** * Converts a shape mode to the proper CSS property name. + * * @param {String} mode the mode of the CSS shape * @returns the equivalent CSS property name */ @@ -3067,6 +3120,7 @@ exports.shapeModeToCssPropertyName = shapeModeToCssPropertyName; /** * Get the SVG path definition for a circle with given attributes. + * * @param {Number} size the radius of the circle in pixels * @param {Number} cx the x coordinate of the centre of the circle * @param {Number} cy the y coordinate of the centre of the circle @@ -3096,6 +3150,7 @@ exports.getCirclePath = getCirclePath; /** * Calculates the object bounding box for a node given its stroke bounding box. + * * @param {Number} top the y coord of the top edge of the stroke bounding box * @param {Number} left the x coord of the left edge of the stroke bounding box * @param {Number} width the width of the stroke bounding box @@ -3139,6 +3194,7 @@ const getObjectBoundingBox = (top, left, width, height, node) => { /** * Get the unit (e.g. px, %, em) for the given point value. + * * @param {any} point a point value for which a unit should be retrieved. * @returns {String} the unit. */ @@ -3154,6 +3210,7 @@ exports.getUnit = getUnit; /** * Check if the given point value has a unit. + * * @param {any} point a point value. * @returns {Boolean} whether the given value has a unit. */ @@ -3172,6 +3229,7 @@ const isUnitless = point => { /** * Return the anchor corresponding to the given scale type. + * * @param {String} type a scale type, of form "scale-[direction]" * @returns {String} a string describing the anchor, one of the 8 cardinal directions. */ diff --git a/devtools/server/actors/highlighters/tabbing-order.js b/devtools/server/actors/highlighters/tabbing-order.js @@ -203,6 +203,7 @@ class TabbingOrderHighlighter { /** * Update NodeTabbingOrderHighlighter focus styling for a node that, * potentially, belongs to the tabbing order. + * * @param {Object} options * Options specifying the node and its focused state. */ diff --git a/devtools/server/actors/highlighters/utils/accessibility.js b/devtools/server/actors/highlighters/utils/accessibility.js @@ -430,6 +430,7 @@ class ContrastRatio extends AuditReport { /** * Update contrast ratio score infobar markup. + * * @param {Object} * Audit report for a given highlighted accessible. * @return {Boolean} @@ -545,6 +546,7 @@ class Keyboard extends AuditReport { /** * Update keyboard audit infobar markup. + * * @param {Object} * Audit report for a given highlighted accessible. * @return {Boolean} @@ -623,6 +625,7 @@ class TextLabel extends AuditReport { /** * Update text label audit infobar markup. + * * @param {Object} * Audit report for a given highlighted accessible. * @return {Boolean} diff --git a/devtools/server/actors/highlighters/utils/markup.js b/devtools/server/actors/highlighters/utils/markup.js @@ -48,6 +48,7 @@ const STYLESHEET_URI = /** * Is this content window a XUL window? + * * @param {Window} window * @return {Boolean} */ @@ -59,6 +60,7 @@ exports.isXUL = isXUL; /** * Returns true if a DOM node is "valid", where "valid" means that the node isn't a dead * object wrapper, is still attached to a document, and is of a given type. + * * @param {DOMNode} node * @param {Number} nodeType Optional, defaults to ELEMENT_NODE * @return {Boolean} @@ -367,6 +369,7 @@ class CanvasFrameAnonymousContentHelper { /** * Remove an event listener from one of the elements inserted in the * canvasFrame native anonymous container. + * * @param {String} id * @param {String} type */ @@ -514,6 +517,7 @@ class CanvasFrameAnonymousContentHelper { /** * Helper function that creates SVG DOM nodes. + * * @param {Object} Options for the node include: * - nodeType: the type of node, defaults to "box". * - attributes: a {name:value} object to be used as attributes for the node. @@ -532,6 +536,7 @@ class CanvasFrameAnonymousContentHelper { /** * Helper function that creates DOM nodes. + * * @param {Object} Options for the node include: * - nodeType: the type of node, defaults to "div". * - namespace: the namespace to use to create the node, defaults to XHTML namespace. @@ -567,6 +572,7 @@ exports.CanvasFrameAnonymousContentHelper = CanvasFrameAnonymousContentHelper; /** * Wait for document readyness. + * * @param {Object} iframeOrWindow * IFrame or Window for which the content should be loaded. */ diff --git a/devtools/server/actors/inspector/css-logic.js b/devtools/server/actors/inspector/css-logic.js @@ -138,6 +138,7 @@ class CssLogic { /** * Get the values of all the computed CSS properties for the highlighted * element. + * * @returns {object} The computed CSS properties for a selected element */ get computedStyle() { @@ -146,6 +147,7 @@ class CssLogic { /** * Get the source filter. + * * @returns {string} The source filter being used. */ get sourceFilter() { @@ -156,6 +158,7 @@ class CssLogic { * Source filter. Only display properties coming from the given source (web * address). Note that in order to avoid information overload we DO NOT show * unmatched system rules. + * * @see FILTER.* */ set sourceFilter(value) { @@ -214,6 +217,7 @@ class CssLogic { /** * Cache all the stylesheets in the inspected document + * * @private */ _cacheSheets() { @@ -861,6 +865,7 @@ class CssSheet { /** * Check if the stylesheet is disabled or not. + * * @return {boolean} true if this stylesheet is disabled, or false otherwise. */ get disabled() { @@ -1343,6 +1348,7 @@ class CssPropertyInfo { * Uses CssLogic.processMatchedSelectors() to find the matched selectors, * passing in a reference to CssPropertyInfo._processMatchedSelector() to * create CssSelectorInfo objects, which we then sort + * * @private */ _findMatchedSelectors() { @@ -1399,6 +1405,7 @@ class CssPropertyInfo { /** * Refilter the matched selectors array when the CssLogic.sourceFilter * changes. This allows for quick filter changes. + * * @private */ _refilterSelectors() { diff --git a/devtools/server/actors/inspector/inspector.js b/devtools/server/actors/inspector/inspector.js @@ -253,6 +253,7 @@ class InspectorActor extends Actor { /** * Resolve a URL to its absolute form, in the scope of a given content window. + * * @param {String} url. * @param {NodeActor} node If provided, the owner window of this node will be * used to resolve the URL. Otherwise, the top-level content window will be @@ -301,6 +302,7 @@ class InspectorActor extends Actor { * Pick a color from the page using the eye-dropper. This method doesn't return anything * but will cause events to be sent to the front when a color is picked or when the user * cancels the picker. + * * @param {Object} options */ async pickColorFromPage(options) { diff --git a/devtools/server/actors/inspector/utils.js b/devtools/server/actors/inspector/utils.js @@ -189,6 +189,7 @@ function allAnonymousContentTreeWalkerFilter(node) { /** * Is the given node a text node composed of whitespace only? + * * @param {DOMNode} node * @return {Boolean} */ @@ -198,6 +199,7 @@ function isWhitespaceTextNode(node) { /** * Does the given node have non-0 width and height? + * * @param {DOMNode} node * @return {Boolean} */ diff --git a/devtools/server/actors/inspector/walker.js b/devtools/server/actors/inspector/walker.js @@ -193,6 +193,7 @@ exports.setValueSummaryLength = function (val) { class WalkerActor extends Actor { /** * Create the WalkerActor + * * @param {DevToolsServerConnection} conn * The server connection. * @param {TargetActor} targetActor @@ -314,6 +315,7 @@ class WalkerActor extends Actor { /** * Callback for eventListenerService.addListenerChangeListener + * * @param nsISimpleEnumerator changesEnum * enumerator of nsIEventListenerChange */ @@ -468,6 +470,7 @@ class WalkerActor extends Actor { /** * Determine if the walker has come across this DOM node before. + * * @param {DOMNode} rawNode * @return {Boolean} */ @@ -478,6 +481,7 @@ class WalkerActor extends Actor { /** * If the walker has come across this DOM node before, then get the * corresponding node actor. + * * @param {DOMNode} rawNode * @return {NodeActor} */ @@ -682,6 +686,7 @@ class WalkerActor extends Actor { /** * Return the document node that contains the given node, * or the root node if no node is specified. + * * @param NodeActor node * The node whose document is needed, or null to * return the root. @@ -694,6 +699,7 @@ class WalkerActor extends Actor { /** * Return the documentElement for the document containing the * given node. + * * @param NodeActor node * The node whose documentElement is requested, or null * to use the root document. @@ -905,6 +911,7 @@ class WalkerActor extends Actor { /** * Returns the raw children of the DOM node, with anonymous content filtered as needed + * * @param Node rawNode. * @param boolean includeAssigned * Whether <slot> assigned children should be returned. See @@ -1103,6 +1110,7 @@ class WalkerActor extends Actor { /** * Get a list of nodes that match the given selector in all known frames of * the current content page. + * * @param {String} selector. * @return {Array} */ @@ -1123,6 +1131,7 @@ class WalkerActor extends Actor { /** * Get a list of nodes that match the given XPath in all known frames of * the current content page. + * * @param {String} xPath. * @return {Array} */ @@ -1154,6 +1163,7 @@ class WalkerActor extends Actor { /** * Return a NodeListActor with all nodes that match the given XPath in all * frames of the current content page. + * * @param {String} xPath */ multiFrameXPath(xPath) { @@ -1484,6 +1494,7 @@ class WalkerActor extends Actor { /** * Clear all the pseudo-classes on a given node or all nodes. + * * @param {NodeActor} node Optional node to clear pseudo-classes on */ clearPseudoClassLocks(node) { @@ -2528,6 +2539,7 @@ class WalkerActor extends Actor { /** * Check if a node is attached to the DOM tree of the current page. + * * @param {Node} rawNode * @return {Boolean} false if the node is removed from the tree or within a * document fragment diff --git a/devtools/server/actors/network-monitor/network-content.js b/devtools/server/actors/network-monitor/network-content.js @@ -38,7 +38,6 @@ const { * in the content process. * * @constructor - * */ class NetworkContentActor extends Actor { constructor(conn, targetActor) { @@ -139,6 +138,7 @@ class NetworkContentActor extends Actor { /** * Gets the stacktrace for the specified network resource. + * * @param {Number} resourceId * The id for the network resource * @return {Object} diff --git a/devtools/server/actors/network-monitor/network-parent.js b/devtools/server/actors/network-monitor/network-parent.js @@ -19,7 +19,6 @@ const { * in the parent process. * * @constructor - * */ class NetworkParentActor extends Actor { constructor(watcherActor) { @@ -127,6 +126,7 @@ class NetworkParentActor extends Actor { /** * Blocks the requests based on the filters + * * @param {Object} filters */ blockRequest(filters) { @@ -138,6 +138,7 @@ class NetworkParentActor extends Actor { /** * Unblocks requests based on the filters + * * @param {Object} filters */ unblockRequest(filters) { diff --git a/devtools/server/actors/object.js b/devtools/server/actors/object.js @@ -520,6 +520,7 @@ class ObjectActor extends Actor { /** * Evaluate the getter function |desc.get|. + * * @param {Object} getter */ _evaluateGetter(getter) { diff --git a/devtools/server/actors/object/utils.js b/devtools/server/actors/object/utils.js @@ -100,6 +100,7 @@ function unwrapDebuggeeValue(value) { /** * Create a grip for the given debuggee value. If the value is an object or a long string, * it will create an actor and add it to the pool + * * @param {ThreadActor} threadActor * The related Thread Actor. * @param {any} value diff --git a/devtools/server/actors/page-style.js b/devtools/server/actors/page-style.js @@ -578,6 +578,7 @@ class PageStyleActor extends Actor { /** * Get the set of styles that apply to a given node. + * * @param NodeActor node * @param object options * `filter`: A string filter that affects the "matched" handling. @@ -650,6 +651,7 @@ class PageStyleActor extends Actor { /** * Helper function for getApplied, gets all the rules from a given * element. See getApplied for documentation on parameters. + * * @param NodeActor node * @param bool inherited * @param object options @@ -890,6 +892,7 @@ class PageStyleActor extends Actor { /** * Helper function for _getAllElementRules, returns the rules from a given * element. See getApplied for documentation on parameters. + * * @param DOMNode node * @param string pseudo * @param DOMNode inherited @@ -999,6 +1002,7 @@ class PageStyleActor extends Actor { /** * Helper function for getApplied that fetches a set of style properties that * apply to the given node and associated rules + * * @param NodeActor node * @param object options * `filter`: A string filter that affects the "matched" handling. @@ -1091,6 +1095,7 @@ class PageStyleActor extends Actor { * This method returns an object with properties giving information about * the node's margin, border, padding and content region sizes, as well * as information about the type of box, its position, z-index, etc... + * * @param {NodeActor} node * @param {Object} options The only available option is autoMargins. * If set to true, the element's margins will receive an extra check to see @@ -1202,6 +1207,7 @@ class PageStyleActor extends Actor { /** * Helper function for adding a new rule and getting its applied style * properties + * * @param NodeActor node * @param CSSStyleRule rule * @returns Array containing its applied style properties @@ -1215,6 +1221,7 @@ class PageStyleActor extends Actor { /** * Adds a new rule, and returns the new StyleRuleActor. + * * @param {NodeActor} node * @param {String} pseudoClasses The list of pseudo classes to append to the * new selector. diff --git a/devtools/server/actors/pause-scoped.js b/devtools/server/actors/pause-scoped.js @@ -9,6 +9,7 @@ const { ObjectActor } = require("resource://devtools/server/actors/object.js"); class PauseScopedObjectActor extends ObjectActor { /** * Creates a pause-scoped actor for the specified object. + * * @see ObjectActor */ constructor(threadActor, obj, hooks) { diff --git a/devtools/server/actors/perf.js b/devtools/server/actors/perf.js @@ -32,6 +32,7 @@ exports.PerfActor = class PerfActor extends Actor { /** * This counter is incremented at each new capture. This makes sure that the * profile data and the additionalInformation are in sync. + * * @type {number} */ #captureHandleCounter = 0; @@ -39,6 +40,7 @@ exports.PerfActor = class PerfActor extends Actor { /** * This stores the profile data retrieved from the last call to * startCaptureAndStopProfiler. + * * @type {Promise<ArrayBuffer> |null} */ #previouslyRetrievedProfileDataPromise = null; @@ -47,6 +49,7 @@ exports.PerfActor = class PerfActor extends Actor { * This stores the additionalInformation returned by * getProfileDataAsGzippedArrayBufferThenStop so that it can be sent to the * front using getPreviouslyRetrievedAdditionalInformation. + * * @type {Promise<MockedExports.ProfileGenerationAdditionalInformation>| null} */ #previouslyRetrievedAdditionalInformationPromise = null; @@ -173,6 +176,7 @@ exports.PerfActor = class PerfActor extends Actor { /** * This actor function returns the profile data using the bulk protocol. + * * @param {number} handle returned by startCaptureAndStopProfiler * @returns {Promise<void>} */ @@ -269,6 +273,7 @@ exports.PerfActor = class PerfActor extends Actor { /** * Lists the supported features of the profiler for the current browser. + * * @returns {string[]} */ getSupportedFeatures() { diff --git a/devtools/server/actors/reflow.js b/devtools/server/actors/reflow.js @@ -85,6 +85,7 @@ exports.ReflowActor = class ReflowActor extends Actor { /** * Base class for all sorts of observers that need to listen to events on the * targetActor's windows. + * * @param {WindowGlobalTargetActor} targetActor * @param {Function} callback Executed everytime the observer observes something */ @@ -341,6 +342,7 @@ class LayoutChangesObserver extends EventEmitter { * Executed whenever a reflow is observed. Only stacks the reflow in the * reflows array. * The EVENT_BATCHING_DELAY loop will take care of it later. + * * @param {Number} start When the reflow started * @param {Number} end When the reflow ended * @param {Boolean} isInterruptible @@ -377,6 +379,7 @@ exports.LayoutChangesObserver = LayoutChangesObserver; /** * Get a LayoutChangesObserver instance for a given window. This function makes * sure there is only one instance per window. + * * @param {WindowGlobalTargetActor} targetActor * @return {LayoutChangesObserver} */ @@ -404,6 +407,7 @@ exports.getLayoutChangesObserver = getLayoutChangesObserver; * Release a LayoutChangesObserver instance that was retrieved by * getLayoutChangesObserver. This is required to ensure the targetActor reference * is removed and the observer is eventually stopped and destroyed. + * * @param {WindowGlobalTargetActor} targetActor */ function releaseLayoutChangesObserver(targetActor) { @@ -422,6 +426,7 @@ exports.releaseLayoutChangesObserver = releaseLayoutChangesObserver; /** * Reports any reflow that occurs in the targetActor's docshells. + * * @extends Observable * @param {WindowGlobalTargetActor} targetActor * @param {Function} callback Executed everytime a reflow occurs @@ -464,6 +469,7 @@ ReflowObserver.prototype.QueryInterface = ChromeUtils.generateQI([ /** * Reports window resize events on the targetActor's windows. + * * @extends Observable * @param {WindowGlobalTargetActor} targetActor * @param {Function} callback Executed everytime a resize occurs diff --git a/devtools/server/actors/resources/network-events.js b/devtools/server/actors/resources/network-events.js @@ -125,7 +125,6 @@ class NetworkEventWatcher { * Gets the throttle settings * * @return {*} data - * */ getThrottleData() { return this.listener.getThrottleData(); @@ -135,7 +134,6 @@ class NetworkEventWatcher { * Sets the throttle data * * @param {*} data - * */ setThrottleData(data) { this.listener.setThrottleData(data); @@ -143,6 +141,7 @@ class NetworkEventWatcher { /** * Instruct to save or ignore request and response bodies + * * @param {Boolean} save */ setSaveRequestAndResponseBodies(save) { @@ -151,6 +150,7 @@ class NetworkEventWatcher { /** * Block requests based on the filters + * * @param {Object} filters */ blockRequest(filters) { @@ -159,6 +159,7 @@ class NetworkEventWatcher { /** * Unblock requests based on the fitlers + * * @param {Object} filters */ unblockRequest(filters) { diff --git a/devtools/server/actors/resources/storage/extension-storage.js b/devtools/server/actors/resources/storage/extension-storage.js @@ -130,6 +130,7 @@ class ExtensionStorageActor extends BaseStorageActor { /** * This method asynchronously reads the storage data for the target extension * and caches this data into this.hostVsStores. + * * @param {String} host - the hostname for the extension */ async populateStoresForHost(host) { @@ -244,6 +245,7 @@ class ExtensionStorageActor extends BaseStorageActor { * devtools/shared/specs/storage.js. Behavior largely mirrors the "indexedDB" storage actor, * except where it would throw an unhandled error (i.e. for a `BigInt` or `undefined` * `item.value`). + * * @param {Object} item - The storage item to convert * @param {String} item.name - The storage item key * @param {*} item.value - The storage item value diff --git a/devtools/server/actors/source.js b/devtools/server/actors/source.js @@ -524,6 +524,7 @@ class SourceActor extends Actor { /** * Handler for the "onSource" packet. + * * @return Object * The return of this function contains a field `contentType`, and * a field `source`. `source` can either be an ArrayBuffer or diff --git a/devtools/server/actors/style-rule.js b/devtools/server/actors/style-rule.js @@ -1463,6 +1463,7 @@ exports.StyleRuleActor = StyleRuleActor; /** * Compute the start and end offsets of a rule's selector text, given * the CSS text and the line and column at which the rule begins. + * * @param {String} initialText * @param {Number} line (1-indexed) * @param {Number} column (1-indexed) diff --git a/devtools/server/actors/target-configuration.js b/devtools/server/actors/target-configuration.js @@ -81,7 +81,6 @@ const SUPPORTED_OPTIONS = { * in the content process. * * @constructor - * */ class TargetConfigurationActor extends Actor { constructor(watcherActor) { diff --git a/devtools/server/actors/targets/base-target-actor.js b/devtools/server/actors/targets/base-target-actor.js @@ -30,6 +30,7 @@ class BaseTargetActor extends Actor { /** * Type of target, a string of Targets.TYPES. + * * @return {string} */ this.targetType = targetType; diff --git a/devtools/server/actors/targets/parent-process.js b/devtools/server/actors/targets/parent-process.js @@ -126,6 +126,7 @@ class ParentProcessTargetActor extends WindowGlobalTargetActor { /** * Getter for the list of all docshells in this targetActor + * * @return {Array} */ get docShells() { diff --git a/devtools/server/actors/targets/window-global.js b/devtools/server/actors/targets/window-global.js @@ -479,6 +479,7 @@ class WindowGlobalTargetActor extends BaseTargetActor { /** * Getter for the list of all `docShell`s in the window global. + * * @return {Array} */ get docShells() { @@ -535,6 +536,7 @@ class WindowGlobalTargetActor extends BaseTargetActor { /** * Getter for the list of all content DOM windows in the window global. + * * @return {Array} */ get windows() { diff --git a/devtools/server/actors/thread-configuration.js b/devtools/server/actors/thread-configuration.js @@ -55,7 +55,6 @@ const SUPPORTED_OPTIONS = { * and stored as THREAD_CONFIGURATION data entries. * * @constructor - * */ class ThreadConfigurationActor extends Actor { constructor(watcherActor) { diff --git a/devtools/server/actors/thread.js b/devtools/server/actors/thread.js @@ -1784,6 +1784,7 @@ class ThreadActor extends Actor { /** * Create and return an environment actor that corresponds to the provided * Debugger.Environment. + * * @param Debugger.Environment environment * The lexical environment we want to extract. * @param object pool diff --git a/devtools/server/actors/utils/actor-registry.js b/devtools/server/actors/utils/actor-registry.js @@ -17,6 +17,7 @@ const ActorRegistry = { /** * Register a CommonJS module with the devtools server. + * * @param id string * The ID of a CommonJS module. * The actor is going to be registered immediately, but loaded only diff --git a/devtools/server/actors/utils/capture-screenshot.js b/devtools/server/actors/utils/capture-screenshot.js @@ -23,6 +23,7 @@ const MAX_IMAGE_HEIGHT = 10000; /** * This function is called to simulate camera effects + * * @param {BrowsingContext} browsingContext: The browsing context associated with the * browser element we want to animate. */ diff --git a/devtools/server/actors/utils/shapes-utils.js b/devtools/server/actors/utils/shapes-utils.js @@ -6,6 +6,7 @@ /** * Get the distance between two points on a plane. + * * @param {Number} x1 the x coord of the first point * @param {Number} y1 the y coord of the first point * @param {Number} x2 the x coord of the second point @@ -19,6 +20,7 @@ const getDistance = (x1, y1, x2, y2) => { /** * Determine if the given x/y coords are along the edge of the given ellipse. * We allow for a small area around the edge that still counts as being on the edge. + * * @param {Number} x the x coordinate of the click * @param {Number} y the y coordinate of the click * @param {Number} cx the x coordinate of the center of the ellipse @@ -57,6 +59,7 @@ const clickedOnEllipseEdge = ( /** * Get the distance between a point and a line defined by two other points. + * * @param {Number} x1 the x coordinate of the first point in the line * @param {Number} y1 the y coordinate of the first point in the line * @param {Number} x2 the x coordinate of the second point in the line @@ -75,6 +78,7 @@ const distanceToLine = (x1, y1, x2, y2, x3, y3) => { /** * Get the point on the line defined by points a,b that is closest to point c + * * @param {Number} ax the x coordinate of point a * @param {Number} ay the y coordinate of point a * @param {Number} bx the x coordinate of point b @@ -93,6 +97,7 @@ const projection = (ax, ay, bx, by, cx, cy) => { /** * Get the dot product of two vectors, represented by arrays of numbers. + * * @param {Array} a the first vector * @param {Array} b the second vector * @returns {Number} the dot product of a and b @@ -105,6 +110,7 @@ const dotProduct = (a, b) => { /** * Determine if the given x/y coords are above the given point. + * * @param {Number} x the x coordinate of the click * @param {Number} y the y coordinate of the click * @param {Number} pointX the x coordinate of the center of the point diff --git a/devtools/server/actors/utils/style-utils.js b/devtools/server/actors/utils/style-utils.js @@ -178,6 +178,7 @@ exports.getRuleText = getRuleText; /** * Return the offset and substring of |text| that starts at the given * line and column. + * * @param {String} text * @param {Number} line (1-indexed) * @param {Number} column (1-indexed) diff --git a/devtools/server/actors/utils/stylesheets-manager.js b/devtools/server/actors/utils/stylesheets-manager.js @@ -59,6 +59,7 @@ const modifiedStyleSheets = new WeakMap(); /** * Manage stylesheets related to a given Target Actor. + * * @emits stylesheet-updated: emitted when there was changes in a stylesheet * First arg is an object with the following properties: * - resourceId {String}: The id that was assigned to the stylesheet @@ -124,6 +125,7 @@ class StyleSheetsManager extends EventEmitter { * Calling this function will make the StyleSheetsManager start the event listeners needed * to watch for stylesheet additions and modifications. * This resolves once it notified about existing stylesheets. + * * @param {Object} options * @param {Function} onAvailable: Function that will be called when a stylesheet is * registered, but also with already registered stylesheets diff --git a/devtools/server/actors/utils/walker-search.js b/devtools/server/actors/utils/walker-search.js @@ -304,6 +304,7 @@ class WalkerSearch { /** * Search the document + * * @param {String} query What to search for * @param {Object} options The following options are accepted: * - searchMethod {String} one of WalkerSearch.SEARCH_METHOD_* diff --git a/devtools/server/actors/watcher.js b/devtools/server/actors/watcher.js @@ -339,6 +339,7 @@ exports.WatcherActor = class WatcherActor extends Actor { /** * Flush any early iframe targets relating to this top level * window target. + * * @param {number} topInnerWindowID */ _flushIframeTargets(topInnerWindowID) { diff --git a/devtools/server/actors/webbrowser.js b/devtools/server/actors/webbrowser.js @@ -233,6 +233,7 @@ BrowserTabList.prototype.destroy = function () { /** * Get the selected browser for the given navigator:browser window. + * * @private * @param window nsIChromeWindow * The navigator:browser window for which you want the selected browser. diff --git a/devtools/server/actors/webconsole.js b/devtools/server/actors/webconsole.js @@ -169,6 +169,7 @@ class WebConsoleActor extends Actor { /** * This is used by the ObjectActor to keep track of the depth of grip() calls. + * * @private * @type number */ @@ -294,6 +295,7 @@ class WebConsoleActor extends Actor { /** * The ConsoleServiceListener instance. + * * @type object */ consoleServiceListener = null; diff --git a/devtools/server/actors/webconsole/commands/parser.js b/devtools/server/actors/webconsole/commands/parser.js @@ -84,7 +84,6 @@ function createToken(string) { /** * returns a command Tree object for a set of tokens * - * * @param Array Tokens tokens * An array of Token objects * diff --git a/devtools/server/actors/webconsole/listeners/console-api.js b/devtools/server/actors/webconsole/listeners/console-api.js @@ -50,6 +50,7 @@ class ConsoleAPIListener { /** * The content window for which we listen to window.console API calls. + * * @type nsIDOMWindow */ window = null; diff --git a/devtools/server/actors/webconsole/listeners/console-file-activity.js b/devtools/server/actors/webconsole/listeners/console-file-activity.js @@ -23,6 +23,7 @@ exports.ConsoleFileActivityListener = ConsoleFileActivityListener; ConsoleFileActivityListener.prototype = { /** * Tells if the console progress listener is initialized or not. + * * @private * @type boolean */ @@ -37,6 +38,7 @@ ConsoleFileActivityListener.prototype = { /** * Initialize the ConsoleFileActivityListener. + * * @private */ _init() { @@ -80,6 +82,7 @@ ConsoleFileActivityListener.prototype = { * Check if there is any file load, given the arguments of * nsIWebProgressListener.onStateChange. If the state change tells that a file * URI has been loaded, then the remote Web Console instance is notified. + * * @private */ _checkFileActivity(progress, request, state) { diff --git a/devtools/server/actors/webconsole/listeners/console-service.js b/devtools/server/actors/webconsole/listeners/console-service.js @@ -40,12 +40,14 @@ class ConsoleServiceListener { /** * The content window for which we listen to page errors. + * * @type nsIDOMWindow */ window = null; /** * The function which is notified of messages from the console service. + * * @type function */ handler = null; diff --git a/devtools/server/actors/worker/service-worker-registration.js b/devtools/server/actors/worker/service-worker-registration.js @@ -37,6 +37,7 @@ XPCOMUtils.defineLazyServiceGetter( class ServiceWorkerRegistrationActor extends Actor { /** * Create the ServiceWorkerRegistrationActor + * * @param DevToolsServerConnection conn * The server connection. * @param ServiceWorkerRegistrationInfo registration diff --git a/devtools/server/devtools-server-connection.js b/devtools/server/devtools-server-connection.js @@ -90,6 +90,7 @@ DevToolsServerConnection.prototype = { /** * Used when sending a bulk reply from an actor. + * * @see DebuggerTransport.prototype.startBulkSend */ startBulkSend(header) { diff --git a/devtools/server/socket/websocket-server.js b/devtools/server/socket/websocket-server.js @@ -93,6 +93,7 @@ function writeString(output, data) { /** * Read HTTP request from async input stream. + * * @return Request line (string) and Map of header names and values. */ const readHttpRequest = async function (input) { diff --git a/devtools/server/tests/browser/head.js b/devtools/server/tests/browser/head.js @@ -114,6 +114,7 @@ async function initInspectorFront(url) { /** * Wait until a DevToolsClient is connected. + * * @param {DevToolsClient} client * @return {Promise} Resolves when connected. */ @@ -123,6 +124,7 @@ function waitUntilClientConnected(client) { /** * Wait for eventName on target. + * * @param {Object} target An observable object that either supports on/off or * addEventListener/removeEventListener * @param {String} eventName @@ -251,6 +253,7 @@ function getCookieId(name, domain, path, partitionKey = "") { /** * Trigger DOM activity and wait for the corresponding accessibility event. + * * @param {Object} emitter Devtools event emitter, usually a front. * @param {Sting} name Accessibility event in question. * @param {Function} handler Accessibility event handler function with checks. @@ -265,6 +268,7 @@ async function emitA11yEvent(emitter, name, handler, task) { /** * Check that accessibilty front is correct and its attributes are also * up-to-date. + * * @param {Object} front Accessibility front to be tested. * @param {Object} expected A map of a11y front properties to be verified. * @param {Object} expectedFront Expected accessibility front. diff --git a/devtools/server/tests/xpcshell/head_dbg.js b/devtools/server/tests/xpcshell/head_dbg.js @@ -407,6 +407,7 @@ async function getTestTab(client, title) { } /** * Attach to the client's tab whose title is specified + * * @param {Object} client * @param {Object} title * @returns commands @@ -427,6 +428,7 @@ async function attachTestTab(client, title) { /** * Attach to the client's tab whose title is specified, and then attach to * that tab's thread. + * * @param {Object} client * @param {Object} title * @returns {Object} diff --git a/devtools/shared/accessibility.js b/devtools/shared/accessibility.js @@ -38,6 +38,7 @@ const LARGE_TEXT = { /** * Get contrast ratio score based on WCAG criteria. + * * @param {Number} ratio * Value of the contrast ratio for a given accessible object. * @param {Boolean} isLargeText @@ -60,6 +61,7 @@ function getContrastRatioScore(ratio, isLargeText) { /** * Get calculated text style properties from a node's computed style, if possible. + * * @param {Object} computedStyle * Computed style using which text styling information is to be calculated. * - fontSize {String} diff --git a/devtools/shared/async-utils.js b/devtools/shared/async-utils.js @@ -14,6 +14,7 @@ /** * Adds an event listener to the given element, and then removes its event * listener once the event is called, returning the event object as a promise. + * * @param Element element * The DOM element to listen on * @param String event diff --git a/devtools/shared/commands/inspector/inspector-command.js b/devtools/shared/commands/inspector/inspector-command.js @@ -414,6 +414,7 @@ class InspectorCommand { /** * Get compatibility issues for all queued domRules declarations + * * @returns {Promise<Array<Array<Object>>>} */ #batchedGetCSSDeclarationBlockIssues = async () => { diff --git a/devtools/shared/commands/resource/resource-command.js b/devtools/shared/commands/resource/resource-command.js @@ -600,6 +600,7 @@ class ResourceCommand { /** * Method called by the TargetCommand when a target has just been destroyed + * * @param {Object} arg * @param {Front} arg.targetFront * The Front of the target that was destroyed diff --git a/devtools/shared/css/color.js b/devtools/shared/css/color.js @@ -618,6 +618,7 @@ function hexToRGBA(name, highResolution) { /** * Blend background and foreground colors takign alpha into account. + * * @param {Array} foregroundColor * An array with [r,g,b,a] values containing the foreground color. * @param {Array} backgroundColor diff --git a/devtools/shared/discovery/discovery.js b/devtools/shared/discovery/discovery.js @@ -53,6 +53,7 @@ function log(msg) { /** * Each Transport instance owns a single UDPSocket. + * * @param port integer * The port to listen on for incoming UDP multicast packets. */ @@ -74,6 +75,7 @@ function Transport(port) { Transport.prototype = { /** * Send a object to some UDP port. + * * @param object object * Object which is the message to send * @param port integer @@ -189,6 +191,7 @@ function Discovery() { Discovery.prototype = { /** * Add a new service offered by this device. + * * @param service string * Name of the service * @param info object @@ -204,6 +207,7 @@ Discovery.prototype = { /** * Remove a service offered by this device. + * * @param service string * Name of the service */ diff --git a/devtools/shared/event-emitter.js b/devtools/shared/event-emitter.js @@ -76,6 +76,7 @@ class EventEmitter { * Removes an event `listener` for the given event `type` on this instance * If no `listener` is passed removes all listeners of the given * `type`. If `type` is not passed removes all the listeners of this instance. + * * @param {String} [type] * The type of event. * @param {Function} [listener] diff --git a/devtools/shared/heapsnapshot/HeapAnalysesClient.js b/devtools/shared/heapsnapshot/HeapAnalysesClient.js @@ -152,7 +152,6 @@ HeapAnalysesClient.prototype.takeCensus = function ( * with their shortest paths attached, and without any dominator tree * child/parent information attached. The results are sorted by * retained size. - * */ HeapAnalysesClient.prototype.getCensusIndividuals = function (opts) { return this._worker.performTask("getCensusIndividuals", opts); diff --git a/devtools/shared/inspector/css-logic.js b/devtools/shared/inspector/css-logic.js @@ -13,6 +13,7 @@ const MAX_DATA_URL_LENGTH = 40; * that helps them understand: * - why their expectations may not have been fulfilled * - how browsers process CSS + * * @constructor */ @@ -49,6 +50,7 @@ exports.FILTER = { * * These statuses are localized inside the styleinspector.properties * string bundle. + * * @see csshtmltree.js RuleView._cacheStatusNames() */ exports.STATUS = { @@ -602,6 +604,7 @@ exports.hasVisitedState = hasVisitedState; /** * Find the position of [element] in [nodeList]. + * * @returns an index of the match, or -1 if there is no match */ function positionInNodeList(element, nodeList) { @@ -643,6 +646,7 @@ function findNodeAndContainer(node) { /** * Find a unique CSS selector for a given element + * * @returns a string such that: * - ele.containingDocOrShadow.querySelector(reply) === ele * - ele.containingDocOrShadow.querySelectorAll(reply).length === 1 diff --git a/devtools/shared/layout/utils.js b/devtools/shared/layout/utils.js @@ -340,6 +340,7 @@ exports.getNodeBounds = getNodeBounds; * elements that act like frames (e.g. <embed>), where 'contentWindow' isn't a * property that can be accessed. * This uses the inIDeepTreeWalker instead. + * * @param {DOMNode} frame * @return {Window} */ @@ -537,6 +538,7 @@ exports.isAfterPseudoElement = isAfterPseudoElement; /** * Get the current zoom factor applied to the container window of a given node. + * * @param {DOMNode|DOMWindow} * The node for which the zoom factor should be calculated, or its * owner window. @@ -622,6 +624,7 @@ exports.getViewportDimensions = getViewportDimensions; * - a DOM node * - the document node * - the window itself + * * @param {DOMNode|DOMWindow|DOMDocument} node The node to get the window for. * @return {DOMWindow} */ diff --git a/devtools/shared/loader/Loader.sys.mjs b/devtools/shared/loader/Loader.sys.mjs @@ -25,6 +25,7 @@ var gNextLoaderID = 0; * * The two following boolean flags are used to control the sandboxes into * which the modules are loaded. + * * @param freshCompartment boolean * If true, the modules will be forced to be loaded in a distinct * compartment. It is typically used to load the modules in a distinct diff --git a/devtools/shared/loader/browser-loader-mocks.js b/devtools/shared/loader/browser-loader-mocks.js @@ -37,6 +37,7 @@ function _getUriForModulePath(modulePath) { /** * Assign a mock object to the provided module path. + * * @param mock * Plain JavaScript object that will implement the expected API for the mocked * module. diff --git a/devtools/shared/network-observer/ChannelMap.sys.mjs b/devtools/shared/network-observer/ChannelMap.sys.mjs @@ -46,6 +46,7 @@ export class ChannelMap { /** * WeakMap from nsIChannel instances to objects which encapsulate ChannelMap * values with the following structure: + * * @property {Object} value * The actual value stored in this ChannelMap entry, which should relate * to this channel. diff --git a/devtools/shared/network-observer/NetworkObserver.sys.mjs b/devtools/shared/network-observer/NetworkObserver.sys.mjs @@ -206,6 +206,7 @@ export class NetworkObserver { #throttleData = null; /** * NetworkThrottleManager instance, created when a valid throttleData is set. + * * @type {NetworkThrottleManager} */ #throttler = null; diff --git a/devtools/shared/network-observer/NetworkResponseListener.sys.mjs b/devtools/shared/network-observer/NetworkResponseListener.sys.mjs @@ -463,6 +463,7 @@ export class NetworkResponseListener { /** * Fetches cache information from CacheEntry + * * @private */ async #getCacheInformation() { @@ -654,6 +655,7 @@ export class NetworkResponseListener { /** * Loads the content from the cache + * * @returns Promise */ #getContentFromCache() { diff --git a/devtools/shared/performance-new/prefs-presets.sys.mjs b/devtools/shared/performance-new/prefs-presets.sys.mjs @@ -432,6 +432,7 @@ export function setRecordingSettings(pageContext, prefs) { /** * Revert the recording prefs for both local and remote profiling. + * * @return {void} */ export function revertRecordingSettings() { @@ -449,6 +450,7 @@ export function revertRecordingSettings() { /** * Add an observer for the profiler-related preferences. + * * @param {PrefObserver} observer * @return {void} */ @@ -458,6 +460,7 @@ export function addPrefObserver(observer) { /** * Removes an observer for the profiler-related preferences. + * * @param {PrefObserver} observer * @return {void} */ @@ -468,6 +471,7 @@ export function removePrefObserver(observer) { * Return the proper view mode for the Firefox Profiler front-end timeline by * looking at the proper preset that is selected. * Return value can be undefined when the preset is unknown or custom. + * * @param {PageContext} pageContext * @return {ProfilerViewMode | undefined} */ @@ -544,6 +548,7 @@ export function getRecordingSettings(pageContext, supportedFeatures) { /** * Change the prefs based on a preset. This mechanism is used by the popup to * easily switch between different settings. + * * @param {string} presetName * @param {PageContext} pageContext * @param {string[]} supportedFeatures diff --git a/devtools/shared/protocol/Actor.js b/devtools/shared/protocol/Actor.js @@ -101,6 +101,7 @@ class Actor extends Pool { /** * Override this method in subclasses to serialize the actor. + * * @returns A jsonable object. */ form() { @@ -153,6 +154,7 @@ class Actor extends Pool { /** * Throw an error with the passed message and attach an `error` property to the Error * object so it can be consumed by the writeError function. + * * @param {String} error: A string (usually a single word serving as an id) that will * be assign to error.error. * @param {String} message: The string that will be passed to the Error constructor. diff --git a/devtools/shared/protocol/Pool.js b/devtools/shared/protocol/Pool.js @@ -130,6 +130,7 @@ class Pool extends EventEmitter { /** * Search for an actor in this pool, given an actorID + * * @param {String} actorID * @returns {Actor/null} Returns null if the actor wasn't found */ diff --git a/devtools/shared/protocol/lazy-pool.js b/devtools/shared/protocol/lazy-pool.js @@ -106,7 +106,6 @@ exports.createExtraActors = createExtraActors; * Creates an "actor-like" object which responds in the same way as an ordinary actor * but has fewer capabilities (ie, does not manage lifetimes or have it's own pool). * - * * @param factories * An object whose own property names are the names of properties to add to * some reply packet (say, a target actor grip or the "listTabs" response diff --git a/devtools/shared/qrcode/index.js b/devtools/shared/qrcode/index.js @@ -39,6 +39,7 @@ Object.defineProperty(this, "decoder", { * * It expects you to pick a version large enough to contain your message. Here * we search for the mimimum version based on the message length. + * * @param string message * Text to encode * @param string quality @@ -64,6 +65,7 @@ exports.findMinimumVersion = function (message, quality) { /** * Simple wrapper around the underlying encoder's API. + * * @param string message * Text to encode * @param string quality (optional) @@ -86,6 +88,7 @@ exports.encodeToDataURI = function (message, quality, version) { /** * Simple wrapper around the underlying decoder's API. + * * @param string URI * URI of an image of a QR code * @return Promise @@ -103,6 +106,7 @@ exports.decodeFromURI = function (URI) { /** * Decode a QR code that has been drawn to a canvas element. + * * @param Canvas canvas * <canvas> element to read from * @return string diff --git a/devtools/shared/security/auth.js b/devtools/shared/security/auth.js @@ -87,6 +87,7 @@ Prompt.Client.prototype = { /** * When client is about to make a new connection, verify that the connection settings * are compatible with this authenticator. + * * @throws if validation requirements are not met */ validateSettings() {}, diff --git a/devtools/shared/security/socket.js b/devtools/shared/security/socket.js @@ -224,6 +224,7 @@ var _attemptTransport = async function (settings) { * Typically, this will only fail if the host / port is unreachable. Other * problems, such as security errors, will allow this stage to succeed, but then * fail later when the streams are actually used. + * * @return s nsISocketTransport * Underlying socket transport, in case more details are needed. * @return input nsIAsyncInputStream diff --git a/devtools/shared/transport/packets.js b/devtools/shared/transport/packets.js @@ -55,6 +55,7 @@ function Packet(transport) { * Attempt to initialize a new Packet based on the incoming packet header we've * received so far. We try each of the types in succession, trying JSON packets * first since they are much more common. + * * @param header string * The packet header string to attempt parsing. * @param transport DebuggerTransport @@ -99,6 +100,7 @@ exports.Packet = Packet; * prepended to the packet, followed by a colon ([length]:[packet]). The * contents of the JSON packet are specified in the Remote Debugging Protocol * specification. + * * @param transport DebuggerTransport * The transport instance that will own the packet. */ @@ -111,6 +113,7 @@ function JSONPacket(transport) { /** * Attempt to initialize a new JSONPacket based on the incoming packet header * we've received so far. + * * @param header string * The packet header string to attempt parsing. * @param transport DebuggerTransport @@ -242,6 +245,7 @@ exports.JSONPacket = JSONPacket; * The interpretation of the data portion depends on the kind of actor and the * packet's type. See the Remote Debugging Protocol Stream Transport spec for * more details. + * * @param transport DebuggerTransport * The transport instance that will own the packet. */ @@ -258,6 +262,7 @@ function BulkPacket(transport) { /** * Attempt to initialize a new BulkPacket based on the incoming packet header * we've received so far. + * * @param header string * The packet header string to attempt parsing. * @param transport DebuggerTransport @@ -434,6 +439,7 @@ exports.BulkPacket = BulkPacket; /** * RawPacket is used to test the transport's error handling of malformed * packets, by writing data directly onto the stream. + * * @param transport DebuggerTransport * The transport instance that will own the packet. * @param data string diff --git a/devtools/shared/transport/stream-utils.js b/devtools/shared/transport/stream-utils.js @@ -275,12 +275,14 @@ class AsyncStreamToArrayBufferCopier { /** * This is a wrapper on top of #originalStream, to be able to read buffers * easily. + * * @typedef {nsIBinaryInputStream} */ #binaryStream; /** * This is the output buffer, accessed as an UInt8Array. + * * @typedef {Uint8Array} */ #outputArray; @@ -288,6 +290,7 @@ class AsyncStreamToArrayBufferCopier { /** * How many bytes have been read already. This is also the next index to write * in #outputArray. + * * @typedef {number} */ #pointer = 0; @@ -295,12 +298,14 @@ class AsyncStreamToArrayBufferCopier { /** * The count of bytes to be transfered. It is infered from the byteLength of * of the output buffer. + * * @typedef {number} */ #count; /** * This temporary buffer is used when reading from #binaryStream. + * * @typedef {ArrayBuffer} */ #tempBuffer; @@ -417,12 +422,14 @@ class ArrayBufferToAsyncStreamCopier { /** * This is a wrapper on top of #originalStream, to be able to write buffers * easily. + * * @typedef {nsIBinaryOutputStream} */ #binaryStream; /** * This is the input buffer, accessed as an UInt8Array. + * * @typedef {Uint8Array} */ #inputArray; @@ -430,6 +437,7 @@ class ArrayBufferToAsyncStreamCopier { /** * How many bytes have been read already. This is also the next index to read * in #outputArray. + * * @typedef {number} */ #pointer = 0; @@ -437,6 +445,7 @@ class ArrayBufferToAsyncStreamCopier { /** * The count of bytes to be transfered. It is infered from the byteLength of * of the input buffer. + * * @typedef {number} */ #count; diff --git a/devtools/shared/transport/transport.js b/devtools/shared/transport/transport.js @@ -192,6 +192,7 @@ DebuggerTransport.prototype = { /** * Close the transport. + * * @param reason nsresult / object (optional) * The status code or error message that corresponds to the reason for * closing the transport (likely because a stream closed or failed). @@ -370,6 +371,7 @@ DebuggerTransport.prototype = { * reading may not complete. The Packet signals that its data is ready for * delivery by calling one of this transport's _on*Ready methods (see * ./packets.js and the _on*Ready methods below). + * * @return boolean * Whether incoming stream processing should continue for any * remaining data. @@ -431,6 +433,7 @@ DebuggerTransport.prototype = { * Read as far as we can into the incoming data, attempting to build up a * complete packet header (which terminates with ":"). We'll only read up to * PACKET_HEADER_MAX characters. + * * @return boolean * True if we now have a complete header. */ diff --git a/devtools/shared/webconsole/analyze-input-string.js b/devtools/shared/webconsole/analyze-input-string.js @@ -367,6 +367,7 @@ exports.analyzeInputString = function (str, timeout = 2500) { /** * Checks whether the analyzed input string is in an appropriate state to autocomplete, e.g. not * inside a string, or declaring a variable. + * * @param {object} inputAnalysisState The analyzed string to check * @returns {boolean} Whether the input should be autocompleted */ @@ -402,6 +403,7 @@ exports.shouldInputBeAutocompleted = function (inputAnalysisState) { /** * Checks whether the analyzed input string is in an appropriate state to be eagerly evaluated. + * * @param {object} inputAnalysisState * @returns {boolean} Whether the input should be eagerly evaluated */ diff --git a/devtools/shared/webconsole/test/xpcshell/test_js_property_provider.js b/devtools/shared/webconsole/test/xpcshell/test_js_property_provider.js @@ -724,6 +724,7 @@ function runChecks(dbgObject, environment, sandbox) { /** * A helper that ensures an empty array of results were found. + * * @param Object results * The results returned by jsPropertyProvider. */ @@ -733,6 +734,7 @@ function test_has_no_results(results) { } /** * A helper that ensures (required) results were found. + * * @param Object results * The results returned by jsPropertyProvider. * @param String requiredSuggestion @@ -751,6 +753,7 @@ function test_has_result(results, requiredSuggestion) { /** * A helper that ensures results are the expected ones. + * * @param Object results * The results returned by jsPropertyProvider. * @param Array expectedMatches diff --git a/devtools/shared/worker/worker.sys.mjs b/devtools/shared/worker/worker.sys.mjs @@ -104,6 +104,7 @@ DevToolsWorker.prototype.onError = function ({ message, filename, lineno }) { /** * Takes a function and returns a Worker-wrapped version of the same function. * Returns a promise upon resolution. + * * @see `./devtools/shared/shared/tests/browser/browser_devtools-worker-03.js * * ⚠This should only be used for tests or A/B testing performance ⚠diff --git a/docshell/base/URIFixup.sys.mjs b/docshell/base/URIFixup.sys.mjs @@ -726,6 +726,7 @@ URIFixupInfo.prototype = { /** * Implementation of isDomainKnown, so we don't have to go through the * service. + * * @param {string} asciiHost * @returns {boolean} whether the domain is known */ @@ -764,6 +765,7 @@ function isDomainKnown(asciiHost) { /** * Checks the suffix of info.fixedURI against the Public Suffix List. * If the suffix is unknown due to a typo this will try to fix it up. + * * @param {URIFixupInfo} info about the uri to check. * @note this may modify the public suffix of info.fixedURI. * @returns {object} result The lookup result. @@ -866,6 +868,7 @@ function tryKeywordFixupForURIInfo(uriString, fixupInfo, isPrivateContext) { * This generates an alternate fixedURI, by adding a prefix and a suffix to * the fixedURI host, if and only if the protocol is http. It should _never_ * modify URIs with other protocols. + * * @param {URIFixupInfo} info an URIInfo object * @param {integer} fixupFlags the fixup flags * @returns {boolean} Whether an alternate uri was generated @@ -905,6 +908,7 @@ function maybeSetAlternateFixedURI(info, fixupFlags) { /** * Try to fixup a file URI. + * * @param {string} uriString The file URI to fix. * @returns {nsIURI} a fixed uri or null. * @note FileURIFixup only returns a URI if it has to add the file: protocol. @@ -1002,6 +1006,7 @@ function makeURIWithFixedLocalHosts(uriString, fixupFlags) { /** * Tries to fixup a string to a search url. + * * @param {string} uriString the string to fixup. * @param {URIFixupInfo} fixupInfo The fixup info object, modified in-place. * @param {boolean} isPrivateContext Whether this happens in a private context. @@ -1083,6 +1088,7 @@ function keywordURIFixup(uriString, fixupInfo, isPrivateContext) { /** * Mimics the logic in Services.io.extractScheme, but avoids crossing XPConnect. * This also tries to fixup the scheme if it was clearly mistyped. + * * @param {string} uriString the string to examine * @param {integer} fixupFlags The original fixup flags * @returns {object} @@ -1155,6 +1161,7 @@ function extractScheme(uriString, fixupFlags = FIXUP_FLAG_NONE) { * View-source is a pseudo scheme. We're interested in fixing up the stuff * after it. The easiest way to do that is to call this method again with * the "view-source:" lopped off and then prepend it again afterwards. + * * @param {string} uriString The original string to fixup * @param {integer} fixupFlags The original fixup flags * @param {nsIInputStream} postData Optional POST data for the search @@ -1191,6 +1198,7 @@ function fixupViewSource(uriString, fixupFlags) { /** * Fixup the host of fixedURI if it contains consecutive dots. + * * @param {URIFixupInfo} info an URIInfo object */ function fixupConsecutiveDotsHost(fixupInfo) { @@ -1229,6 +1237,7 @@ function fixupConsecutiveDotsHost(fixupInfo) { * - "localhost:8080" (if given host is "localhost") * - "/foo?bar" * - "/foo#bar" + * * @param {string} uriString. * @param {string} host. * @param {boolean} true if uri like. diff --git a/dom/animation/test/testcommon.js b/dom/animation/test/testcommon.js @@ -122,6 +122,7 @@ function assert_properties_equal(actual, expected) { * KeyframeEffectReadonly::GetProperties(). * The method returns undefined as a value in case of missing keyframe. * Therefor, we can use undefined for |value| and |easing| parameter. + * * @param offset - keyframe offset. e.g. 0.1 * @param value - any keyframe value. e.g. undefined '1px', 'center', 0.5 * @param composite - 'replace', 'add', 'accumulate' diff --git a/dom/canvas/test/test_imagebitmap.html b/dom/canvas/test/test_imagebitmap.html @@ -19,6 +19,7 @@ SimpleTest.waitForExplicitFinish(); /** * [isPixel description] + * * @param {[type]} ctx : canvas context * @param {[type]} x : pixel x coordinate * @param {[type]} y : pixel y coordinate diff --git a/dom/canvas/test/test_imagebitmap_cropping.html b/dom/canvas/test/test_imagebitmap_cropping.html @@ -10,6 +10,7 @@ SimpleTest.waitForExplicitFinish(); /** * [isPixel description] + * * @param {[type]} ctx : canvas context * @param {[type]} x : pixel x coordinate * @param {[type]} y : pixel y coordinate diff --git a/dom/events/test/test_bug336682.js b/dom/events/test/test_bug336682.js @@ -22,6 +22,7 @@ function trace(text) { * Returns a handler function for an online/offline event. The returned handler * ensures the passed event object has expected properties and that the handler * is called at the right moment (according to the gState variable). + * * @param nameTemplate The string identifying the hanlder. '%1' in that * string will be replaced with the event name. * @param eventName 'online' or 'offline' diff --git a/dom/indexedDB/test/file.js b/dom/indexedDB/test/file.js @@ -104,6 +104,7 @@ function verifyBlobProperties(blob1, blob2, fileId) { * * Note: Unlike the generator based verifyBlob routine, verifyBlobAsync uses * bufferCache for both blob1 and blob2 arguments. + * * @param {Blob} blob1 actual Blob value * @param {Blob} blob2 Blob with expected properties * @param {Number} fileId expected id diff --git a/dom/ipc/ManifestMessagesChild.sys.mjs b/dom/ipc/ManifestMessagesChild.sys.mjs @@ -48,6 +48,7 @@ export class ManifestMessagesChild extends JSWindowActorChild { /** * Asynchronously obtains a web manifest from this window by using the * ManifestObtainer and returns the result. + * * @param {Object} checkConformance True if spec conformance messages should be collected. */ async obtainManifest(options) { @@ -89,6 +90,7 @@ export class ManifestMessagesChild extends JSWindowActorChild { * Utility function to Serializes an JS Error, so it can be transferred over * the message channel. * FIX ME: https://bugzilla.mozilla.org/show_bug.cgi?id=1172586 + * * @param {Error} aError The error to serialize. * @return {Object} The serialized object. */ diff --git a/dom/manifest/ManifestFinder.sys.mjs b/dom/manifest/ManifestFinder.sys.mjs @@ -6,6 +6,7 @@ export var ManifestFinder = { /** * Check from content process if DOM Window has a conforming * manifest link relationship. + * * @param aContent DOM Window to check. * @return {Promise<Boolean>} */ @@ -19,6 +20,7 @@ export var ManifestFinder = { /** * Check from a XUL browser (parent process) if it's content document has a * manifest link relationship. + * * @param aBrowser The XUL browser to check. * @return {Promise} */ diff --git a/dom/manifest/ManifestObtainer.sys.mjs b/dom/manifest/ManifestObtainer.sys.mjs @@ -28,6 +28,7 @@ export var ManifestObtainer = { /** * Public interface for obtaining a web manifest from a XUL browser, to use * on the parent process. + * * @param {XULBrowser} The browser to check for the manifest. * @param {Object} aOptions * @param {Boolean} aOptions.checkConformance If spec conformance messages should be collected. @@ -57,6 +58,7 @@ export var ManifestObtainer = { }, /** * Public interface for obtaining a web manifest from a XUL browser. + * * @param {Window} aContent A content Window from which to extract the manifest. * @param {Object} aOptions * @param {Boolean} aOptions.checkConformance If spec conformance messages should be collected. @@ -110,6 +112,7 @@ function isXULBrowser(aBrowser) { /** * Asynchronously processes the result of response after having fetched * a manifest. + * * @param {Response} aResp Response from fetch(). * @param {Window} aContentWindow The content window. * @return {Promise<Object>} The processed manifest. @@ -133,6 +136,7 @@ async function processResponse(aResp, aContentWindow, aOptions) { /** * Asynchronously fetches a web manifest. + * * @param {Window} a The content Window from where to extract the manifest. * @return {Promise<Object>} */ diff --git a/dom/media/autoplay/test/browser/head.js b/dom/media/autoplay/test/browser/head.js @@ -1,5 +1,6 @@ /** * Return a web-based URL for a given file based on the testing directory. + * * @param {String} fileName * file that caller wants its web-based url * @param {Boolean} crossOrigin [optional] @@ -16,6 +17,7 @@ function GetTestWebBasedURL(fileName, { crossOrigin = false } = {}) { /** * Runs a content script that creates an autoplay video. + * * @param {browserElement} browser * the browser to run the script in * @param {object} args @@ -80,6 +82,7 @@ function loadAutoplayVideo(browser, args) { /** * Runs a content script that checks whether the video created by * loadAutoplayVideo() started playing. + * * @param {browserElement} browser * the browser to run the script in * @param {object} args @@ -111,6 +114,7 @@ function checkVideoDidPlay(browser, args) { * Create a tab that will load the given url, and define an autoplay policy * check function inside the content window in that tab. This function should * only be used when `dom.media.autoplay-policy-detection.enabled` is true. + * * @param {url} url * the url which the created tab should load */ diff --git a/dom/media/test/browser/browser_telemetry_video_hardware_decoding_support.js b/dom/media/test/browser/browser_telemetry_video_hardware_decoding_support.js @@ -93,6 +93,7 @@ add_task(async function testAudioCodecs() { /** * Return a web-based URL for a given file based on the testing directory. + * * @param {String} fileName * file that caller wants its web-based url */ diff --git a/dom/media/test/browser/wmfme/head.js b/dom/media/test/browser/wmfme/head.js @@ -2,6 +2,7 @@ /** * Return a web-based URL for a given file based on the testing directory. + * * @param {String} fileName * file that caller wants its web-based url * @param {Boolean} cors [optional] @@ -29,6 +30,7 @@ async function getMFCDMProcessId() { /** * Make the utility process with given process id crash. + * * @param {int} pid * the process id for the process which is going to crash */ @@ -106,6 +108,7 @@ async function crashUtilityProcess(utilityPid) { /** * Make video in the tab play. + * * @param {object} tab * the tab contains at least one video element */ @@ -124,6 +127,7 @@ async function playVideo(tab) { /** * Check whether the video playback is performed in the right process and right decoder. + * * @param {object} tab * the tab which has a playing video * @param {string} expectedProcess @@ -165,6 +169,7 @@ async function assertRunningProcessAndDecoderName( /** * Check whether the video playback is not performed in the given process and given decoder. + * * @param {object} tab * the tab which has a playing video * @param {string} givenProcess diff --git a/dom/media/test/eme_standalone.js b/dom/media/test/eme_standalone.js @@ -40,6 +40,7 @@ var EmeHelper = class EmeHelper { /** * Get the clearkey key system string. + * * @return The clearkey key system string. */ static GetClearkeyKeySystemString() { @@ -51,6 +52,7 @@ var EmeHelper = class EmeHelper { /** * Helper to convert Uint8Array into base64 using base64url alphabet, without * padding. + * * @param uint8Array An array of bytes to convert to base64. * @return A base 64 encoded string */ @@ -65,6 +67,7 @@ var EmeHelper = class EmeHelper { /** * Helper to convert a hex string into base64 using base64url alphabet, * without padding. + * * @param hexString A string of hex characters. * @return A base 64 encoded string */ @@ -83,6 +86,7 @@ var EmeHelper = class EmeHelper { /** * Helper to convert a base64 string (base64 or base64url) into a hex string. + * * @param base64String A base64 encoded string. This can be base64url. * @return A hex string (lower case); */ @@ -110,6 +114,7 @@ var EmeHelper = class EmeHelper { /** * Sets the key system that will be used by the EME helper. + * * @param keySystem The key system to use. Probably "org.w3.clearkey", which * can be fetched via `GetClearkeyKeySystemString`. */ @@ -120,6 +125,7 @@ var EmeHelper = class EmeHelper { /** * Sets the init data types that will be used by the EME helper. This is used * when calling `navigator.requestMediaKeySystemAccess`. + * * @param initDataTypes A list containing the init data types to be set by * the helper. This will usually be ["cenc"] or ["webm"], see * https://www.w3.org/TR/eme-initdata-registry/ for more info on what these @@ -134,6 +140,7 @@ var EmeHelper = class EmeHelper { * used when calling `navigator.requestMediaKeySystemAccess`. * See https://developer.mozilla.org/en-US/docs/Web/API/Navigator/requestMediaKeySystemAccess * for more info on these. + * * @param audioCapabilities A list containing audio capabilities. E.g. * [{ contentType: 'audio/webm; codecs="opus"' }]. */ @@ -146,6 +153,7 @@ var EmeHelper = class EmeHelper { * used when calling `navigator.requestMediaKeySystemAccess`. * See https://developer.mozilla.org/en-US/docs/Web/API/Navigator/requestMediaKeySystemAccess * for more info on these. + * * @param videoCapabilities A list containing video capabilities. E.g. * [{ contentType: 'video/webm; codecs="vp9"' }] */ @@ -174,6 +182,7 @@ var EmeHelper = class EmeHelper { /** * Removes a key id and its associate key from the key map. + * * @param keyId The key id to remove. */ RemoveKeyIdAndKey(keyId) { @@ -186,6 +195,7 @@ var EmeHelper = class EmeHelper { * Internal handler for `session.onmessage`. When calling this either do so * from inside an arrow function or using `bind` to ensure `this` points to * an EmeHelper instance (rather than a session). + * * @param messageEvent The message event passed to `session.onmessage`. */ _SessionMessageHandler(messageEvent) { @@ -232,6 +242,7 @@ var EmeHelper = class EmeHelper { /** * Configures EME on a media element using the parameters already set on the * instance of EmeHelper. + * * @param htmlMediaElement - A media element to configure EME on. * @return A promise that will be resolved once the media element is * configured. This promise will be rejected with an error if configuration diff --git a/dom/media/test/test_background_video_cancel_suspend_visible.html b/dom/media/test/test_background_video_cancel_suspend_visible.html @@ -13,6 +13,7 @@ var manager = new MediaTestManager; /** * Check that making the element visible before suspend timer delay causes the * the suspend timer to be canceled. + * * @param {HTMLMediaElement} video Video element under test. * @returns {Promise} Promise that is resolved when video decode resumes. */ diff --git a/dom/media/webrtc/tests/mochitests/head.js b/dom/media/webrtc/tests/mochitests/head.js @@ -1088,6 +1088,7 @@ CommandChain.prototype = { /** * Returns the index of the specified command in the chain. + * * @param {occurrence} Optional param specifying which occurrence to match, * with 0 representing the first occurrence. */ diff --git a/dom/media/webrtc/tests/mochitests/parser_rtp.js b/dom/media/webrtc/tests/mochitests/parser_rtp.js @@ -6,6 +6,7 @@ /** * Parses an RTP packet + * * @param buffer an ArrayBuffer that contains the packet * @return { type: "rtp", header: {...}, payload: a DataView } */ diff --git a/dom/push/PushService.sys.mjs b/dom/push/PushService.sys.mjs @@ -1240,6 +1240,7 @@ export var PushService = { * Clear subscriptions matching either a principal or a domain and * OriginAttributesPattern. If domain="*" is passed all records will be * deleted. + * * @param {*} options * @param {nsIPrincipal} [options.principal] - The principal to clear * subscriptions for. This does an exact origin match. diff --git a/dom/security/test/cors/browser_CORS-console-warnings.js b/dom/security/test/cors/browser_CORS-console-warnings.js @@ -32,6 +32,7 @@ async function do_cleanup() { /** * Set e10s related preferences in the test environment. + * * @return {Promise} promise that resolves when preferences are set. */ function setCookiePref() { @@ -48,6 +49,7 @@ function setCookiePref() { /** * Unset e10s related preferences in the test environment. + * * @return {Promise} promise that resolves when preferences are unset. */ function unsetCookiePref() { diff --git a/dom/security/test/https-first/browser_mixed_content_download.js b/dom/security/test/https-first/browser_mixed_content_download.js @@ -20,6 +20,7 @@ let SECURE_BASE_URL = * Waits until a download is triggered. * It waits until a prompt is shown, * saves and then accepts the dialog. + * * @returns {Promise} Resolved once done. */ diff --git a/dom/security/test/mixedcontentblocker/browser_mixed_content_auth_download.js b/dom/security/test/mixedcontentblocker/browser_mixed_content_auth_download.js @@ -36,6 +36,7 @@ let SECURE_BASE_URL = * Waits until a download is triggered. * It waits until a prompt is shown, * saves and then accepts the dialog. + * * @returns {Promise} Resolved once done. */ diff --git a/dom/security/test/mixedcontentblocker/browser_test_mixed_content_download.js b/dom/security/test/mixedcontentblocker/browser_test_mixed_content_download.js @@ -61,6 +61,7 @@ const downloadMonitoringView = { * will simply be saved, so resolve when the view is notified of the new * download. Otherwise, it waits until a prompt is shown, selects the choosen * <action>, then accepts the dialog + * * @param [action] Which action to select, either: * "handleInternally", "save" or "open". * @returns {Promise} Resolved once done. diff --git a/dom/smil/test/smilTestUtils.js b/dom/smil/test/smilTestUtils.js @@ -589,6 +589,7 @@ extend(AnimTestcaseFrom, AnimTestcase); /** * A testcase for a simple "from-to" animation + * * @param aFrom The 'from' value * @param aTo The 'to' value * @param aComputedValMap A hash-map that contains some computed values, @@ -603,7 +604,6 @@ extend(AnimTestcaseFrom, AnimTestcase); * @param aSkipReason If this test-case is known to currently fail, this * parameter should be a string explaining why. * Otherwise, this value should be null (or omitted). - * */ function AnimTestcaseFromTo(aFrom, aTo, aComputedValMap, aSkipReason) { this.from = aFrom; @@ -697,6 +697,7 @@ extend(AnimTestcaseFromBy, AnimTestcaseFrom); /** * A testcase for a "paced-mode" animation + * * @param aValues An array of values, to be used as the "Values" list * @param aComputedValMap A hash-map that contains some computed values, * if they're needed, as follows: diff --git a/dom/workers/test/onLine_worker_child.js b/dom/workers/test/onLine_worker_child.js @@ -17,6 +17,7 @@ function ok(test, message) { * Returns a handler function for an online/offline event. The returned handler * ensures the passed event object has expected properties and that the handler * is called at the right moment (according to the gState variable). + * * @param nameTemplate The string identifying the hanlder. '%1' in that * string will be replaced with the event name. * @param eventName 'online' or 'offline' diff --git a/dom/workers/test/onLine_worker_head.js b/dom/workers/test/onLine_worker_head.js @@ -17,6 +17,7 @@ function ok(test, message) { * Returns a handler function for an online/offline event. The returned handler * ensures the passed event object has expected properties and that the handler * is called at the right moment (according to the gState variable). + * * @param nameTemplate The string identifying the hanlder. '%1' in that * string will be replaced with the event name. * @param eventName 'online' or 'offline' diff --git a/gfx/layers/apz/test/mochitest/apz_test_native_event_utils.js b/gfx/layers/apz/test/mochitest/apz_test_native_event_utils.js @@ -880,6 +880,7 @@ async function promiseNativePointerInput( /** * Function to generate native pointer events as a sequence. + * * @param aTarget is the element or window whose bounding rect the coordinates are * relative to. * @param aPointerType "touch" or "pen". diff --git a/intl/locale/LangPackMatcher.sys.mjs b/intl/locale/LangPackMatcher.sys.mjs @@ -47,6 +47,7 @@ async function negotiateLangPackForLanguageMismatch() { /** * Figure out a langpack to recommend. + * * @type {LangPack | null} */ const langPack = @@ -163,6 +164,7 @@ const mockable = { /** * Use the AddonManager to install an addon from the URL. + * * @param {LangPack} langPack */ async installLangPack(langPack) { diff --git a/mobile/shared/modules/geckoview/GeckoViewTab.sys.mjs b/mobile/shared/modules/geckoview/GeckoViewTab.sys.mjs @@ -159,7 +159,6 @@ export const GeckoViewTabBridge = { /** * Request the GeckoView App to close a tab (GeckoSession). * - * * @param {object} options * @param {Window} options.window The window owning the tab to close * @param {string} options.extensionId diff --git a/mobile/shared/modules/geckoview/GeckoViewUtils.sys.mjs b/mobile/shared/modules/geckoview/GeckoViewUtils.sys.mjs @@ -461,6 +461,7 @@ export var GeckoViewUtils = { /** * Checks whether we support managing permissions for a specific scheme. + * * @param {string} scheme - Scheme to test. * @returns {boolean} Whether the scheme is supported. */ diff --git a/netwerk/cookie/test/browser/browser_3pcb_expection.js b/netwerk/cookie/test/browser/browser_3pcb_expection.js @@ -27,6 +27,7 @@ let db; /** * Dispatch a RemoteSettings "sync" event. + * * @param {Object} data - The event's data payload. * @param {Object} [data.created] - Records that were created. * @param {Object} [data.updated] - Records that were updated. @@ -44,6 +45,7 @@ async function remoteSettingsSync({ created, updated, deleted }) { /** * Compare two string arrays ignoring order. + * * @param {string[]} arr1 - The first array. * @param {string[]} arr2 - The second array. * @returns {boolean} - Whether the arrays match. @@ -54,6 +56,7 @@ const strArrayMatches = (arr1, arr2) => /** * Wait until the 3pcb allow-list matches the expected state. + * * @param {string[]} allowedSiteHosts - (Unordered) host list to match. */ async function waitForAllowListState(expected) { @@ -70,6 +73,7 @@ async function waitForAllowListState(expected) { /** * A helper function to create the iframe and the nested ABA iframe. + * * @param {Browser} browser The browser where the testing is performed. * @param {string} firstPartyURL The first party URL. * @param {string} thirdPartyURL The third party URL. diff --git a/netwerk/protocol/http/HPKEConfigManager.sys.mjs b/netwerk/protocol/http/HPKEConfigManager.sys.mjs @@ -7,6 +7,7 @@ let knownConfigs = new Map(); export class HPKEConfigManager { /** * Decodes a base64url-encoded key string. + * * @param {string} aBase64Key * @returns {Uint8Array} */ diff --git a/netwerk/url-classifier/UrlClassifierExceptionListService.sys.mjs b/netwerk/url-classifier/UrlClassifierExceptionListService.sys.mjs @@ -61,6 +61,7 @@ class Feature { /** * Convert a JS object from RemoteSettings to an nsIUrlClassifierExceptionListEntry. + * * @param {Object} rsObject - The JS object from RemoteSettings to convert. * @returns {nsIUrlClassifierExceptionListEntry} The converted nsIUrlClassifierExceptionListEntry. */ diff --git a/services/common/kinto-storage-adapter.sys.mjs b/services/common/kinto-storage-adapter.sys.mjs @@ -32,6 +32,7 @@ function reduceRecords(filters, order, list) { * Checks if a value is undefined. * * This is a copy of `_isUndefined` from kinto.js/src/utils.js. + * * @param {Any} value * @return {Boolean} */ diff --git a/services/crypto/modules/jwcrypto.sys.mjs b/services/crypto/modules/jwcrypto.sys.mjs @@ -164,6 +164,7 @@ class JWCrypto { * JWA RFC. * The raw ECDH secret is derived into a key using * Concat KDF, as defined in Section 5.8.1 of [NIST.800-56A]. + * * @param {CryptoKey} privateKey * @param {CryptoKey} publicKey * @param {String[]} keyUsages See `SubtleCrypto.deriveKey` 5th paramater documentation. diff --git a/services/crypto/modules/utils.sys.mjs b/services/crypto/modules/utils.sys.mjs @@ -36,6 +36,7 @@ export var CryptoUtils = { /** * Generate a string of random bytes. + * * @returns {String} Octet string */ generateRandomBytesLegacy(length) { diff --git a/services/fxaccounts/Credentials.sys.mjs b/services/fxaccounts/Credentials.sys.mjs @@ -54,7 +54,6 @@ export var Credentials = Object.freeze({ * * keyWord derivation for use as a salt. * - * * @param {String} context String for use in generating salt * * @return {bitArray} the salt diff --git a/services/fxaccounts/FxAccounts.sys.mjs b/services/fxaccounts/FxAccounts.sys.mjs @@ -453,6 +453,7 @@ export class FxAccounts { /** * This private method actually fetches the clients from the server. * It should not be called directly by consumers of this API. + * * @returns {Array.<AttachedClient>} * @private */ diff --git a/services/fxaccounts/FxAccountsKeys.sys.mjs b/services/fxaccounts/FxAccountsKeys.sys.mjs @@ -146,7 +146,6 @@ export class FxAccountsKeys { * k: Derived key material * kty: Always "oct" for scoped keys * } - * */ async getKeyForScope(scope) { const { scopedKeys } = await this._loadOrFetchKeys(); @@ -308,6 +307,7 @@ export class FxAccountsKeys { /** * Set externally derived scoped keys in internal storage + * * @param { Object } scopedKeys: The scoped keys object derived by the oauth flow * * @return { Promise }: A promise that resolves if the keys were successfully stored, diff --git a/services/fxaccounts/FxAccountsOAuth.sys.mjs b/services/fxaccounts/FxAccountsOAuth.sys.mjs @@ -47,6 +47,7 @@ export class FxAccountsOAuth { /** * Stores a flow in-memory + * * @param { string } state: A base-64 URL-safe string represnting a random value created at the start of the flow * @param { Object } value: The data needed to complete a flow, once the oauth code is available. * in practice, `value` is: @@ -67,6 +68,7 @@ export class FxAccountsOAuth { /** * Gets a stored flow + * * @param { string } state: The base-64 URL-safe state string that was created at the start of the flow * @returns { Object }: The values initially stored when startign th eoauth flow * in practice, the return value is: @@ -174,6 +176,7 @@ export class FxAccountsOAuth { /** * Completes an OAuth flow and invalidates any other ongoing flows + * * @param { string } sessionTokenHex: The session token encoded in hexadecimal * @param { string } code: OAuth authorization code provided by running an OAuth flow * @param { string } state: The state first provided by `beginOAuthFlow`, then roundtripped through the server diff --git a/services/fxaccounts/FxAccountsProfileClient.sys.mjs b/services/fxaccounts/FxAccountsProfileClient.sys.mjs @@ -221,6 +221,7 @@ FxAccountsProfileClient.prototype = { /** * Normalized profile client errors + * * @param {Object} [details] * Error details object * @param {number} [details.code] diff --git a/services/fxaccounts/FxAccountsWebChannel.sys.mjs b/services/fxaccounts/FxAccountsWebChannel.sys.mjs @@ -454,6 +454,7 @@ FxAccountsWebChannel.prototype = { /** * Create a new channel with the WebChannelBroker, setup a callback listener + * * @private */ _registerChannel() { @@ -474,7 +475,6 @@ FxAccountsWebChannel.prototype = { * @param sendingContext.principal {Principal} * The <Principal> of the EventTarget where the message was sent. * @private - * */ let listener = (webChannelId, message, sendingContext) => { if (message) { @@ -533,6 +533,7 @@ FxAccountsWebChannelHelpers.prototype = { /** * Checks if the user is potentially hitting an issue with the current * account they're logging into. Returns the choice of the user if shown + * * @returns {string} - The corresponding option the user pressed. Can be either: * cancel, continue, switch-profile, or create-profile */ @@ -694,6 +695,7 @@ FxAccountsWebChannelHelpers.prototype = { /** * Logins in to sync by completing an OAuth flow + * * @param { Object } oauthData: The oauth code and state as returned by the server */ async oauthLogin(oauthData) { @@ -1072,9 +1074,9 @@ FxAccountsWebChannelHelpers.prototype = { /** * Similar to _promptForRelink but more offers more contextual warnings * to the user to support browser profiles. + * * @returns {string} - The corresponding option the user pressed. Can be either: * cancel, continue, switch-profile, or create-profile - * */ _promptForProfileSyncWarning(acctEmail, profileLinkedWithAcct) { let currentProfile = this._getCurrentProfileName(); @@ -1155,6 +1157,7 @@ FxAccountsWebChannelHelpers.prototype = { /** * Shows the user a warning prompt. + * * @returns {string} - The corresponding option the user pressed. Can be either: * cancel, continue, switch-profile, or create-profile */ diff --git a/services/fxaccounts/tests/xpcshell/test_profile_client.js b/services/fxaccounts/tests/xpcshell/test_profile_client.js @@ -24,6 +24,7 @@ const STATUS_SUCCESS = 200; /** * Mock request responder + * * @param {String} response * Mocked raw response from the server * @returns {Function} @@ -66,6 +67,7 @@ const PROFILE_OPTIONS = { /** * Mock request error responder + * * @param {Error} error * Error object * @returns {Function} diff --git a/services/settings/RemoteSettings.worker.mjs b/services/settings/RemoteSettings.worker.mjs @@ -59,6 +59,7 @@ const Agent = { * If present, import the JSON file into the Remote Settings IndexedDB * for the specified bucket and collection. * (eg. blocklists/certificates, main/onboarding) + * * @param {String} bucket * @param {String} collection * @returns {int} Number of records loaded from dump or -1 if no dump found. @@ -81,6 +82,7 @@ const Agent = { /** * Check that the specified file matches the expected size and SHA-256 hash. + * * @param {String} fileUrl file URL to read from * @param {Number} size expected file size * @param {String} size expected file SHA-256 as hex string diff --git a/services/settings/RemoteSettingsClient.sys.mjs b/services/settings/RemoteSettingsClient.sys.mjs @@ -978,6 +978,7 @@ export class RemoteSettingsClient extends EventEmitter { /** * Return a more precise error instance, based on the specified * error and its message. + * * @param {Error} e the original error * @returns {Error} */ diff --git a/services/settings/SharedUtils.sys.mjs b/services/settings/SharedUtils.sys.mjs @@ -9,6 +9,7 @@ export var SharedUtils = { /** * Check that the specified content matches the expected size and SHA-256 hash. + * * @param {ArrayBuffer} buffer binary content * @param {Number} size expected file size * @param {String} size expected file SHA-256 as hex string @@ -30,6 +31,7 @@ export var SharedUtils = { /** * Load (from disk) the JSON file distributed with the release for this collection. + * * @param {String} bucket * @param {String} collection */ diff --git a/services/settings/Utils.sys.mjs b/services/settings/Utils.sys.mjs @@ -155,6 +155,7 @@ export var Utils = { /** * Internal method to enable pulling data from preview buckets. + * * @param enabled */ enablePreviewMode(enabled) { diff --git a/services/settings/remote-settings.sys.mjs b/services/settings/remote-settings.sys.mjs @@ -76,6 +76,7 @@ XPCOMUtils.defineLazyPreferenceGetter( /** * cacheProxy returns an object Proxy that will memoize properties of the target. + * * @param {object} target the object to wrap. * @returns {Proxy} */ @@ -104,6 +105,7 @@ class JexlFilter { /** * Default entry filtering function, in charge of excluding remote settings entries * where the JEXL expression evaluates into a falsy value. + * * @param {Object} entry The Remote Settings entry to be excluded or kept. * @returns {?Object} the entry or null if excluded. */ @@ -134,6 +136,7 @@ class JexlFilter { /** * Creates the default entry filter, in charge of excluding remote settings entries * where the JEXL expression evaluates into a falsy value. + * * @param {ClientEnvironment} environment Information about version, language, platform etc. * @param {string} collectionName * Which collection includes this entry. This is used for error reporting. @@ -218,6 +221,7 @@ function remoteSettingsFunction() { /** * Helper to introspect the synchronization history and determine whether it is * consistently failing and thus, broken. + * * @returns {bool} true if broken. */ async function isSynchronizationBroken() { @@ -646,6 +650,7 @@ function remoteSettingsFunction() { /** * Returns an object with polling status information and the list of * known remote settings collections. + * * @param {Object} options * @param {boolean?} options.localOnly (optional) If set to `true`, do not contact the server. */ diff --git a/services/sync/modules/service.sys.mjs b/services/sync/modules/service.sys.mjs @@ -1428,6 +1428,7 @@ Sync11Service.prototype = { /** * Upload a fresh meta/global record + * * @throws the response object if the upload request was not a success */ async _uploadNewMetaGlobal() { @@ -1443,6 +1444,7 @@ Sync11Service.prototype = { /** * Upload meta/global, throwing the response on failure + * * @param {WBORecord} meta meta/global record * @throws the response object if the request was not a success */ @@ -1462,6 +1464,7 @@ Sync11Service.prototype = { /** * Upload crypto/keys + * * @param {WBORecord} cryptoKeys crypto/keys record * @param {Number} lastModified known last modified timestamp (in decimal seconds), * will be used to set the X-If-Unmodified-Since header diff --git a/services/sync/modules/sync_auth.sys.mjs b/services/sync/modules/sync_auth.sys.mjs @@ -470,6 +470,7 @@ SyncAuthManager.prototype = { /** * Exchanges an OAuth access_token for a TokenServer token. + * * @returns {Promise} * @private */ diff --git a/services/sync/tests/unit/head_http_server.js b/services/sync/tests/unit/head_http_server.js @@ -215,7 +215,6 @@ ServerWBO.prototype = { * collection. This should be in the format returned by new_timestamp(). * * @return the new ServerCollection instance. - * */ function ServerCollection(wbos, acceptNew, timestamp) { this._wbos = wbos || {}; @@ -766,7 +765,6 @@ SyncServer.prototype = { * * @param cb * A callback function. Invoked after the server has been stopped. - * */ stop: function stop(cb) { if (!this.started) { diff --git a/services/sync/tps/extensions/tps/resource/tps.sys.mjs b/services/sync/tps/extensions/tps/resource/tps.sys.mjs @@ -1359,7 +1359,6 @@ export var TPS = { * * @param {String} [wipeAction] * Type of wipe to perform (resetClient, wipeClient, wipeRemote) - * */ async Sync(wipeAction) { if (this._syncActive) { diff --git a/storage/test/unit/test_vacuum.js b/storage/test/unit/test_vacuum.js @@ -19,6 +19,7 @@ function synthesize_idle_daily() { /** * Returns a new nsIFile reference for a profile database. + * * @param filename for the database, excluded the .sqlite extension. */ function new_db_file(name = "testVacuum") { diff --git a/testing/mochitest/BrowserTestUtils/BrowserTestUtils.sys.mjs b/testing/mochitest/BrowserTestUtils/BrowserTestUtils.sys.mjs @@ -1954,6 +1954,7 @@ export var BrowserTestUtils = { /** * Create enough tabs to cause a tab overflow in the given window. + * * @param {Function|null} registerCleanupFunction * The test framework doesn't keep its cleanup stuff anywhere accessible, * so the first argument is a reference to your cleanup registration @@ -2256,6 +2257,7 @@ export var BrowserTestUtils = { /** * Returns a promise that is resolved when element gains attribute (or, * optionally, when it is set to value). + * * @param {String} attr * The attribute to wait for * @param {Element} element @@ -2284,6 +2286,7 @@ export var BrowserTestUtils = { /** * Returns a promise that is resolved when element loses an attribute. + * * @param {String} attr * The attribute to wait for * @param {Element} element @@ -2809,6 +2812,7 @@ export var BrowserTestUtils = { /** * Sends a message to a specific BrowserTestUtils window actor. + * * @param {BrowsingContext} aBrowsingContext * The browsing context where the actor lives. * @param {string} aMessageName @@ -2828,6 +2832,7 @@ export var BrowserTestUtils = { /** * Sends a query to a specific BrowserTestUtils window actor. + * * @param {BrowsingContext} aBrowsingContext * The browsing context where the actor lives. * @param {string} aMessageName diff --git a/testing/mochitest/tests/SimpleTest/AccessibilityUtils.js b/testing/mochitest/tests/SimpleTest/AccessibilityUtils.js @@ -151,6 +151,7 @@ this.AccessibilityUtils = (function () { /** * Get related accessible objects that are targets of labelled by relation e.g. * labels. + * * @param {nsIAccessible} accessible * Accessible objects to get labels for. * @@ -802,6 +803,7 @@ this.AccessibilityUtils = (function () { * accessible object. This is used for cases where accessibility best * practices are not followed or for something that is not as severe to be * considered a failure. + * * @param {String} message * @param {nsIAccessible} accessible * Accessible to log along with the todo message. @@ -1055,6 +1057,7 @@ this.AccessibilityUtils = (function () { /** * Walk node ancestry and force refresh driver tick in every document. + * * @param {DOMNode} node * Node for traversing the ancestry. */ diff --git a/testing/mochitest/tests/SimpleTest/EventUtils.js b/testing/mochitest/tests/SimpleTest/EventUtils.js @@ -1762,7 +1762,6 @@ function synthesizeAndWaitNativeMouseMove( * the modifiers only during dispatching the key events. * Note that if some of these values are false, they are ignored (i.e., * not inactivated with this function). - * */ function synthesizeKey(aKey, aEvent = undefined, aWindow = window, aCallback) { const event = aEvent === undefined || aEvent === null ? {} : aEvent; diff --git a/testing/mochitest/tests/SimpleTest/SimpleTest.js b/testing/mochitest/tests/SimpleTest/SimpleTest.js @@ -6,6 +6,7 @@ /** * SimpleTest framework object. + * * @class */ var SimpleTest = {}; @@ -935,7 +936,6 @@ window.setTimeout = function SimpleTest_setTimeoutShim() { * * @param {String} reason * A string representation of the reason why the test needs timeouts. - * */ SimpleTest.requestFlakyTimeout = function (reason) { SimpleTest.is(typeof reason, "string", "A valid string reason is expected"); diff --git a/testing/modules/Assert.sys.mjs b/testing/modules/Assert.sys.mjs @@ -122,7 +122,6 @@ function getMessage(error, prefix = "") { * truncate: truncate, * stack: stack, // Optional, defaults to the current stack. * }); - * */ Assert.AssertionError = function (options) { this.name = "AssertionError"; diff --git a/testing/talos/talos/talos-powers/api.js b/testing/talos/talos/talos-powers/api.js @@ -192,7 +192,6 @@ TalosPowersService.prototype = { * Adds an instant marker to the Profile in the parent process. * * @param marker (string) A marker to set. - * */ addInstantMarker(marker) { ChromeUtils.addProfilerMarker("Talos", { category: "Test" }, marker); diff --git a/testing/xpcshell/head.js b/testing/xpcshell/head.js @@ -335,6 +335,7 @@ var _fakeIdleService = { /** * Restores the idle service factory if needed and returns the service's handle. + * * @return A handle to the idle service. */ function do_get_idle() { @@ -1613,6 +1614,7 @@ function do_send_remote_message(name, data) { /** * Schedules and awaits a precise GC, and forces CC, `maxCount` number of times. + * * @param maxCount * How many times GC and CC should be scheduled. */ diff --git a/toolkit/actors/AutoCompleteParent.sys.mjs b/toolkit/actors/AutoCompleteParent.sys.mjs @@ -504,6 +504,7 @@ export class AutoCompleteParent extends JSWindowActorParent { * The real controller's handleEnter is called directly in the content process * for other methods of completing a selection (e.g. using the tab or enter * keys) since the field with focus is in that process. + * * @param {boolean} aIsPopupSelection */ handleEnter(aIsPopupSelection) { diff --git a/toolkit/actors/FindBarChild.sys.mjs b/toolkit/actors/FindBarChild.sys.mjs @@ -54,6 +54,7 @@ export class FindBarChild extends JSWindowActorChild { * Check whether this key event will start the findbar in the parent, * in which case we should pass any further key events to the parent to avoid * them being lost. + * * @param aEvent the key event to check. */ eventMatchesFindShortcut(aEvent) { diff --git a/toolkit/actors/PictureInPictureChild.sys.mjs b/toolkit/actors/PictureInPictureChild.sys.mjs @@ -109,6 +109,7 @@ ChromeUtils.defineLazyGetter(lazy, "logConsole", () => { * * The Picture-In-Picture add-on can use this to provide site-specific wrappers for * sites that require special massaging to control. + * * @param {Object} pipChild reference to PictureInPictureChild class calling this function * @param {Element} originatingVideo * The <video> element to wrap. @@ -699,6 +700,7 @@ export class PictureInPictureToggleChild extends JSWindowActorChild { * Changes from the first-time toggle to the icon toggle if the Nimbus variable `displayDuration`'s * end date is reached when hovering over a video. The end date is calculated according to the timestamp * indicating when the PiP toggle was first seen. + * * @param {Number} firstSeenStartSeconds the timestamp in seconds indicating when the PiP toggle was first seen */ changeToIconIfDurationEnd(firstSeenStartSeconds) { @@ -1629,6 +1631,7 @@ export class PictureInPictureChild extends JSWindowActorChild { /** * Creates a link element with a reference to the css stylesheet needed * for text tracks responsive styling. + * * @returns {Element} the link element containing text tracks stylesheet. */ createTextTracksStyleSheet() { @@ -1725,6 +1728,7 @@ export class PictureInPictureChild extends JSWindowActorChild { * If overlap is found, set attribute "overlap-video-controls" to move text tracks * and define a new relative bottom position according to pip window size and the * position of video controls. + * * @param {Object} data args needed to determine if text tracks must be moved */ moveTextTracks(data) { @@ -1773,6 +1777,7 @@ export class PictureInPictureChild extends JSWindowActorChild { /** * Updates the text content for the container that holds and displays text tracks * on the pip window. + * * @param textTrackCues {TextTrackCueList|null} * Collection of TextTrackCue objects containing text displayed, or null if there is no cue to display. */ @@ -2204,6 +2209,7 @@ export class PictureInPictureChild extends JSWindowActorChild { /** * Set the current time of the video based of the position of the scrubber + * * @param {Number} scrubberPosition A number between 0 and 1 representing the position of the scrubber */ setVideoTime(scrubberPosition, wasPlaying) { @@ -2236,6 +2242,7 @@ export class PictureInPictureChild extends JSWindowActorChild { /** * Updates this._currentWebVTTTrack if an active track is found * for the originating video. + * * @param {TextTrackList} textTrackList list of text tracks */ setActiveTextTrack(textTrackList) { @@ -2905,6 +2912,7 @@ class PictureInPictureChildVideoWrapper { /** * Function to display the captions on the PiP window + * * @param {String} text - Raw text to be displayed * @param {String} type - Optional type of text track. If "vtt" or "html", the text * will be parsed and displayed as a WebVTT cue. If not provided, the text will @@ -2945,6 +2953,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the play() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to handle video * behaviour when a video is played. + * * @param {HTMLVideoElement} video * The originating video source element */ @@ -2961,6 +2970,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the pause() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to handle video * behaviour when a video is paused. + * * @param {HTMLVideoElement} video * The originating video source element */ @@ -2977,6 +2987,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the getPaused() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to determine if * a video is paused or not. + * * @param {HTMLVideoElement} video * The originating video source element * @returns {Boolean} Boolean value true if paused, or false if video is still playing @@ -2994,6 +3005,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the getEnded() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to determine if * video playback or streaming has stopped. + * * @param {HTMLVideoElement} video * The originating video source element * @returns {Boolean} Boolean value true if the video has ended, or false if still playing @@ -3011,6 +3023,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the getDuration() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to get the current * duration of a video in seconds. + * * @param {HTMLVideoElement} video * The originating video source element * @returns {Number} Duration of the video in seconds @@ -3028,6 +3041,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the getCurrentTime() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to get the current * time of a video in seconds. + * * @param {HTMLVideoElement} video * The originating video source element * @returns {Number} Current time of the video in seconds @@ -3045,6 +3059,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the setCurrentTime() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to set the current * time of a video. + * * @param {HTMLVideoElement} video * The originating video source element * @param {Number} position @@ -3065,6 +3080,7 @@ class PictureInPictureChildVideoWrapper { /** * Return hours, minutes, and seconds from seconds + * * @param {Number} aSeconds * The time in seconds * @returns {String} Timestamp string @@ -3084,6 +3100,7 @@ class PictureInPictureChildVideoWrapper { /** * Format a timestamp from current time and total duration, * output as a string in the form '0:00 / 0:00' + * * @param {Number} aCurrentTime * The current time in seconds * @param {Number} aDuration @@ -3105,6 +3122,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the getVolume() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to get the volume * value of a video. + * * @param {HTMLVideoElement} video * The originating video source element * @returns {Number} Volume of the video between 0 (muted) and 1 (loudest) @@ -3122,6 +3140,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the setVolume() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to set the volume * value of a video. + * * @param {HTMLVideoElement} video * The originating video source element * @param {Number} volume @@ -3142,6 +3161,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the isMuted() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to get the mute * state a video. + * * @param {HTMLVideoElement} video * The originating video source element * @param {Boolean} shouldMute @@ -3160,6 +3180,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the setMuted() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to mute or unmute * a video. + * * @param {HTMLVideoElement} video * The originating video source element * @param {Boolean} shouldMute @@ -3181,6 +3202,7 @@ class PictureInPictureChildVideoWrapper { * if the method does not exist or if an error is thrown while calling it. This method is meant to listen for any cue changes in a * video's caption container and execute a callback function responsible for updating the pip window's text tracks container whenever * a cue change is triggered {@see updatePiPTextTracks()}. + * * @param {HTMLVideoElement} video * The originating video source element * @param {Function} _callback @@ -3204,6 +3226,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the removeCaptionContainerObserver() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to remove any caption observers that * may have been set in setCaptionContainerObserver(). + * * @param {HTMLVideoElement} video * The originating video source element * @param {Function} _callback @@ -3222,6 +3245,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the shouldHideToggle() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to determine if the pip toggle * for a video should be hidden by the site wrapper. + * * @param {HTMLVideoElement} video * The originating video source element * @returns {Boolean} Boolean value true if the pip toggle should be hidden by the site wrapper, or false if it should not @@ -3239,6 +3263,7 @@ class PictureInPictureChildVideoWrapper { * OVERRIDABLE - calls the isLive() method defined in the site wrapper script. Runs a fallback implementation * if the method does not exist or if an error is thrown while calling it. This method is meant to get if the * video is a live stream. + * * @param {HTMLVideoElement} video * The originating video source element */ diff --git a/toolkit/actors/PopupAndRedirectBlockingChild.sys.mjs b/toolkit/actors/PopupAndRedirectBlockingChild.sys.mjs @@ -38,6 +38,7 @@ export class PopupAndRedirectBlockingChild extends JSWindowActorChild { /** * WeakMap keyed by `document`, holding per-document popup/redirect state. + * * @type {WeakMap<Document, DocState>} */ #mWeakDocStates; diff --git a/toolkit/actors/PopupAndRedirectBlockingParent.sys.mjs b/toolkit/actors/PopupAndRedirectBlockingParent.sys.mjs @@ -13,6 +13,7 @@ export class PopupAndRedirectBlocker { * in that browsing context. This allows tracking blocked popups per * frame/window without leaking memory, since keys are GC'd when * WindowGlobals go away. + * * @type {WeakMap<WindowGlobalParent, number>} */ #mBlockedPopupCounts; @@ -20,6 +21,7 @@ export class PopupAndRedirectBlocker { * WeakMap mapping the browser's top-level WindowGlobal to the * BrowsingContext that attempted a blocked redirect. This allows * identifying the source frame/window of a blocked redirect. + * * @type {WeakMap<WindowGlobalParent, BrowsingContext>} */ #mBlockedRedirects; diff --git a/toolkit/components/antitracking/TrackingDBService.sys.mjs b/toolkit/components/antitracking/TrackingDBService.sys.mjs @@ -280,6 +280,7 @@ TrackingDBService.prototype = { /** * Saves data rows to the DB. + * * @param data * An array of JS objects representing row items to save. */ diff --git a/toolkit/components/antitracking/bouncetrackingprotection/test/browser/browser_bouncetracking_mode_prefs.js b/toolkit/components/antitracking/bouncetrackingprotection/test/browser/browser_bouncetracking_mode_prefs.js @@ -14,6 +14,7 @@ const BTP_MODE_PREF = "privacy.bounceTrackingProtection.mode"; /** * Run a bounce test with a custom bounce tracking protection mode. + * * @param {Number} mode - Mode to set for BTP. Any of * Ci.nsIBounceTrackingProtection.MODE_* * @param {boolean} shouldBeEnabled - Whether BTP should classify + purge in diff --git a/toolkit/components/antitracking/bouncetrackingprotection/test/browser/browser_bouncetracking_remoteExceptions.js b/toolkit/components/antitracking/bouncetrackingprotection/test/browser/browser_bouncetracking_remoteExceptions.js @@ -19,6 +19,7 @@ let db; /** * Compare two string arrays ignoring order. + * * @param {string[]} arr1 * @param {string[]} arr2 * @returns {boolean} - Whether the arrays match. @@ -47,6 +48,7 @@ add_setup(async function () { /** * Run a bounce test. + * * @param {boolean} expectTrackerPurged - Whether the bounce tracker is expected * to be purged. */ @@ -82,6 +84,7 @@ async function runPurgeTest(expectTrackerPurged) { /** * Wait until the BTP allow-list matches the expected state. + * * @param {string[]} allowedSiteHosts - (Unordered) host list to match. */ async function waitForAllowListState(allowedSiteHosts) { @@ -101,6 +104,7 @@ async function waitForAllowListState(allowedSiteHosts) { /** * Dispatch a RemoteSettings "sync" event. + * * @param {Object} data - The event's data payload. * @param {Object} [data.created] - Records that were created. * @param {Object} [data.updated] - Records that were updated. diff --git a/toolkit/components/antitracking/bouncetrackingprotection/test/browser/browser_bouncetracking_userActivation.js b/toolkit/components/antitracking/bouncetrackingprotection/test/browser/browser_bouncetracking_userActivation.js @@ -37,6 +37,7 @@ function getURL(origin) { /** * Inserts an iframe element and resolves once the iframe has loaded. + * * @param {*} browserOrBrowsingContext - Browser or BrowsingContext to insert the iframe into. * @param {string} url - URL to load in the iframe. * @returns {Promise<BrowsingContext>} Promise which resolves to the iframe's @@ -57,6 +58,7 @@ function insertIframeAndWaitForLoad(browserOrBrowsingContext, url) { /** * Runs a test that spawns an iframe, interacts with it, and checks the BTP user * activation state. + * * @param {boolean} useIframeSameSite - Whether the iframe interacted with * should be same or cross-site to the top-level window. */ diff --git a/toolkit/components/antitracking/bouncetrackingprotection/test/browser/browser_bouncetracking_webAuthUserActivation.js b/toolkit/components/antitracking/bouncetrackingprotection/test/browser/browser_bouncetracking_webAuthUserActivation.js @@ -49,6 +49,7 @@ function promiseWebAuthnGetAssertionDiscoverableBC( /** * Test that a webauthn request triggers BTP user activation. + * * @param {Function} triggerFn - Function that runs the webauthn request. * @param {String} userActivationSiteHost - The expected user activation site host in BTP. */ @@ -81,6 +82,7 @@ async function runWebAuthTest(triggerFn, userActivationSiteHost) { /** * Wrapper around runWebAuthTest for the case where the webauthn request is made * in an iframe. + * * @param {string} topLevelSite - The top level site where the iframe is inserted. * @param {string} iframeSite - The site of the iframe. */ diff --git a/toolkit/components/antitracking/bouncetrackingprotection/test/browser/browser_bouncetracking_web_console.js b/toolkit/components/antitracking/bouncetrackingprotection/test/browser/browser_bouncetracking_web_console.js @@ -10,6 +10,7 @@ let btpGracePeriodSec = Services.prefs.getIntPref( /** * Registers a console listener and waits for the bounce tracker classified or * purged warning message to be logged. + * * @returns {Promise} - Promise which resolves once the message has been logged. */ async function waitForBTPConsoleMessage(type, siteHost) { diff --git a/toolkit/components/antitracking/bouncetrackingprotection/test/browser/head.js b/toolkit/components/antitracking/bouncetrackingprotection/test/browser/head.js @@ -31,6 +31,7 @@ const ROOT_DIR = getRootDirectory(gTestPath); /** * Get the base url for the current test directory using the given origin. + * * @param {string} origin - Origin to use in URL. * @returns {string} - Generated URL as a string. */ @@ -40,6 +41,7 @@ function getBaseUrl(origin) { /** * Constructs a url for an intermediate "bounce" hop which represents a tracker. + * * @param {*} options - URL generation options. * @param {('server'|'client')} options.bounceType - Redirect type to use for * the bounce. @@ -160,6 +162,7 @@ function getBounceURL({ /** * Insert an <a href/> element with the given target and perform a synthesized * click on it. + * * @param {MozBrowser} browser - Browser to insert the link in. * @param {URL} targetURL - Destination for navigation. * @param {Object} options - Additional options. @@ -218,6 +221,7 @@ async function navigateLinkClick( /** * Wait for the record-bounces method to run for the given tab / browser. + * * @param {browser} browser - Browser element which represents the tab we want * to observe. * @returns {Promise} Promise which resolves once the record-bounces method has @@ -245,6 +249,7 @@ async function waitForRecordBounces(browser) { * Test helper which loads an initial blank page, then navigates to a url which * performs a bounce. Checks that the bounce hosts are properly identified as * trackers. + * * @param {object} options - Test Options. * @param {('server'|'client')} options.bounceType - Whether to perform a client * or server side redirect. diff --git a/toolkit/components/antitracking/bouncetrackingprotection/test/xpcshell/test_bouncetracking_purge.js b/toolkit/components/antitracking/bouncetrackingprotection/test/xpcshell/test_bouncetracking_purge.js @@ -16,6 +16,7 @@ let bounceTrackingActivationLifetimeSec; /** * Adds brackets to a host if it's an IPv6 address. + * * @param {string} host - Host which may be an IPv6. * @returns {string} bracketed IPv6 or host if host is not an IPv6. */ @@ -28,6 +29,7 @@ function maybeFixupIpv6(host) { /** * Adds cookies and indexedDB test data for the given host. + * * @param {string} host */ async function addStateForHost(host) { @@ -38,6 +40,7 @@ async function addStateForHost(host) { /** * Checks if the given host as cookies or indexedDB data. + * * @param {string} host * @returns {boolean} */ diff --git a/toolkit/components/antitracking/bouncetrackingprotection/test/xpcshell/test_bouncetracking_purge_telemetry.js b/toolkit/components/antitracking/bouncetrackingprotection/test/xpcshell/test_bouncetracking_purge_telemetry.js @@ -15,6 +15,7 @@ let bounceTrackingGracePeriodSec; /** * Wait for purge telemetry to be recorded for a list of site hosts. + * * @param {Array} siteHosts - List of site hosts to be purged. */ function waitForPurgeTelemetry(siteHosts) { diff --git a/toolkit/components/antitracking/bouncetrackingprotection/test/xpcshell/test_bouncetracking_storage_batch_write.js b/toolkit/components/antitracking/bouncetrackingprotection/test/xpcshell/test_bouncetracking_storage_batch_write.js @@ -13,6 +13,7 @@ let databasePath; /** * Count the number of entries in the database. + * * @returns {number} The number of entries in the database. */ async function countDatabaseEntries() { @@ -29,6 +30,7 @@ const MAX_PENDING_UPDATES = Services.prefs.getIntPref( /** * Wait for an observer message. + * * @param {string} topic The topic to wait for. * @returns {Promise<{subject: any, topic: string, data: string}>} A promise that resolves to the subject, topic, and data of the message. */ @@ -55,6 +57,7 @@ async function waitForDBFlush() { /** * Wait for the database flush to be skipped because the buffer isn't full yet. + * * @returns {number} The number of pending updates when the flush was skipped. */ async function waitForDBSkipFlush() { diff --git a/toolkit/components/antitracking/test/browser/browser_allowListPreference.js b/toolkit/components/antitracking/test/browser/browser_allowListPreference.js @@ -8,6 +8,7 @@ const COLLECTION_NAME = "url-classifier-exceptions"; /** * Load a tracker in third-party context. + * * @param {string} trackerUrl - The URL of the tracker to load in an iframe. * @returns {Promise} A promise that resolves when the tracker is loaded or * blocked. The promise resolves to "loaded" if the tracker is loaded, or @@ -95,6 +96,7 @@ add_setup(async function () { /** * Set exceptions via RemoteSettings. + * * @param {Boolean} baseline - If true, set baseline allow list entries. * @param {Boolean} convenience - If true, set convenience allow list entries. * @param {String} category - The content blocking category to set. diff --git a/toolkit/components/antitracking/test/browser/browser_contentBlockingAllowListPrincipal.js b/toolkit/components/antitracking/test/browser/browser_contentBlockingAllowListPrincipal.js @@ -13,6 +13,7 @@ const TEST_SANDBOX_URL = /** * Tests the contentBlockingAllowListPrincipal. + * * @param {Browser} browser - Browser to test. * @param {("content"|"system")} type - Expected principal type. * @param {String} [origin] - Expected origin of principal. Defaults to the @@ -46,6 +47,7 @@ function checkAllowListPrincipal( /** * Runs a given test in a normal window and in a private browsing window. + * * @param {String} initialUrl - URL to load in the initial test tab. * @param {Function} testCallback - Test function to run in both windows. */ @@ -69,6 +71,7 @@ async function runTestInNormalAndPrivateMode(initialUrl, testCallback) { /** * Creates an iframe in the passed browser and waits for it to load. + * * @param {Browser} browser - Browser to create the frame in. * @param {String} src - Frame source url. * @param {String} id - Frame id. diff --git a/toolkit/components/antitracking/test/browser/browser_partitionedClearSiteDataHeader.js b/toolkit/components/antitracking/test/browser/browser_partitionedClearSiteDataHeader.js @@ -33,6 +33,7 @@ const skipLocalStorageTests = Services.prefs.getBoolPref( /** * Creates an iframe in the passed browser and waits for it to load. + * * @param {Browser} browser - Browser to create the frame in. * @param {String} src - Frame source url. * @param {String} id - Frame id. @@ -61,6 +62,7 @@ function createFrame(browser, src, id, sandbox) { /** * Creates a new tab, loads a url and creates an iframe. * Callers need to clean up the tab before the test ends. + * * @param {String} firstPartyUrl - Url to load in tab. * @param {String} thirdPartyUrl - Url to load in frame. * @param {String} frameId - Id of iframe element. @@ -94,6 +96,7 @@ async function createTabWithFrame( * Depending on the clearDataContext variable we then either navigate ORIGIN_A * (as top level) or ORIGIN_B (as third party frame) to the clear-site-data * endpoint. + * * @param {function} cbPreClear - Called after initial setup, once top levels * and frames have been loaded. * @param {function} cbPostClear - Called after data has been cleared via the @@ -183,6 +186,7 @@ async function runClearSiteDataTest( /** * Create an origin with partitionKey. + * * @param {String} originNoSuffix - Origin without origin attributes. * @param {String} [firstParty] - First party to create partitionKey. * @returns {String} Origin with suffix. If not passed this will return the @@ -199,6 +203,7 @@ function getOrigin(originNoSuffix, firstParty) { /** * Sets a storage item for an origin. + * * @param {("cookie"|"localStorage")} storageType - Which storage type to use. * @param {String} originNoSuffix - Context to set storage item in. * @param {String} [firstParty] - Optional first party domain to partition @@ -227,6 +232,7 @@ function setStorageEntry(storageType, originNoSuffix, firstParty, key, value) { * For the purpose of this test we assume that there is either one or no cookie * set. * This performs cookie lookups directly via the cookie service. + * * @param {boolean} hasCookie - Whether we expect to see a cookie. * @param {String} originNoSuffix - Origin the cookie is stored for. * @param {String|null} firstParty - Whether to test for a partitioned cookie. @@ -257,6 +263,7 @@ function testHasCookie(hasCookie, originNoSuffix, firstParty, key, value) { /** * Tests whether a context has a localStorage entry. + * * @param {boolean} hasEntry - Whether we expect to see an entry. * @param {String} originNoSuffix - Origin to test localStorage for. * @param {String} [firstParty] - First party context to test under. @@ -299,6 +306,7 @@ function testHasLocalStorageEntry( * 3. third party partitioned ( B under A) * 4. third party partitioned ( A under B) * The entry values reflect which context they are set for. + * * @param {("cookie"|"localStorage")} storageType - Storage type to initialize. */ async function setupInitialStorageState(storageType) { diff --git a/toolkit/components/antitracking/test/browser/browser_siteSpecificWorkAroundsComplex.js b/toolkit/components/antitracking/test/browser/browser_siteSpecificWorkAroundsComplex.js @@ -11,6 +11,7 @@ let db; /** * Load a tracker in third-party context. + * * @param {string} topLevelURL - The URL of the top level page to load. * @param {boolean} usePrivateWindow - Whether to use a private window. * @returns {Promise} A promise that resolves when the tracker is loaded or diff --git a/toolkit/components/antitracking/test/browser/browser_staticPartition_tls_session.js b/toolkit/components/antitracking/test/browser/browser_staticPartition_tls_session.js @@ -21,6 +21,7 @@ const TEST_URL_C = TEST_ORIGIN_C + TEST_ENDPOINT; /** * Waits for a load with the given URL to happen and returns the peerId. + * * @param {string} url - The URL expected to load. * @returns {Promise<string>} a promise which resolves on load with the * associated socket peerId. @@ -51,6 +52,7 @@ async function waitForLoad(url) { * associated with the load. * Note: Loads are identified by URI. If multiple loads with the same URI happen * concurrently, this method may not map them correctly. + * * @param {MozBrowser} browser * @param {string} url * @returns {Promise<string>} Resolves on load with the peer id associated with diff --git a/toolkit/components/antitracking/test/browser/browser_storageAccess_cookies_on_grant.js b/toolkit/components/antitracking/test/browser/browser_storageAccess_cookies_on_grant.js @@ -5,6 +5,7 @@ /** * Inserts an iframe element and resolves once the iframe has loaded. + * * @param {*} browser - Browser to insert the iframe into. * @param {string} url - URL to load in the iframe. * @returns {Promise<BrowsingContext>} Promise which resolves to the iframe's diff --git a/toolkit/components/antitracking/test/browser/browser_urlQueryStringStripping_nimbus.js b/toolkit/components/antitracking/test/browser/browser_urlQueryStringStripping_nimbus.js @@ -33,6 +33,7 @@ async function waitForListServiceInit(strippingEnabled) { /** * Set a list of prefs on the default branch and restore the original values on test end. + * * @param {*} prefs - Key value pairs in an array. */ function setDefaultPrefs(prefs) { diff --git a/toolkit/components/antitracking/test/browser/head.js b/toolkit/components/antitracking/test/browser/head.js @@ -159,6 +159,7 @@ function setCookieBehaviorPref(cookieBehavior, runInPrivateWindow) { /** * Wait for the exception list service to initialize. + * * @param {string} [urlPattern] - The URL pattern to wait for to be present. * Pass null to wait for all entries to be removed. */ @@ -182,6 +183,7 @@ async function waitForExceptionListServiceSynced(urlPattern) { /** * Wait for a content blocking event to occur. + * * @param {Window} win - The window to listen for the event on. * @returns {Promise} A promise that resolves when the event occurs. */ @@ -201,6 +203,7 @@ async function waitForContentBlockingEvent(win) { /** * Dispatch a RemoteSettings "sync" event. + * * @param {string} collectionName - The remote setting collection name * @param {Object} data - The event's data payload. * @param {Object} [data.created] - Records that were created. @@ -225,6 +228,7 @@ async function remoteSettingsSync( /** * Set exceptions via RemoteSettings. + * * @param {Object[]} entries - The entries to set. If empty, the exceptions will be cleared. * @param {Object} db - The Remote Settings collections database. * @param {Object} collectionName The remote setting collection name diff --git a/toolkit/components/asyncshutdown/AsyncShutdown.sys.mjs b/toolkit/components/asyncshutdown/AsyncShutdown.sys.mjs @@ -107,6 +107,7 @@ PromiseSet.prototype = { * * Note that calling `wait()` causes Promise to be removed from the * Set once they are resolved. + * * @param {function} onDoneCb invoked synchronously once all the entries * have been handled and no new entries will be accepted. * @return {Promise} Resolved once all Promise have been resolved or removed, diff --git a/toolkit/components/asyncshutdown/nsAsyncShutdown.sys.mjs b/toolkit/components/asyncshutdown/nsAsyncShutdown.sys.mjs @@ -28,6 +28,7 @@ class PropertyBagConverter { /** * Converts from a PropertyBag to a JS value. + * * @param {nsIPropertyBag} bag The PropertyBag to convert. * @returns {jsval} A JS value. */ @@ -63,6 +64,7 @@ class PropertyBagConverter { /** * Converts from a JS value to a PropertyBag. + * * @param {jsval} val JS value to convert. * @returns {nsIPropertyBag} A PropertyBag. * @note function is converted to "(function)" and undefined to null. diff --git a/toolkit/components/cleardata/ClearDataService.sys.mjs b/toolkit/components/cleardata/ClearDataService.sys.mjs @@ -61,6 +61,7 @@ XPCOMUtils.defineLazyPreferenceGetter( /** * Adds brackets to a host if it's an IPv6 address. + * * @param {string} host - Host which may be an IPv6. * @returns {string} bracketed IPv6 or host if host is not an IPv6. */ @@ -81,6 +82,7 @@ function maybeFixupIpv6(host) { * Test if (host, OriginAttributes) or principal belong to a (schemeless) site. * Also considers partitioned storage by inspecting OriginAttributes * partitionKey. + * * @param options * @param {string} [options.host] - Optional host to compare to site. * @param {object} [options.originAttributes] - Optional origin attributes to @@ -812,6 +814,7 @@ const MediaDevicesCleaner = { const QuotaCleaner = { /** * Clear quota storage for matching principals. + * * @param {function} filterFn - Filter function which is passed a principal. * Return true to clear storage for given principal or false to skip it. * @returns {Promise} - Resolves once all matching items have been cleared. @@ -1163,6 +1166,7 @@ const PredictorNetworkCleaner = { const PushNotificationsCleaner = { /** * Clear entries for aDomain including subdomains of aDomain. + * * @param {string} aDomain - Domain to clear data for. * @param {Object} aOriginAttributesPattern - Optional pattern to filter OriginAttributes. * @returns {Promise} a promise which resolves once data has been cleared. diff --git a/toolkit/components/cleardata/SiteDataTestUtils.sys.mjs b/toolkit/components/cleardata/SiteDataTestUtils.sys.mjs @@ -71,6 +71,7 @@ export var SiteDataTestUtils = { /** * Adds a new cookie for the specified origin or host + path + oa, with the * specified contents. The cookie will be valid for one day. + * * @param {object} options * @param {String} [options.origin] - Origin of the site to add test data for. * If set, overrides host, path and originAttributes args. diff --git a/toolkit/components/cleardata/tests/browser/browser_image_cache.js b/toolkit/components/cleardata/tests/browser/browser_image_cache.js @@ -63,6 +63,7 @@ async function testCached( /** * Creates tabs and loads images in first party and third party context. + * * @returns {Promise} - Promise which resolves once all tabs are initialized, * {@link originToTabs} is populated and (sub-)resources have loaded. */ diff --git a/toolkit/components/cleardata/tests/browser/browser_sessionStorage.js b/toolkit/components/cleardata/tests/browser/browser_sessionStorage.js @@ -80,6 +80,7 @@ async function testHasEntry( /** * Creates tabs and sets sessionStorage entries in first party and third party * context. + * * @returns {Promise} - Promise which resolves once all tabs are initialized, * {@link originToTabs} is populated and (sub-)resources have loaded. */ diff --git a/toolkit/components/cleardata/tests/unit/test_network_cache.js b/toolkit/components/cleardata/tests/unit/test_network_cache.js @@ -29,7 +29,6 @@ function getPartitionedLoadContextInfo( * For now, we need to actively wait for the cache to be cleared before we can proceed. * This needs to be removed once bug 1839340 is resolved. * - * * @param {String} url - Waiting until there is no entry of this url in the cache anymore * @param {string[]} cacheTypes - The caches that should be chacked, e.g ["disk", "memory"] * @param {Object[]} partitionContexts - Defines which partitions should be checked in addition. diff --git a/toolkit/components/cleardata/tests/unit/test_quota.js b/toolkit/components/cleardata/tests/unit/test_quota.js @@ -20,6 +20,7 @@ const skipLocalStorageTests = Services.prefs.getBoolPref( /** * Create an origin with partitionKey. + * * @param {String} host - Host portion of origin to create. * @param {String} [topLevelBaseDomain] - Optional first party base domain to use for partitionKey. * @param {Object} [originAttributes] - Optional object of origin attributes to @@ -124,6 +125,7 @@ async function setTestEntries(storageType) { /** * Run the base domain test with either localStorage or indexedDB. + * * @param {('localStorage'|'indexedDB')} storageType */ async function runTestBaseDomain(storageType) { @@ -191,6 +193,7 @@ async function runTestBaseDomain(storageType) { /** * Run the host test with either localStorage or indexedDB. + * * @param {('localStorage'|'indexedDB')} storageType */ async function runTestHost(storageType) { @@ -259,6 +262,7 @@ async function runTestHost(storageType) { /** * Run the principal test with either localStorage or indexedDB. + * * @param {('localStorage'|'indexedDB')} storageType */ async function runTestPrincipal(storageType) { diff --git a/toolkit/components/contentprefs/ContentPrefService2.sys.mjs b/toolkit/components/contentprefs/ContentPrefService2.sys.mjs @@ -70,6 +70,7 @@ function executeStatementsInTransaction(conn, stmts) { /** * Helper function to extract a non-empty group from a URI. + * * @param {nsIURI} uri The URI to extract from. * @returns {string} a non-empty group. * @throws if a non-empty group cannot be extracted. diff --git a/toolkit/components/cookiebanners/CookieBannerChild.sys.mjs b/toolkit/components/cookiebanners/CookieBannerChild.sys.mjs @@ -111,6 +111,7 @@ export class CookieBannerChild extends JSWindowActorChild { /** * Whether the feature is enabled based on pref state. + * * @type {boolean} true if feature is enabled, false otherwise. */ get #isEnabled() { @@ -135,6 +136,7 @@ export class CookieBannerChild extends JSWindowActorChild { /** * Whether the feature is enabled in detect-only-mode where cookie banner * detection events are dispatched, but banners aren't handled. + * * @type {boolean} true if feature mode is enabled, false otherwise. */ get #isDetectOnly() { @@ -157,6 +159,7 @@ export class CookieBannerChild extends JSWindowActorChild { /** * Checks whether we handled a banner for this site by injecting cookies and * dispatches events. + * * @returns {boolean} Whether we handled the banner and dispatched events. */ #dispatchEventsForBannerHandledByInjection() { diff --git a/toolkit/components/cookiebanners/CookieBannerListService.sys.mjs b/toolkit/components/cookiebanners/CookieBannerListService.sys.mjs @@ -321,6 +321,7 @@ export class CookieBannerListService { /** * Converts runContext string field to nsIClickRule::RunContext + * * @param {('top'|'child'|'all')} runContextStr - Run context as string. * @returns nsIClickRule::RunContext representation. */ diff --git a/toolkit/components/cookiebanners/test/browser/browser_bannerClicking_events.js b/toolkit/components/cookiebanners/test/browser/browser_bannerClicking_events.js @@ -7,6 +7,7 @@ add_setup(clickTestSetup); /** * Triggers cookie banner clicking and tests the events dispatched. + * * @param {*} options - Test options. * @param {nsICookieBannerService::Modes} options.mode - The cookie banner service mode to test with. * @param {boolean} options.detectOnly - Whether the service should be enabled diff --git a/toolkit/components/cookiebanners/test/browser/browser_bannerClicking_runContext.js b/toolkit/components/cookiebanners/test/browser/browser_bannerClicking_runContext.js @@ -7,6 +7,7 @@ add_setup(clickTestSetup); /** * Insert a test rule with the specified runContext. + * * @param {RunContext} - The runContext to set for the rule. See nsIClickRule * for documentation. */ diff --git a/toolkit/components/cookiebanners/test/browser/browser_bannerClicking_visibilityOverride.js b/toolkit/components/cookiebanners/test/browser/browser_bannerClicking_visibilityOverride.js @@ -11,6 +11,7 @@ add_setup(clickTestSetup); /** * Insert a test rule with or without the skipPresenceVisibilityCheck flag. + * * @param {boolean} skipPresenceVisibilityCheck - Whether to set the flag for * the test rule. */ diff --git a/toolkit/components/cookiebanners/test/browser/browser_cookiebanner_webconsole.js b/toolkit/components/cookiebanners/test/browser/browser_cookiebanner_webconsole.js @@ -10,6 +10,7 @@ const { SiteDataTestUtils } = ChromeUtils.importESModule( /** * Registers a console listener and waits for the cookie banner handled message * to be logged. + * * @returns {Promise} - Promise which resolves once the message has been logged. */ async function waitForCookieBannerHandledConsoleMsg() { diff --git a/toolkit/components/cookiebanners/test/browser/browser_cookiebannerservice_hasRuleForBCTree.js b/toolkit/components/cookiebanners/test/browser/browser_cookiebannerservice_hasRuleForBCTree.js @@ -47,6 +47,7 @@ let testRules = [ /** * Insert an iframe and wait for it to load. + * * @param {BrowsingContext} parentBC - The BC the frame to insert under. * @param {string} uri - The URI to load in the frame. * @returns {Promise} - A Promise which resolves once the frame has loaded. diff --git a/toolkit/components/cookiebanners/test/browser/browser_cookieinjector.js b/toolkit/components/cookiebanners/test/browser/browser_cookieinjector.js @@ -42,6 +42,7 @@ function assertNoCookies() { /** * Loads a list of urls consecutively from the same tab. + * * @param {string[]} urls - List of urls to load. */ async function visitTestSites(urls = [ORIGIN_A, ORIGIN_B, ORIGIN_C]) { diff --git a/toolkit/components/cookiebanners/test/browser/head.js b/toolkit/components/cookiebanners/test/browser/head.js @@ -373,6 +373,7 @@ function insertTestCookieRules() { /** * Triggers a cookie banner handling feature and tests the events dispatched. + * * @param {*} options - Test options. * @param {nsICookieBannerService::Modes} options.mode - The cookie banner * service mode to test with. diff --git a/toolkit/components/cookiebanners/test/unit/test_cookiebannerlistservice.js b/toolkit/components/cookiebanners/test/unit/test_cookiebannerlistservice.js @@ -188,6 +188,7 @@ add_setup(async () => { /** * Promise wrapper to listen for Services.cookieBanners.insertRule calls from * the CookieBannerListService. + * * @param {function} checkFn - Function which returns true or false to indicate * if this is the insert the caller is looking for. * @returns {Promise} - Promise which resolves when checkFn matches after diff --git a/toolkit/components/crashes/CrashManager.in.sys.mjs b/toolkit/components/crashes/CrashManager.in.sys.mjs @@ -1677,6 +1677,7 @@ CrashStore.prototype = Object.freeze({ /** * Ensure the submission record is present in storage. + * * @returns [submission, crash] */ _ensureSubmissionRecord(crashID, submissionID) { diff --git a/toolkit/components/credentialmanagement/IdentityCredentialPromptService.sys.mjs b/toolkit/components/credentialmanagement/IdentityCredentialPromptService.sys.mjs @@ -102,6 +102,7 @@ export class IdentityCredentialPromptService { /** * Ask the user, using a PopupNotification, to select an Identity Provider from a provided list. + * * @param {BrowsingContext} browsingContext - The BrowsingContext of the document requesting an identity credential via navigator.credentials.get() * @param {IdentityProviderConfig[]} identityProviders - The list of identity providers the user selects from * @param {IdentityProviderAPIConfig[]} identityManifests - The manifests corresponding 1-to-1 with identityProviders @@ -313,6 +314,7 @@ export class IdentityCredentialPromptService { /** * Ask the user, using a PopupNotification, to select an account from a provided list. + * * @param {BrowsingContext} browsingContext - The BrowsingContext of the document requesting an identity credential via navigator.credentials.get() * @param {IdentityProviderAccountList} accountList - The list of accounts the user selects from * @param {IdentityProviderConfig} provider - The selected identity provider @@ -562,6 +564,7 @@ export class IdentityCredentialPromptService { /** * Close all UI from the other methods of this module for the provided window. + * * @param {BrowsingContext} browsingContext - The BrowsingContext of the document requesting an identity credential via navigator.credentials.get() * @returns */ diff --git a/toolkit/components/downloads/DownloadIntegration.sys.mjs b/toolkit/components/downloads/DownloadIntegration.sys.mjs @@ -1035,6 +1035,7 @@ export var DownloadIntegration = { /** * Launches the specified file, unless overridden by regression tests. + * * @note Always use launchDownload() from the outside of this module, it is * both more powerful and safer. */ diff --git a/toolkit/components/downloads/test/unit/head.js b/toolkit/components/downloads/test/unit/head.js @@ -130,6 +130,7 @@ function getTempFile(leafName) { /** * Check for file existence. + * * @param {string} path The file path. */ async function fileExists(path) { diff --git a/toolkit/components/glean/tests/browser/browser_fog_gmp.js b/toolkit/components/glean/tests/browser/browser_fog_gmp.js @@ -5,6 +5,7 @@ /** * Return a web-based URL for a given file based on the testing directory. + * * @param {String} fileName * file that caller wants its web-based url */ diff --git a/toolkit/components/glean/tests/browser/browser_fog_rdd.js b/toolkit/components/glean/tests/browser/browser_fog_rdd.js @@ -5,6 +5,7 @@ /** * Return a web-based URL for a given file based on the testing directory. + * * @param {String} fileName * file that caller wants its web-based url */ diff --git a/toolkit/components/messaging-system/schemas/SpecialMessageActionSchemas/test/browser/head.js b/toolkit/components/messaging-system/schemas/SpecialMessageActionSchemas/test/browser/head.js @@ -31,6 +31,7 @@ const EXAMPLE_URL = "https://example.com/"; const SMATestUtils = { /** * Checks if an action is valid acording to existing schemas + * * @param {SpecialMessageAction} action */ async validateAction(action) { @@ -52,6 +53,7 @@ const SMATestUtils = { /** * Executes a Special Message Action after validating it + * * @param {SpecialMessageAction} action * @param {Browser} browser */ diff --git a/toolkit/components/nimbus/ExperimentAPI.sys.mjs b/toolkit/components/nimbus/ExperimentAPI.sys.mjs @@ -660,6 +660,7 @@ export class _ExperimentFeature { /** * Lookup feature variables in experiments, rollouts, and fallback prefs. + * * @param {{defaultValues?: {[variableName: string]: any}}} options * @returns {{[variableName: string]: any}} The feature value */ diff --git a/toolkit/components/nimbus/lib/ExperimentManager.sys.mjs b/toolkit/components/nimbus/lib/ExperimentManager.sys.mjs @@ -400,7 +400,6 @@ export class ExperimentManager { * either "normandy_id" or "group_id". * * @param {object} bucketConfig - * */ async getUserId(bucketConfig) { let id; @@ -1746,6 +1745,7 @@ class AboutConfigObserver { /** * Record that a pref is about to change. + * * @param {string} pref The pref. */ #onWillChange(pref) { @@ -1754,6 +1754,7 @@ class AboutConfigObserver { /** * Record that a pref has finished changing. + * * @param {string} pref The pref. */ #onChanged(pref) { diff --git a/toolkit/components/nimbus/lib/ExperimentStore.sys.mjs b/toolkit/components/nimbus/lib/ExperimentStore.sys.mjs @@ -309,6 +309,7 @@ export class ExperimentStore extends SharedDataMap { /** * Returns all active experiments + * * @returns {Enrollment[]} */ getAllActiveExperiments() { @@ -319,6 +320,7 @@ export class ExperimentStore extends SharedDataMap { /** * Returns all active rollouts + * * @returns {Enrollment[]} */ getAllActiveRollouts() { @@ -330,6 +332,7 @@ export class ExperimentStore extends SharedDataMap { /** * Returns a Map from the setPrefs from all active experiments to * the pref values that the experiment overwrote. + * * @returns {nsIPrefOverrideMap} */ getOriginalPrefValuesForAllActiveEnrollments() { @@ -348,6 +351,7 @@ export class ExperimentStore extends SharedDataMap { /** * Query the store for the remote configuration of a feature + * * @param {string} featureId The feature we want to query for * @returns {{Rollout}|undefined} Remote defaults if available */ @@ -441,6 +445,7 @@ export class ExperimentStore extends SharedDataMap { /** * Persists early startup experiments or rollouts + * * @param {Enrollment} enrollment Experiment or rollout */ _updateSyncStore(enrollment) { @@ -473,6 +478,7 @@ export class ExperimentStore extends SharedDataMap { /** * Add an enrollment and notify listeners + * * @param {object} enrollment The enrollment to add. * @param {object} recipe The recipe for the enrollment that was enrolled. */ diff --git a/toolkit/components/nimbus/lib/Migrations.sys.mjs b/toolkit/components/nimbus/lib/Migrations.sys.mjs @@ -355,7 +355,6 @@ export const NimbusMigrations = { * application of further migrations in the phase. * * @param {Phase} phase The phase of migrations to apply. - * */ async applyMigrations(phase) { const phasePref = NIMBUS_MIGRATION_PREFS[phase]; diff --git a/toolkit/components/nimbus/lib/RemoteSettingsExperimentLoader.sys.mjs b/toolkit/components/nimbus/lib/RemoteSettingsExperimentLoader.sys.mjs @@ -1085,6 +1085,7 @@ export class EnrollmentsContext { /** * Checks targeting of a recipe if it is defined + * * @param {Recipe} recipe * @param {{[key: string]: any}} customContext A custom filter context * @returns {Promise<boolean>} Should we process the recipe? diff --git a/toolkit/components/normandy/actions/BranchedAddonStudyAction.sys.mjs b/toolkit/components/normandy/actions/BranchedAddonStudyAction.sys.mjs @@ -342,6 +342,7 @@ export class BranchedAddonStudyAction extends BaseStudyAction { /** * Enroll in the study represented by the given recipe. + * * @param recipe Object describing the study to enroll in. * @param extensionDetails Object describing the addon to be installed. */ @@ -499,6 +500,7 @@ export class BranchedAddonStudyAction extends BaseStudyAction { /** * Update the study represented by the given recipe. + * * @param recipe Object describing the study to be updated. * @param extensionDetails Object describing the addon to be installed. */ @@ -679,6 +681,7 @@ export class BranchedAddonStudyAction extends BaseStudyAction { /** * Unenrolls the client from the study with a given recipe ID. + * * @param recipeId The recipe ID of an enrolled study * @param reason The reason for this unenrollment, to be used in Telemetry * @throws If the specified study does not exist, or if it is already inactive. diff --git a/toolkit/components/normandy/actions/PreferenceRolloutAction.sys.mjs b/toolkit/components/normandy/actions/PreferenceRolloutAction.sys.mjs @@ -142,6 +142,7 @@ export class PreferenceRolloutAction extends BaseAction { * Check that all the preferences in a rollout are ok to set. This means 1) no * other rollout is managing them, and 2) they match the types of the builtin * values. + * * @param {PreferenceRollout} rollout The arguments from a rollout recipe. * @throws If the preferences are not valid, with details in the error message. */ diff --git a/toolkit/components/normandy/actions/ShowHeartbeatAction.sys.mjs b/toolkit/components/normandy/actions/ShowHeartbeatAction.sys.mjs @@ -156,6 +156,7 @@ export class ShowHeartbeatAction extends BaseAction { /** * Generate the appropriate post-answer URL for a recipe. + * * @param recipe * @return {String} URL with post-answer query params */ @@ -208,6 +209,7 @@ export class ShowHeartbeatAction extends BaseAction { /** * Get last shown time in milliseconds since epoch for a recipe. + * * @param {string | null} recipeId * ID of the recipe to look up, or null for the max across recipes. * @returns {Promise<number | null>} The last shown date, if any. @@ -230,6 +232,7 @@ export class ShowHeartbeatAction extends BaseAction { /** * Get last interaction time in milliseconds since epoch for a recipe. + * * @param {string | null} recipeId * ID of the recipe to look up, or null for the max across recipes. * @returns {Promise<number | null>} The last interaction date, if any. @@ -252,6 +255,7 @@ export class ShowHeartbeatAction extends BaseAction { /** * Set a last shown for a recipe. + * * @param {string} recipeId * ID of the recipe to update. * @param {number} lastShown @@ -272,6 +276,7 @@ export class ShowHeartbeatAction extends BaseAction { /** * Set a last interaction for a recipe. + * * @param {string} recipeId * ID of the recipe to update. * @param {number} lastInteraction diff --git a/toolkit/components/normandy/content/AboutPages.sys.mjs b/toolkit/components/normandy/content/AboutPages.sys.mjs @@ -74,6 +74,7 @@ export let AboutPages = {}; let BrowsingContexts = new WeakSet(); /** * about:studies page for displaying in-progress and past Shield studies. + * * @type {AboutPage} * @implements {nsIMessageListener} */ @@ -143,6 +144,7 @@ ChromeUtils.defineLazyGetter(AboutPages, "aboutStudies", () => { /** * Sends a message to every about:studies page, * by iterating over the BrowsingContexts weakset. + * * @param {string} message The message string to send to. * @param {object} data The data object to send. */ @@ -167,6 +169,7 @@ ChromeUtils.defineLazyGetter(AboutPages, "aboutStudies", () => { /** * Disable an active add-on study and remove its add-on. + * * @param {String} recipeId the id of the addon to remove * @param {String} reason the reason for removal */ @@ -191,6 +194,7 @@ ChromeUtils.defineLazyGetter(AboutPages, "aboutStudies", () => { /** * Disable an active preference study. + * * @param {String} experimentName the name of the experiment to remove * @param {String} reason the reason for removal */ diff --git a/toolkit/components/normandy/content/ShieldFrameChild.sys.mjs b/toolkit/components/normandy/content/ShieldFrameChild.sys.mjs @@ -154,6 +154,7 @@ export class ShieldFrameChild extends JSWindowActorChild { } /** * Trigger an event to communicate with the unprivileged about:studies page. + * * @param {String} type The type of event to trigger. * @param {Object} detail The data to pass along to the event. */ diff --git a/toolkit/components/normandy/content/about-studies/about-studies.js b/toolkit/components/normandy/content/about-studies/about-studies.js @@ -12,6 +12,7 @@ const r = React.createElement; /** * Dispatches a page event to the privileged frame script for this tab. + * * @param {String} action * @param {Object} data */ diff --git a/toolkit/components/normandy/lib/AddonRollouts.sys.mjs b/toolkit/components/normandy/lib/AddonRollouts.sys.mjs @@ -11,6 +11,7 @@ ChromeUtils.defineESModuleGetters(lazy, { /** * AddonRollouts store info about an active or expired addon rollouts. + * * @typedef {object} AddonRollout * @property {int} recipeId * The ID of the recipe. @@ -98,6 +99,7 @@ export const AddonRollouts = { /** * Add a new rollout + * * @param {AddonRollout} rollout */ async add(rollout) { @@ -107,6 +109,7 @@ export const AddonRollouts = { /** * Update an existing rollout + * * @param {AddonRollout} rollout * @throws If a matching rollout does not exist. */ @@ -123,6 +126,7 @@ export const AddonRollouts = { /** * Update many existing rollouts. More efficient than calling `update` many * times in a row. + * * @param {Array<PreferenceRollout>} rollouts * @throws If any of the passed rollouts have a slug that doesn't exist in the database already. */ @@ -156,6 +160,7 @@ export const AddonRollouts = { /** * Test whether there is a rollout in storage with the given slug. + * * @param {string} slug * @returns {Promise<boolean>} */ @@ -167,6 +172,7 @@ export const AddonRollouts = { /** * Get a rollout by slug + * * @param {string} slug */ async get(slug) { diff --git a/toolkit/components/normandy/lib/AddonStudies.sys.mjs b/toolkit/components/normandy/lib/AddonStudies.sys.mjs @@ -236,6 +236,7 @@ export var AddonStudies = { /** * If a study add-on is uninstalled, mark the study as having ended. + * * @param {Addon} addon */ async onUninstalled(addon) { @@ -258,6 +259,7 @@ export var AddonStudies = { /** * Test whether there is a study in storage for the given recipe ID. + * * @param {Number} recipeId * @returns {Boolean} */ @@ -269,6 +271,7 @@ export var AddonStudies = { /** * Fetch a study from storage. + * * @param {Number} recipeId * @return {Study} The requested study, or null if none with that ID exist. */ @@ -283,6 +286,7 @@ export var AddonStudies = { /** * Fetch all studies in storage. + * * @return {Array<Study>} */ async getAll({ branched = AddonStudies.FILTER_ALL } = {}) { @@ -303,6 +307,7 @@ export var AddonStudies = { /** * Fetch all studies in storage. + * * @return {Array<Study>} */ async getAllActive(options) { @@ -311,6 +316,7 @@ export var AddonStudies = { /** * Add a study to storage. + * * @return {Promise<void, Error>} Resolves when the study is stored, or rejects with an error. */ async add(study) { @@ -320,6 +326,7 @@ export var AddonStudies = { /** * Update a study in storage. + * * @return {Promise<void, Error>} Resolves when the study is updated, or rejects with an error. */ async update(study) { @@ -330,6 +337,7 @@ export var AddonStudies = { /** * Update many existing studies. More efficient than calling `update` many * times in a row. + * * @param {Array<AddonStudy>} studies * @throws If any of the passed studies have a slug that doesn't exist in the database already. */ @@ -365,6 +373,7 @@ export var AddonStudies = { /** * Remove a study from storage + * * @param recipeId The recipeId of the study to delete * @return {Promise<void, Error>} Resolves when the study is deleted, or rejects with an error. */ @@ -375,6 +384,7 @@ export var AddonStudies = { /** * Mark a study object as having ended. Modifies the study in-place. + * * @param {IDBDatabase} db * @param {Study} study * @param {String} reason Why the study is ending. diff --git a/toolkit/components/normandy/lib/ClientEnvironment.sys.mjs b/toolkit/components/normandy/lib/ClientEnvironment.sys.mjs @@ -40,6 +40,7 @@ export class ClientEnvironment extends ClientEnvironmentBase { /** * Test wrapper that mocks the server request for classifying the client. + * * @param {Object} data Fake server data to use * @param {Function} testFunction Test function to execute while mock data is in effect. */ diff --git a/toolkit/components/normandy/lib/LogManager.sys.mjs b/toolkit/components/normandy/lib/LogManager.sys.mjs @@ -11,6 +11,7 @@ export var LogManager = { /** * Configure the root logger for the Recipe Client. Must be called at * least once before using any loggers created via getLogger. + * * @param {Number} loggingLevel * Logging level to use as defined in Log.sys.mjs */ @@ -24,6 +25,7 @@ export var LogManager = { /** * Obtain a named logger with the recipe client logger as its parent. + * * @param {String} name * Name of the logger to obtain. * @return {Logger} diff --git a/toolkit/components/normandy/lib/NormandyApi.sys.mjs b/toolkit/components/normandy/lib/NormandyApi.sys.mjs @@ -131,6 +131,7 @@ export var NormandyApi = { /** * Fetch metadata about this client determined by the server. + * * @return {object} Metadata specified by the server */ async classifyClient() { @@ -143,6 +144,7 @@ export var NormandyApi = { /** * Fetch details for an extension from the server. + * * @param extensionId {integer} The ID of the extension to look up * @resolves {Object} */ diff --git a/toolkit/components/normandy/lib/PreferenceExperiments.sys.mjs b/toolkit/components/normandy/lib/PreferenceExperiments.sys.mjs @@ -19,6 +19,7 @@ /** * Experiments store info about an active or expired preference experiment. + * * @typedef {Object} Experiment * @property {string} slug * A string uniquely identifying the experiment. Used for telemetry, and other @@ -54,6 +55,7 @@ /** * Each Preference stores information about a preference that an * experiment sets. + * * @property {string|integer|boolean} preferenceValue * Value to change the preference to during the experiment. * @property {string} preferenceType @@ -103,6 +105,7 @@ const DefaultPreferences = Services.prefs.getDefaultBranch(""); /** * Enum storing Preference modules for each type of preference branch. + * * @enum {Object} */ const PreferenceBranchType = { @@ -148,6 +151,7 @@ CleanupManager.addCleanupHandler(() => export var PreferenceExperiments = { /** * Update the the experiment storage with changes that happened during early startup. + * * @param {object} studyPrefsChanged Map from pref name to previous pref value */ async recordOriginalValues(studyPrefsChanged) { @@ -318,6 +322,7 @@ export var PreferenceExperiments = { /** * Start a new preference experiment. + * * @param {Object} experiment * @param {string} experiment.slug * @param {string} experiment.actionName The action who knows about this @@ -529,6 +534,7 @@ export var PreferenceExperiments = { /** * Register a preference observer that stops an experiment when the user * modifies the preference. + * * @param {string} experimentSlug * @param {string} preferenceName * @param {string|integer|boolean} preferenceValue @@ -576,6 +582,7 @@ export var PreferenceExperiments = { /** * Check if a preference observer is active for an experiment. + * * @param {string} experimentSlug * @return {Boolean} */ @@ -586,6 +593,7 @@ export var PreferenceExperiments = { /** * Disable a preference observer for an experiment. + * * @param {string} experimentSlug * @throws {Error} * If there is no active observer for the experiment. @@ -622,6 +630,7 @@ export var PreferenceExperiments = { /** * Update the timestamp storing when Normandy last sent a recipe for the * experiment. + * * @param {string} experimentSlug * @rejects {Error} * If there is no stored experiment with the given slug. @@ -688,6 +697,7 @@ export var PreferenceExperiments = { /** * Stop an active experiment, deactivate preference watchers, and optionally * reset the associated preference to its previous value. + * * @param {string} experimentSlug * @param {Object} options * @param {boolean} [options.resetValue = true] @@ -832,6 +842,7 @@ export var PreferenceExperiments = { /** * Get the experiment object for the experiment. + * * @param {string} experimentSlug * @resolves {Experiment} * @rejects {Error} @@ -851,6 +862,7 @@ export var PreferenceExperiments = { /** * Get a list of all stored experiment objects. + * * @resolves {Experiment[]} */ async getAll() { @@ -862,6 +874,7 @@ export var PreferenceExperiments = { /** * Get a list of experiment objects for all active experiments. + * * @resolves {Experiment[]} */ async getAllActive() { @@ -873,6 +886,7 @@ export var PreferenceExperiments = { /** * Check if an experiment exists with the given slug. + * * @param {string} experimentSlug * @resolves {boolean} True if the experiment exists, false if it doesn't. */ diff --git a/toolkit/components/normandy/lib/PreferenceRollouts.sys.mjs b/toolkit/components/normandy/lib/PreferenceRollouts.sys.mjs @@ -17,6 +17,7 @@ const log = LogManager.getLogger("recipe-runner"); /** * PreferenceRollouts store info about an active or expired preference rollout. + * * @typedef {object} PreferenceRollout * @property {string} slug * Unique slug of the experiment @@ -32,6 +33,7 @@ const log = LogManager.getLogger("recipe-runner"); /** * PreferenceSpec describe how a preference should change during a rollout. + * * @typedef {object} PreferenceSpec * @property {string} preferenceName * The preference to modify. @@ -116,6 +118,7 @@ export var PreferenceRollouts = { /** * Update the rollout database with changes that happened during early startup. + * * @param {object} rolloutPrefsChanged Map from pref name to previous pref value */ async recordOriginalValues(originalPreferences) { @@ -204,6 +207,7 @@ export var PreferenceRollouts = { /** * Add a new rollout + * * @param {PreferenceRollout} rollout */ async add(rollout) { @@ -213,6 +217,7 @@ export var PreferenceRollouts = { /** * Update an existing rollout + * * @param {PreferenceRollout} rollout * @throws If a matching rollout does not exist. */ @@ -229,6 +234,7 @@ export var PreferenceRollouts = { /** * Update many existing rollouts. More efficient than calling `update` many * times in a row. + * * @param {Array<PreferenceRollout>} rollouts * @throws If any of the passed rollouts have a slug that doesn't exist in the database already. */ @@ -262,6 +268,7 @@ export var PreferenceRollouts = { /** * Test whether there is a rollout in storage with the given slug. + * * @param {string} slug * @returns {boolean} */ @@ -273,6 +280,7 @@ export var PreferenceRollouts = { /** * Get a rollout by slug + * * @param {string} slug */ async get(slug) { diff --git a/toolkit/components/normandy/lib/Storage.sys.mjs b/toolkit/components/normandy/lib/Storage.sys.mjs @@ -35,6 +35,7 @@ export var Storage = class { /** * Sets an item in the prefixed storage. + * * @returns {Promise} * @resolves With the stored value, or null. * @rejects Javascript exception. @@ -47,6 +48,7 @@ export var Storage = class { /** * Sets an item in the prefixed storage. + * * @returns {Promise} * @resolves When the operation is completed successfully * @rejects Javascript exception. @@ -62,6 +64,7 @@ export var Storage = class { /** * Removes a single item from the prefixed storage. + * * @returns {Promise} * @resolves When the operation is completed successfully * @rejects Javascript exception. @@ -76,6 +79,7 @@ export var Storage = class { /** * Clears all storage for the prefix. + * * @returns {Promise} * @resolves When the operation is completed successfully * @rejects Javascript exception. diff --git a/toolkit/components/normandy/test/browser/browser_PreferenceExperiments.js b/toolkit/components/normandy/test/browser/browser_PreferenceExperiments.js @@ -213,6 +213,7 @@ const migrationsInfo = [ /** * Make a mock `JsonFile` object with a no-op `saveSoon` method and a deep copy * of the data passed. + * * @param {Object} data the data in the store */ function makeMockJsonFile(data = {}) { diff --git a/toolkit/components/normandy/test/browser/head.js b/toolkit/components/normandy/test/browser/head.js @@ -418,6 +418,7 @@ this.CryptoUtils = { /** * Get the computed hash for a given file + * * @param {nsIFile} file The file to be hashed * @param {string} [algorithm] The hashing algorithm to use */ diff --git a/toolkit/components/normandy/test/unit/utils.js b/toolkit/components/normandy/test/unit/utils.js @@ -123,6 +123,7 @@ const CryptoUtils = { /** * Get the computed hash for a given file + * * @param {nsIFile} file The file to be hashed * @param {string} [algorithm] The hashing algorithm to use */ diff --git a/toolkit/components/passwordmgr/LoginAutoComplete.sys.mjs b/toolkit/components/passwordmgr/LoginAutoComplete.sys.mjs @@ -390,6 +390,7 @@ export class LoginAutoCompleteResult { /** * Accessed via .wrappedJSObject + * * @private */ get logins() { diff --git a/toolkit/components/passwordmgr/LoginHelper.sys.mjs b/toolkit/components/passwordmgr/LoginHelper.sys.mjs @@ -48,6 +48,7 @@ class ImportRowProcessor { /** * Validates if the login data contains a GUID that was already found in a previous row in the current import. * If this is the case, the summary will be updated with an error. + * * @param {object} loginData * An vanilla object for the login without any methods. * @returns {boolean} True if there is an error, false otherwise. @@ -66,6 +67,7 @@ class ImportRowProcessor { /** * Validates if the login data contains invalid fields that are mandatory like origin and password. * If this is the case, the summary will be updated with an error. + * * @param {object} loginData * An vanilla object for the login without any methods. * @returns {boolean} True if there is an error, false otherwise. @@ -90,6 +92,7 @@ class ImportRowProcessor { * If there are similar values but not identical, a new "modified" entry will be added to the summary. * If there are identical values, a new "no_change" entry will be added to the summary * If either of these is the case, it will return true. + * * @param {object} loginData * An vanilla object for the login without any methods. * @returns {boolean} True if the entry is similar or identical to another previously processed entry, false otherwise. @@ -138,6 +141,7 @@ class ImportRowProcessor { * Validates if there is a conflict with previous rows based on the origin. * We need to check the logins that we've already decided to add, to see if this is a duplicate. * If this is the case, we mark this one as "no_change" in the summary and return true. + * * @param {object} login * A login object. * @returns {boolean} True if the entry is similar or identical to another previously processed entry, false otherwise. @@ -169,6 +173,7 @@ class ImportRowProcessor { * If this is the case and there are some changes, we mark it as "modified" in the summary. * If it matches an existing login without any extra modifications, we mark it as "no_change". * For both cases we return true. + * * @param {object} login * A login object. * @returns {boolean} True if the entry is similar or identical to another previously processed entry, false otherwise. @@ -224,6 +229,7 @@ class ImportRowProcessor { /** * Validates if there are any invalid values using LoginHelper.checkLoginValues. * If this is the case we mark it as "error" and return true. + * * @param {object} login * A login object. * @param {object} loginData @@ -245,6 +251,7 @@ class ImportRowProcessor { /** * Creates a new login from loginData. + * * @param {object} loginData * An vanilla object for the login without any methods. * @returns {object} A login object. @@ -275,6 +282,7 @@ class ImportRowProcessor { /** * Cleans the action and realm field of the loginData. + * * @param {object} loginData * An vanilla object for the login without any methods. */ @@ -291,6 +299,7 @@ class ImportRowProcessor { /** * Adds a login to the summary. + * * @param {object} login * A login object. * @param {string} result @@ -347,6 +356,7 @@ class ImportRowProcessor { * Iterates over all then rows where more than two match the same origin. It mutates the internal state of the processor. * It makes sure that if the `timePasswordChanged` field is present it will be used to decide if it's a "no_change" or "added". * The entry with the oldest `timePasswordChanged` will be "added", the rest will be "no_change". + * * @returns {Object[]} An entry for each processed row containing how the row was processed and the login data. */ async processLoginsAndBuildSummary() { @@ -646,6 +656,7 @@ export const LoginHelper = { /** * Helper to avoid the property bags when calling * Services.logins.searchLogins from JS. + * * @deprecated Use Services.logins.searchLoginsAsync instead. * * @param {Object} aSearchOptions - A regular JS object to copy to a property bag before searching @@ -993,6 +1004,7 @@ export const LoginHelper = { /** * Generate a unique key string from a login. + * * @param {nsILoginInfo} login * @param {string[]} uniqueKeys containing nsILoginInfo attribute names or "hostPort" * @returns {string} to use as a key in a Map @@ -1590,6 +1602,7 @@ export const LoginHelper = { /** * Shows the Primary Password prompt if enabled, or the * OS auth dialog otherwise. + * * @param {Element} browser * The <browser> that the prompt should be shown on * @param OSReauthEnabled Boolean indicating if OS reauth should be tried diff --git a/toolkit/components/passwordmgr/LoginManager.shared.sys.mjs b/toolkit/components/passwordmgr/LoginManager.shared.sys.mjs @@ -257,6 +257,7 @@ class Logic { /** * Transforms the parsed rules returned from PasswordRulesParser into a Map for easier access. * The returned Map could have the following keys: "allowed", "required", "maxlength", "minlength", and "max-consecutive" + * * @example * // Returns a Map with a key-value pair of "allowed": "ascii-printable" * transformRulesToMap([{ _name: "allowed", value: [{ _name: "ascii-printable" }] }]) diff --git a/toolkit/components/passwordmgr/LoginManagerChild.sys.mjs b/toolkit/components/passwordmgr/LoginManagerChild.sys.mjs @@ -692,6 +692,7 @@ export class LoginFormState { /** * Focus event handler for username fields to decide whether to show autocomplete. + * * @param {HTMLInputElement} focusedField */ #onUsernameFocus(focusedField) { @@ -747,6 +748,7 @@ export class LoginFormState { /** * Highlight login fields on autocomplete or autofill on page load. + * * @param {Node} element that needs highlighting. */ static _highlightFilledField(element) { @@ -2580,6 +2582,7 @@ export class LoginManagerChild extends JSWindowActorChild { /** * The password field has been filled with a generated password, ensure the * field is handled accordingly. + * * @param {HTMLInputElement} passwordField */ filledWithGeneratedPassword(passwordField) { @@ -2611,6 +2614,7 @@ export class LoginManagerChild extends JSWindowActorChild { /** * Notify the parent that a generated password was filled into a field or * edited so that it can potentially be saved. + * * @param {HTMLInputElement} passwordField */ _passwordEditedOrGenerated( @@ -2653,6 +2657,7 @@ export class LoginManagerChild extends JSWindowActorChild { /** * Filter logins for exact origin/formActionOrigin and dedupe on usernamematche + * * @param {nsILoginInfo[]} logins an array of nsILoginInfo that could be * used for the form, including ones with a different form action origin * which are only used when the fill is userTriggered diff --git a/toolkit/components/passwordmgr/LoginRecipes.sys.mjs b/toolkit/components/passwordmgr/LoginRecipes.sys.mjs @@ -35,7 +35,6 @@ ChromeUtils.defineLazyGetter(lazy, "log", () => * @constructor * @param {String} [aOptions.defaults=null] the URI to load the recipes from. * If it's null, nothing is loaded. - * */ export function LoginRecipesParent(aOptions = { defaults: null }) { if (Services.appinfo.processType != Ci.nsIXULRuntime.PROCESS_TYPE_DEFAULT) { diff --git a/toolkit/components/passwordmgr/LoginRelatedRealms.sys.mjs b/toolkit/components/passwordmgr/LoginRelatedRealms.sys.mjs @@ -60,6 +60,7 @@ export class LoginRelatedRealmsParent extends JSWindowActorParent { /** * Determine if there are any related realms of this `formOrigin` using the related realms collection + * * @param {string} formOrigin A form origin * @return {string[]} filteredRealms An array of domains related to the `formOrigin` * @async diff --git a/toolkit/components/passwordmgr/OSCrypto_win.sys.mjs b/toolkit/components/passwordmgr/OSCrypto_win.sys.mjs @@ -80,6 +80,7 @@ export function OSCrypto() { OSCrypto.prototype = { /** * Convert an array containing only two bytes unsigned numbers to a string. + * * @param {number[]} arr - the array that needs to be converted. * @returns {string} the string representation of the array. */ @@ -93,6 +94,7 @@ OSCrypto.prototype = { /** * Convert a string to an array. + * * @param {string} str - the string that needs to be converted. * @returns {number[]} the array representation of the string. */ @@ -107,6 +109,7 @@ OSCrypto.prototype = { /** * Calculate the hash value used by IE as the name of the registry value where login details are * stored. + * * @param {string} data - the string value that needs to be hashed. * @returns {string} the hash value of the string. */ @@ -175,6 +178,7 @@ OSCrypto.prototype = { /** * Decrypt a string using the windows CryptUnprotectData API. + * * @param {string} data - the encrypted string that needs to be decrypted. * @param {?string} entropy - the entropy value of the decryption (could be null). Its value must * be the same as the one used when the data was encrypted. @@ -224,6 +228,7 @@ OSCrypto.prototype = { /** * Encrypt a string using the windows CryptProtectData API. + * * @param {string} data - the string that is going to be encrypted. * @param {?string} entropy - the entropy value of the encryption (could be null). Its value must * be the same as the one that is going to be used for the decryption. diff --git a/toolkit/components/passwordmgr/PasswordRulesManager.sys.mjs b/toolkit/components/passwordmgr/PasswordRulesManager.sys.mjs @@ -42,6 +42,7 @@ export class PasswordRulesManagerParent extends JSWindowActorParent { /** * Generates a password based on rules from the origin parameters. + * * @param {nsIURI} uri * @return {string} password * @memberof PasswordRulesManagerParent diff --git a/toolkit/components/passwordmgr/shared/PasswordGenerator.sys.mjs b/toolkit/components/passwordmgr/shared/PasswordGenerator.sys.mjs @@ -126,6 +126,7 @@ export const PasswordGenerator = { /** * Adds special characters and/or other required characters to the requiredCharacters array. + * * @param {Map} rules * @param {string[]} requiredClasses */ @@ -171,6 +172,7 @@ export const PasswordGenerator = { /** * Shuffle the order of characters in a string. + * * @param {string} str to shuffle * @returns {string} shuffled string */ @@ -193,6 +195,7 @@ export const PasswordGenerator = { * Determine the number of consecutive characters in a string. * This is primarily used to validate the "max-consecutive" rule * of a generated password. + * * @param {string} generatedPassword * @param {number} value the number of consecutive characters allowed * @return {boolean} `true` if the generatePassword has less than the value argument number of characters, `false` otherwise diff --git a/toolkit/components/passwordmgr/storage-geckoview.sys.mjs b/toolkit/components/passwordmgr/storage-geckoview.sys.mjs @@ -213,6 +213,7 @@ export class LoginManagerStorage extends LoginManagerStorage_json { /** * GeckoView logins are already decrypted before this component receives them * so this method is a no-op for this backend. + * * @see _vanillaLoginToStorageLogin */ _decryptLogins(logins) { diff --git a/toolkit/components/passwordmgr/storage-json.sys.mjs b/toolkit/components/passwordmgr/storage-json.sys.mjs @@ -755,7 +755,6 @@ export class LoginManagerStorage_json { * @param {Object} [aOptions] Additional options for matching * * @returns {boolean} - Returns true if the login item matches the match data, - * */ #matchLogin( aLoginItem, diff --git a/toolkit/components/passwordmgr/test/browser/browser_basicAuth_multiTab.js b/toolkit/components/passwordmgr/test/browser/browser_basicAuth_multiTab.js @@ -17,6 +17,7 @@ const AUTH_PATH = /** * Opens a tab and navigates to the auth test path. + * * @param {String} origin - Origin to open with test path. * @param {Object} authOptions - Authentication options to pass to server and * test for. @@ -53,6 +54,7 @@ async function openTabWithAuthPrompt(origin, authOptions) { /** * Waits for tab to load and tests for expected auth state. + * * @param {boolean} expectAuthed - true: auth success, false otherwise. * @param {Object} tabInfo - Information about the tab as generated by * openTabWithAuthPrompt. diff --git a/toolkit/components/passwordmgr/test/browser/browser_context_menu.js b/toolkit/components/passwordmgr/test/browser/browser_context_menu.js @@ -600,6 +600,7 @@ async function assertContextMenuFill( /** * Check if every login that matches the page origin are available at the context menu. + * * @param {Element} contextMenu * @param {Number} expectedCount - Number of logins expected in the context menu. Used to ensure * we continue testing something useful. diff --git a/toolkit/components/passwordmgr/test/browser/browser_proxyAuth_prompt.js b/toolkit/components/passwordmgr/test/browser/browser_proxyAuth_prompt.js @@ -65,6 +65,7 @@ add_setup(async function () { /** * Create an object for consuming an nsIAuthPromptCallback. + * * @returns result * @returns {nsIAuthPromptCallback} result.callback - Callback to be passed into * asyncPromptAuth. diff --git a/toolkit/components/passwordmgr/test/mochitest/pwmgr_common.js b/toolkit/components/passwordmgr/test/mochitest/pwmgr_common.js @@ -82,6 +82,7 @@ function checkAutoCompleteResults(actualValues, expectedValues, hostname, msg) { /** * Wait for autocomplete popup to get closed + * * @return {Promise} resolving when the AC popup is closed */ async function untilAutocompletePopupClosed() { @@ -299,6 +300,7 @@ function createLoginForm({ /** * Check for expected username/password in form. + * * @see `checkForm` below for a similar function. */ function checkLoginForm( @@ -358,6 +360,7 @@ function ensureCondition( /** * Wait a while to ensure login form stays filled with username and password + * * @see `checkLoginForm` below for a similar function. * @returns a promise, resolving when done * @@ -821,6 +824,7 @@ async function promisePromptShown(expectedTopic) { /** * Run a function synchronously in the parent process and destroy it in the test cleanup function. + * * @param {Function|String} aFunctionOrURL - either a function that will be stringified and run * or the URL to a JS file. * @return {Object} - the return value of loadChromeScript providing message-related methods. @@ -888,6 +892,7 @@ function manageLoginsInParent() { /** * Initialize with a list of logins. The logins are added within the parent chrome process. + * * @param {array} aLogins - a list of logins to add. Each login is an array of the arguments * that would be passed to nsLoginInfo.init(). */ @@ -900,6 +905,7 @@ async function addLoginsInParent(...aLogins) { /** * Initialize with a list of logins, after removing all user facing logins. * The logins are added within the parent chrome process. + * * @param {array} aLogins - a list of logins to add. Each login is an array of the arguments * that would be passed to nsLoginInfo.init(). */ @@ -914,6 +920,7 @@ async function setStoredLoginsAsync(...aLogins) { * Sets given logins for the duration of the test. Existing logins are first * removed and finally restored when the test is finished. * The logins are added within the parent chrome process. + * * @param {array} logins - a list of logins to add. Each login is an array of the arguments * that would be passed to nsLoginInfo.init(). */ @@ -931,6 +938,7 @@ async function setStoredLoginsDuringTest(...logins) { /** * Sets given logins for the duration of the task. Existing logins are first * removed and finally restored when the task is finished. + * * @param {array} logins - a list of logins to add. Each login is an array of the arguments * that would be passed to nsLoginInfo.init(). */ diff --git a/toolkit/components/pdfjs/content/PdfStreamConverter.sys.mjs b/toolkit/components/pdfjs/content/PdfStreamConverter.sys.mjs @@ -616,6 +616,7 @@ class ChromeActions { /** * Set the different editor states in order to be able to update the context * menu. + * * @param {Object} details */ updateEditorStates({ details }) { diff --git a/toolkit/components/pdfjs/test/browser_pdfjs_editing_contextmenu.js b/toolkit/components/pdfjs/test/browser_pdfjs_editing_contextmenu.js @@ -30,6 +30,7 @@ async function openContextMenuAt(browser, x, y) { /** * Open a context menu and get the pdfjs entries + * * @param {Object} browser * @param {Object} box * @returns {Promise<Map<string,HTMLElement>>} the pdfjs menu entries. @@ -68,6 +69,7 @@ function getContextMenuItems(browser, box) { /** * Open a context menu on the element corresponding to the given selector * and returs the pdfjs menu entries. + * * @param {Object} browser * @param {string} selector * @returns {Promise<Map<string,HTMLElement>>} the pdfjs menu entries. @@ -87,6 +89,7 @@ async function getContextMenuItemsOn(browser, selector) { /** * Hide the context menu. + * * @param {Object} browser */ async function hideContextMenu(browser) { @@ -121,6 +124,7 @@ async function clickOnItem(browser, items, entry) { /** * Asserts that the enabled pdfjs menuitems are the expected ones. + * * @param {Map<string,HTMLElement>} menuitems * @param {Array<string>} expected */ diff --git a/toolkit/components/pdfjs/test/browser_pdfjs_filters.js b/toolkit/components/pdfjs/test/browser_pdfjs_filters.js @@ -6,6 +6,7 @@ const TESTROOT = "https://example.com/browser/" + RELATIVE_DIR; /** * Get the number of red pixels in the canvas. + * * @param {Object} browser * @returns {Object} */ diff --git a/toolkit/components/pdfjs/test/browser_pdfjs_hcm.js b/toolkit/components/pdfjs/test/browser_pdfjs_hcm.js @@ -6,6 +6,7 @@ const TESTROOT = "http://example.com/browser/" + RELATIVE_DIR; /** * Get the first and last pixels on the drawn canvas. + * * @param {Object} browser * @returns {Object} */ diff --git a/toolkit/components/pdfjs/test/browser_pdfjs_jpeg2000.js b/toolkit/components/pdfjs/test/browser_pdfjs_jpeg2000.js @@ -6,6 +6,7 @@ const TESTROOT = "https://example.com/browser/" + RELATIVE_DIR; /** * Get the the pixels on the drawn canvas. + * * @param {Object} browser * @returns {Object} */ diff --git a/toolkit/components/pdfjs/test/head.js b/toolkit/components/pdfjs/test/head.js @@ -185,6 +185,7 @@ async function waitForTelemetry(browser) { /** * Enable an editor (Ink, FreeText, ...). + * * @param {Object} browser * @param {string} name */ @@ -232,6 +233,7 @@ async function enableEditor(browser, name, expectedPageRendered) { /** * The text layer contains some spans with the text of the pdf. + * * @param {Object} browser * @param {string} text * @returns {Object} the bbox of the span containing the text. @@ -274,6 +276,7 @@ async function getSpanBox(browser, text, pageNumber = 1) { /** * Count the number of elements corresponding to the given selector. + * * @param {Object} browser * @param {string} selector * @returns @@ -290,6 +293,7 @@ async function countElements(browser, selector) { /** * Click at the given coordinates. + * * @param {Object} browser * @param {number} x * @param {number} y @@ -322,6 +326,7 @@ async function clickAt(browser, x, y, n = 1) { /** * Click on the element corresponding to the given selector. + * * @param {Object} browser * @param {string} selector */ @@ -349,6 +354,7 @@ function focusEditorLayer(browser) { /** * Focus an element corresponding to the given selector. + * * @param {Object} browser * @param {string} selector * @returns @@ -387,6 +393,7 @@ async function hitKey(browser, char) { /** * Write some text using the keyboard. + * * @param {Object} browser * @param {string} text */ @@ -407,6 +414,7 @@ async function escape(browser) { /** * Add a FreeText annotation and write some text inside. + * * @param {Object} browser * @param {string} text * @param {Object} box diff --git a/toolkit/components/pictureinpicture/PictureInPicture.sys.mjs b/toolkit/components/pictureinpicture/PictureInPicture.sys.mjs @@ -270,6 +270,7 @@ export var PictureInPicture = { /** * Get the PiP panel for a browser. Create the panel if needed. + * * @param {Browser} browser The current browser * @returns panel The panel element */ @@ -321,6 +322,7 @@ export var PictureInPicture = { /** * Increase the count of PiP windows for a given browser + * * @param browser The browser to increase PiP count in browserWeakMap */ addPiPBrowserToWeakMap(browser) { @@ -362,6 +364,7 @@ export var PictureInPicture = { /** * Decrease the count of PiP windows for a given browser. * If the count becomes 0, we will remove the browser from the WeakMap + * * @param browser The browser to decrease PiP count in browserWeakMap */ removePiPBrowserFromWeakMap(browser) { @@ -496,6 +499,7 @@ export var PictureInPicture = { /** * Update the respect PiPDisabled pref value when the toggle is clicked. + * * @param {Event} event The event from toggling the respect * PiPDisabled in the PiP panel */ @@ -514,6 +518,7 @@ export var PictureInPicture = { /** * Updates the PiP count and PiPDisabled count of eligible PiP videos for a * respective WindowGlobal. + * * @param {BrowsingContext} browsingContext The BrowsingContext with eligible videos * @param {Object} object * pipCount: The number of eligible videos for the respective WindowGlobal @@ -530,6 +535,7 @@ export var PictureInPicture = { /** * A generator function that yeilds a WindowGlobal, it's respective PiP * count, and if any of the videos have PiPDisabled set. + * * @param {Browser} browser The selected browser */ *windowGlobalPipCountGenerator(browser) { @@ -557,6 +563,7 @@ export var PictureInPicture = { /** * Gets the total eligible video count and total PiPDisabled count for a * given browser. + * * @param {Browser} browser The selected browser * @returns Total count of eligible PiP videos for the selected broser */ @@ -577,6 +584,7 @@ export var PictureInPicture = { /** * This function updates the hover text on the urlbar PiP button when we enter or exit PiP + * * @param {Document} document The window document * @param {Element} pipToggle The urlbar PiP button * @param {String} dataL10nId The data l10n id of the string we want to show @@ -593,6 +601,7 @@ export var PictureInPicture = { * Toggles the visibility of the PiP urlbar button. If the total video count * is 1, then we will show the button. If any eligible video has PiPDisabled, * then the button will show. Otherwise the button is hidden. + * * @param {Browser} browser The selected browser */ updateUrlbarToggle(browser) { @@ -630,6 +639,7 @@ export var PictureInPicture = { /** * Open the PiP panel if any video has PiPDisabled, otherwise finds the * correct WindowGlobal to open the eligible PiP video. + * * @param {Event} event Event from clicking the PiP urlbar button */ toggleUrlbar(event) { @@ -689,6 +699,7 @@ export var PictureInPicture = { * Set the toggle for PiPDisabled when the panel is shown. * If the pref is set from about:config, we need to update * the toggle switch in the panel to match the pref. + * * @param {Event} event The panel shown event */ onPipPanelShown(event) { @@ -701,6 +712,7 @@ export var PictureInPicture = { * The button will show when there is more than 1 video and at least 1 video * has PiPDisabled. If we no longer want to respect PiPDisabled then we * need to check if the urlbar button should still be visible. + * * @param {Event} event The panel hidden event */ onPipPanelHidden(event) { @@ -709,6 +721,7 @@ export var PictureInPicture = { /** * Create the PiP panel if needed and toggle the display of the panel + * * @param {Browser} browser The current browser */ togglePipPanel(browser) { @@ -731,6 +744,7 @@ export var PictureInPicture = { /** * Sets the PiP urlbar to an active state. This changes the icon in the * urlbar button to the unpip icon. + * * @param {Window} win The current Window */ setUrlbarPipIconActive(win) { @@ -747,6 +761,7 @@ export var PictureInPicture = { /** * Sets the PiP urlbar to an inactive state. This changes the icon in the * urlbar button to the open pip icon. + * * @param {Window} win The current window */ setUrlbarPipIconInactive(win) { @@ -1490,6 +1505,7 @@ export var PictureInPicture = { * currently has a PiP window. * If the browser has a PiP window we want to keep the browser in an active state because * the browser is still partially visible. + * * @param browser The browser to check if it has a PiP window * @returns true if browser has PiP window else false */ @@ -1521,6 +1537,7 @@ export var PictureInPicture = { /** * This function takes a screen and will return the left, top, width and * height of the screen + * * @param {Screen} screen * The screen we need to get the size and coordinates of * @@ -1593,6 +1610,7 @@ export var PictureInPicture = { /** * Saves position and size of Picture-in-Picture window + * * @param {Window} win The Picture-in-Picture window */ savePosition(win) { @@ -1616,6 +1634,7 @@ export var PictureInPicture = { /** * Load last Picture in Picture location and size + * * @returns {object} * The size and position of the last Picture in Picture window. * diff --git a/toolkit/components/pictureinpicture/content/player.js b/toolkit/components/pictureinpicture/content/player.js @@ -105,6 +105,7 @@ function setIsMutedState(isMuted) { /** * Function to resize and reposition the PiP window + * * @param {Object} rect * An object containing `left`, `top`, `width`, and `height` for the PiP * window @@ -560,6 +561,7 @@ let Player = { * because if we get an input event from the keyboard, onKeyDown will set * this.preventNextInputEvent to true. * This function is called by input events on the scrubber + * * @param {Event} event The input event */ handleScrubbing(event) { @@ -585,6 +587,7 @@ let Player = { /** * This function handles setting the scrubbing state to false and playing * the video if we paused it before scrubbing. + * * @param {Event} event The change event */ handleScrubbingDone(event) { @@ -603,6 +606,7 @@ let Player = { * Set the volume on the video and unmute if the video was muted. * If the volume is changed via the keyboard, onKeyDown will set * this.preventNextInputEvent to true. + * * @param {Number} volume A number between 0 and 1 that represents the volume */ handleAudioScrubbing(volume) { @@ -770,6 +774,7 @@ let Player = { /** * Function to toggle the visibility of the subtitles settings panel + * * @param {Object} options [optional] Object containing options for the function * - forceHide: true to force hide the subtitles settings panel * - isKeyboard: true if the subtitles button was activated using the keyboard diff --git a/toolkit/components/pictureinpicture/tests/browser_aaa_run_first_firstTimePiPToggleEvents.js b/toolkit/components/pictureinpicture/tests/browser_aaa_run_first_firstTimePiPToggleEvents.js @@ -71,6 +71,7 @@ const SECOND_TOGGLE_EXPECTED_EVENTS = [ /** * This function will open the PiP window by clicking the toggle * and then close the PiP window + * * @param browser The current browser * @param videoID The video element id */ @@ -158,6 +159,7 @@ async function openAndClosePipWithToggle(browser, videoID) { /** * This function will open the PiP window by with the context menu + * * @param browser The current browser * @param videoID The video element id */ diff --git a/toolkit/components/pictureinpicture/tests/browser_reversePiP.js b/toolkit/components/pictureinpicture/tests/browser_reversePiP.js @@ -76,6 +76,7 @@ add_task(async () => { async browser => { /** * A helper function used to get the "flipped" attribute of the video's shadowRoot's first child. + * * @param {Element} browser The <xul:browser> hosting the <video> * @param {String} videoID The ID of the video being checked */ @@ -94,6 +95,7 @@ add_task(async () => { /** * A helper function that returns the transform.a of the video being played in PiP. + * * @param {Element} playerBrowser The <xul:browser> of the PiP window */ async function getPiPVideoTransform(playerBrowser) { diff --git a/toolkit/components/pictureinpicture/tests/browser_text_tracks_webvtt_3.js b/toolkit/components/pictureinpicture/tests/browser_text_tracks_webvtt_3.js @@ -5,6 +5,7 @@ /** * Verifies the value of a cue's .line property. + * * @param {Element} browser The <xul:browser> hosting the <video> * @param {String} videoID The ID of the video being checked * @param {Integer} trackIndex The index of the track to be loaded diff --git a/toolkit/components/pictureinpicture/tests/head.js b/toolkit/components/pictureinpicture/tests/head.js @@ -554,6 +554,7 @@ async function getToggleClientRect( /** * This function will hover over the middle of the video and then * hover over the toggle. + * * @param browser The current browser * @param videoID The video element id */ @@ -992,6 +993,7 @@ async function isVideoMuted(browser, videoID) { * First track is the default track to be loaded onto the video. * Once initialization is done, play then pause the requested video. * so that text tracks are loaded. + * * @param {Element} browser The <xul:browser> hosting the <video> * @param {String} videoID The ID of the video being checked * @param {Integer} defaultTrackIndex The index of the track to be loaded, or none if -1 @@ -1035,6 +1037,7 @@ async function prepareVideosAndWebVTTTracks( /** * Plays originating video until the next cue is loaded. * Once the next cue is loaded, pause the video. + * * @param {Element} browser The <xul:browser> hosting the <video> * @param {String} videoID The ID of the video being checked * @param {Integer} textTrackIndex The index of the track to be loaded, or none if -1 @@ -1090,6 +1093,7 @@ function overrideSavedPosition(left, top, width, height) { /** * Function used to filter events when waiting for the correct number * telemetry events. + * * @param {String} expected The expected string or undefined * @param {String} actual The actual string * @returns true if the expected is undefined or if expected matches actual @@ -1103,6 +1107,7 @@ function matches(expected, actual) { /** * Function that waits for the expected number of events aftering filtering. + * * @param {Object} filter An object containing optional filters * { * category: (optional) The category of the event. Ex. "pictureinpicture" diff --git a/toolkit/components/processtools/tests/browser/browser_test_powerMetrics.js b/toolkit/components/processtools/tests/browser/browser_test_powerMetrics.js @@ -5,6 +5,7 @@ /** * Return a web-based URL for a given file based on the testing directory. + * * @param {String} fileName * file that caller wants its web-based url */ diff --git a/toolkit/components/prompts/src/Prompter.sys.mjs b/toolkit/components/prompts/src/Prompter.sys.mjs @@ -25,6 +25,7 @@ export function Prompter() {} /** * Implements nsIPromptService and nsIPromptFactory + * * @class Prompter */ Prompter.prototype = { @@ -65,6 +66,7 @@ Prompter.prototype = { /** * Puts up an alert dialog with an OK button. + * * @param {mozIDOMWindowProxy} domWin - The parent window or null. * @param {String} title - Text to appear in the title of the dialog. * @param {String} text - Text to appear in the body of the dialog. @@ -76,6 +78,7 @@ Prompter.prototype = { /** * Puts up an alert dialog with an OK button. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -106,6 +109,7 @@ Prompter.prototype = { /** * Puts up an alert dialog with an OK button and a labeled checkbox. + * * @param {mozIDOMWindowProxy} domWin - The parent window or null. * @param {String} title - Text to appear in the title of the dialog. * @param {String} text - Text to appear in the body of the dialog. @@ -121,6 +125,7 @@ Prompter.prototype = { /** * Puts up an alert dialog with an OK button and a labeled checkbox. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -139,6 +144,7 @@ Prompter.prototype = { /** * Puts up an alert dialog with an OK button and a labeled checkbox. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -157,6 +163,7 @@ Prompter.prototype = { /** * Puts up a dialog with OK and Cancel buttons. + * * @param {mozIDOMWindowProxy} domWin - The parent window or null. * @param {String} title - Text to appear in the title of the dialog. * @param {String} text - Text to appear in the body of the dialog. @@ -169,6 +176,7 @@ Prompter.prototype = { /** * Puts up a dialog with OK and Cancel buttons. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -184,6 +192,7 @@ Prompter.prototype = { /** * Puts up a dialog with OK and Cancel buttons. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -200,6 +209,7 @@ Prompter.prototype = { /** * Puts up a dialog with OK and Cancel buttons and a labeled checkbox. + * * @param {mozIDOMWindowProxy} domWin - The parent window or null. * @param {String} title - Text to appear in the title of the dialog. * @param {String} text - Text to appear in the body of the dialog. @@ -215,6 +225,7 @@ Prompter.prototype = { /** * Puts up a dialog with OK and Cancel buttons and a labeled checkbox. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -234,6 +245,7 @@ Prompter.prototype = { /** * Puts up a dialog with OK and Cancel buttons and a labeled checkbox. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -310,6 +322,7 @@ Prompter.prototype = { /** * Puts up a dialog with up to 3 buttons and an optional, labeled checkbox. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -334,6 +347,7 @@ Prompter.prototype = { /** * Puts up a dialog with up to 3 buttons and an optional, labeled checkbox. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -357,6 +371,7 @@ Prompter.prototype = { /** * Puts up a dialog with an edit field and an optional, labeled checkbox. + * * @param {mozIDOMWindowProxy} domWin - The parent window or null. * @param {String} title - Text to appear in the title of the dialog. * @param {String} text - Text to appear in the body of the dialog. @@ -379,6 +394,7 @@ Prompter.prototype = { /** * Puts up a dialog with an edit field and an optional, labeled checkbox. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -404,6 +420,7 @@ Prompter.prototype = { /** * Puts up a dialog with an edit field and an optional, labeled checkbox. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -424,6 +441,7 @@ Prompter.prototype = { /** * Puts up a dialog with an edit field and a password field. + * * @param {mozIDOMWindowProxy} domWin - The parent window or null. * @param {String} title - Text to appear in the title of the dialog. * @param {String} text - Text to appear in the body of the dialog. @@ -445,6 +463,7 @@ Prompter.prototype = { /** * Puts up a dialog with an edit field and a password field. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -469,6 +488,7 @@ Prompter.prototype = { /** * Puts up a dialog with an edit field and a password field. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -487,6 +507,7 @@ Prompter.prototype = { /** * Puts up a dialog with a password field. + * * @param {mozIDOMWindowProxy} domWin - The parent window or null. * @param {String} title - Text to appear in the title of the dialog. * @param {String} text - Text to appear in the body of the dialog. @@ -508,6 +529,7 @@ Prompter.prototype = { /** * Puts up a dialog with a password field. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -527,6 +549,7 @@ Prompter.prototype = { /** * Puts up a dialog with a password field. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -545,6 +568,7 @@ Prompter.prototype = { /** * Puts up a dialog box which has a list box of strings from which the user * may make a single selection. + * * @param {mozIDOMWindowProxy} domWin - The parent window or null. * @param {String} title - Text to appear in the title of the dialog. * @param {String} text - Text to appear in the body of the dialog. @@ -561,6 +585,7 @@ Prompter.prototype = { /** * Puts up a dialog box which has a list box of strings from which the user * may make a single selection. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -580,6 +605,7 @@ Prompter.prototype = { /** * Puts up a dialog box which has a list box of strings from which the user * may make a single selection. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -598,6 +624,7 @@ Prompter.prototype = { /** * Requests a username and a password. Shows a dialog with username and * password field, depending on flags also a domain field. + * * @param {mozIDOMWindowProxy} domWin - The parent window or null. * @param {nsIChannel} channel - The channel that requires authentication. * @param {Number} level - Security level of the credential transmission. @@ -617,6 +644,7 @@ Prompter.prototype = { /** * Requests a username and a password. Shows a dialog with username and * password field, depending on flags also a domain field. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -639,6 +667,7 @@ Prompter.prototype = { /** * Requests a username and a password. Shows a dialog with username and * password field, depending on flags also a domain field. + * * @param {BrowsingContext} browsingContext - The browsing context the * prompt should be opened for. * @param {Number} modalType - The modal type of the prompt. @@ -1049,6 +1078,7 @@ class ModalPrompter { /** * Synchronous wrapper around {@link ModalPrompter#openPrompt} + * * @param {Object} args Prompt arguments. When prompt has been closed, they are updated to reflect the result state. */ openPromptSync(args) { @@ -1247,6 +1277,7 @@ class ModalPrompter { * We try and find a window to use as the parent, but don't consider if that * is visible before showing the prompt. parentWindow may still be null if * there are _no_ windows open. + * * @param {Window} [parentWindow] - The parent window for the prompt, may be * null. * @param {Object} args - Prompt options and return values. @@ -1280,6 +1311,7 @@ class ModalPrompter { /** * Calls async prompt method and optionally runs promise chained task on * result data. Converts result data to nsIPropertyBag. + * * @param {Object} args - Prompt arguments. * @param {Function} [task] - Function which is called with the modified * prompt args object once the prompt has been closed. Must return a diff --git a/toolkit/components/prompts/test/PromptTestUtils.sys.mjs b/toolkit/components/prompts/test/PromptTestUtils.sys.mjs @@ -13,6 +13,7 @@ export let PromptTestUtils = { /** * Wait for a prompt from nsIPrompt or nsIPromptsService, interact with it and * click the specified button to close it. + * * @param {Browser|Window} [parent] - Parent of the prompt. This can be * either the parent window or the browser. For tab prompts, if given a * window, the currently selected browser in that window will be used. @@ -28,6 +29,7 @@ export let PromptTestUtils = { /** * Interact with an existing prompt and close it. + * * @param {Dialog} dialog - The dialog instance associated with the prompt. * @param {Object} [actions] - Options on how to interact with the * prompt and how to close it. @@ -89,6 +91,7 @@ export let PromptTestUtils = { /** * Wait for a prompt from nsIPrompt or nsIPromptsService to open. + * * @param {Browser|Window} [parent] - Parent of the prompt. This can be either * the parent window or the browser. For tab prompts, if given a window, the * currently selected browser in that window will be used. diff --git a/toolkit/components/prompts/test/prompt_common.js b/toolkit/components/prompts/test/prompt_common.js @@ -2,6 +2,7 @@ const { Cc, Ci, Cu: ChromeUtils } = SpecialPowers; /** * Converts a property bag to object. + * * @param {nsIPropertyBag} bag - The property bag to convert * @returns {Object} - The object representation of the nsIPropertyBag */ @@ -169,6 +170,7 @@ function onloadPromiseFor(id) { * This is useful when the action doesn't depend on which prompt is shown and you * are expecting multiple prompts at once in an indeterminate order. * If you know the state of the prompt you expect you should use `handlePrompt` instead. + * * @param {object} action defining how to handle the prompt * @returns {Promise} resolving with the prompt state. */ diff --git a/toolkit/components/taskscheduler/TaskSchedulerWinImpl.sys.mjs b/toolkit/components/taskscheduler/TaskSchedulerWinImpl.sys.mjs @@ -237,7 +237,6 @@ export var WinImpl = { * * copied from quoteString() in toolkit/modules/subproces/subprocess_worker_win.js * - * * @see https://msdn.microsoft.com/en-us/library/17w5ykft(v=vs.85).aspx * * @param {string} str diff --git a/toolkit/components/telemetry/app/TelemetryArchive.sys.mjs b/toolkit/components/telemetry/app/TelemetryArchive.sys.mjs @@ -55,6 +55,7 @@ export var TelemetryArchive = { /** * Checks if pings can be archived. Some products (e.g. Thunderbird) might not want * to do that. + * * @return {Boolean} True if pings should be archived, false otherwise. */ function shouldArchivePings() { diff --git a/toolkit/components/telemetry/app/TelemetryControllerBase.sys.mjs b/toolkit/components/telemetry/app/TelemetryControllerBase.sys.mjs @@ -113,6 +113,7 @@ export var TelemetryControllerBase = Object.freeze({ /** * Perform telemetry initialization for either chrome or content process. + * * @return {Boolean} True if Telemetry is allowed to record at least base (FHR) data, * false otherwise. */ diff --git a/toolkit/components/telemetry/app/TelemetryControllerContent.sys.mjs b/toolkit/components/telemetry/app/TelemetryControllerContent.sys.mjs @@ -40,6 +40,7 @@ var Impl = { /** * This triggers basic telemetry initialization for content processes. + * * @param {Boolean} [testing=false] True if we are in test mode, false otherwise. */ setupContentTelemetry(testing = false) { diff --git a/toolkit/components/telemetry/app/TelemetryControllerParent.sys.mjs b/toolkit/components/telemetry/app/TelemetryControllerParent.sys.mjs @@ -255,7 +255,6 @@ export var TelemetryController = Object.freeze({ * should be included in the orderly shutdown process. * * @param {Function} aFnShutdown The function to call as telemetry shuts down. - */ registerSyncPingShutdown(afnShutdown) { Impl.registerSyncPingShutdown(afnShutdown); @@ -264,6 +263,7 @@ export var TelemetryController = Object.freeze({ /** * Allows waiting for TelemetryControllers delayed initialization to complete. * The returned promise is guaranteed to resolve before TelemetryController is shutting down. + * * @return {Promise} Resolved when delayed TelemetryController initialization completed. */ promiseInitialized() { @@ -273,6 +273,7 @@ export var TelemetryController = Object.freeze({ /** * Allows to trigger TelemetryControllers delayed initialization now and waiting for its completion. * The returned promise is guaranteed to resolve before TelemetryController is shutting down. + * * @return {Promise} Resolved when delayed TelemetryController initialization completed. */ ensureInitialized() { @@ -1135,6 +1136,7 @@ var Impl = { /** * Allows waiting for TelemetryControllers delayed initialization to complete. * This will complete before TelemetryController is shutting down. + * * @return {Promise} Resolved when delayed TelemetryController initialization completed. */ promiseInitialized() { @@ -1144,6 +1146,7 @@ var Impl = { /** * Allows to trigger TelemetryControllers delayed initialization now and waiting for its completion. * This will complete before TelemetryController is shutting down. + * * @return {Promise} Resolved when delayed TelemetryController initialization completed. */ ensureInitialized() { diff --git a/toolkit/components/telemetry/app/TelemetryEnvironment.sys.mjs b/toolkit/components/telemetry/app/TelemetryEnvironment.sys.mjs @@ -400,6 +400,7 @@ const SERVICES_INFO_CHANGE_TOPIC = "sync-ui-state:update"; /** * Get the current browser locale. + * * @return a string with the locale or null on failure. */ function getBrowserLocale() { @@ -412,6 +413,7 @@ function getBrowserLocale() { /** * Get the current OS locale. + * * @return a string with the OS locale or null on failure. */ function getSystemLocale() { @@ -426,6 +428,7 @@ function getSystemLocale() { /** * Get the current OS locales. + * * @return an array of strings with the OS locales or null on failure. */ function getSystemLocales() { @@ -440,6 +443,7 @@ function getSystemLocales() { /** * Get the current OS regional preference locales. + * * @return an array of strings with the OS regional preference locales or null on failure. */ function getRegionalPrefsLocales() { @@ -645,6 +649,7 @@ EnvironmentCache.prototype = { /** * The current environment data. The returned data is cloned to avoid * unexpected sharing or mutation. + * * @returns object */ get currentEnvironment() { @@ -653,6 +658,7 @@ EnvironmentCache.prototype = { /** * Wait for the current enviroment to be fully initialized. + * * @returns Promise<object> */ onInitialized() { @@ -730,6 +736,7 @@ EnvironmentCache.prototype = { /** * Register a listener for environment changes. + * * @param name The name of the listener. If a new listener is registered * with the same name, the old listener will be replaced. * @param listener function(reason, oldEnvironment) - Will receive a reason for @@ -747,6 +754,7 @@ EnvironmentCache.prototype = { /** * Unregister from listening to environment changes. * It's fine to call this on an unitialized TelemetryEnvironment. + * * @param name The name of the listener to remove. */ unregisterChangeListener(name) { @@ -854,6 +862,7 @@ EnvironmentCache.prototype = { /** * Only used in tests, set the preferences to watch. + * * @param aPreferences A map of preferences names and their recording policy. */ _watchPreferences(aPreferences) { @@ -885,6 +894,7 @@ EnvironmentCache.prototype = { /** * Get the value of a preference given the preference name and the policy. + * * @param pref Name of the preference. * @param what Policy of the preference. * @@ -1158,6 +1168,7 @@ EnvironmentCache.prototype = { /** * Get the build data in object form. + * * @return Object containing the build data. */ _getBuild() { @@ -1182,6 +1193,7 @@ EnvironmentCache.prototype = { /** * Determine if we're the default browser. + * * @returns null on error, true if we are the default browser, or false otherwise. */ _isDefaultBrowser() { @@ -1346,6 +1358,7 @@ EnvironmentCache.prototype = { /** * Update the cached profile data. + * * @returns Promise<> resolved when the I/O is complete. */ async _updateProfile() { @@ -1384,6 +1397,7 @@ EnvironmentCache.prototype = { /** * Load the attribution data object and updates the environment. + * * @returns Promise<> resolved when the I/O is complete. */ async _loadAttributionAsync() { @@ -1478,6 +1492,7 @@ EnvironmentCache.prototype = { /** * Get i18n data about the system. + * * @return A promise of completion. */ async _loadIntlData() { @@ -1527,6 +1542,7 @@ EnvironmentCache.prototype = { /** * Get the partner data in object form. + * * @return Object containing the partner data. */ _getPartner() { @@ -1563,6 +1579,7 @@ EnvironmentCache.prototype = { _cpuData: null, /** * Get the CPU information. + * * @return Object containing the CPU information data. */ _getCPUData() { @@ -1609,6 +1626,7 @@ EnvironmentCache.prototype = { _processData: null, /** * Get the process information. + * * @return Object containing the process information data. */ _getProcessData() { @@ -1621,6 +1639,7 @@ EnvironmentCache.prototype = { _osData: null, /** * Get the OS information. + * * @return Object containing the OS data. */ _getOSData() { @@ -1687,6 +1706,7 @@ EnvironmentCache.prototype = { _hddData: null, /** * Get the HDD information. + * * @return Object containing the HDD data. */ _getHDDData() { @@ -1699,6 +1719,7 @@ EnvironmentCache.prototype = { /** * Get registered security product information. + * * @return Object containing the security product data */ _getSecurityAppData() { @@ -1727,6 +1748,7 @@ EnvironmentCache.prototype = { /** * Get the GFX information. + * * @return Object containing the GFX data. */ _getGFXData() { @@ -1813,6 +1835,7 @@ EnvironmentCache.prototype = { /** * Get the system data in object form. + * * @return Object containing the system data. */ _getSystem() { diff --git a/toolkit/components/telemetry/app/TelemetryReportingPolicy.sys.mjs b/toolkit/components/telemetry/app/TelemetryReportingPolicy.sys.mjs @@ -277,6 +277,7 @@ var TelemetryReportingPolicyImpl = { /** * Get the date the policy was notified. + * * @return {Object} A date object or null on errors. */ get dataSubmissionPolicyNotifiedDate() { @@ -316,6 +317,7 @@ var TelemetryReportingPolicyImpl = { /** * Set the date the policy was notified. + * * @param {Object} aDate A valid date object. */ set dataSubmissionPolicyNotifiedDate(aDate) { @@ -339,6 +341,7 @@ var TelemetryReportingPolicyImpl = { /** * Get the date the terms of use were accepted. + * * @return {Object} A date object or null on errors. */ get termsOfUseAcceptedDate() { @@ -373,6 +376,7 @@ var TelemetryReportingPolicyImpl = { /** * Set the date the policy was notified. + * * @param {Object} aDate A valid date object. */ set termsOfUseAcceptedDate(aDate) { @@ -494,6 +498,7 @@ var TelemetryReportingPolicyImpl = { /** * Checks to see if the user has been notified about data submission + * * @return {Bool} True if user has been notified and the notification is still valid, * false otherwise. */ @@ -517,6 +522,7 @@ var TelemetryReportingPolicyImpl = { /** * Checks to see if the user has accepted the current terms of use + * * @return {Bool} True if user has accepted and the acceptance is still valid, * false otherwise. */ @@ -778,6 +784,7 @@ var TelemetryReportingPolicyImpl = { * Otherwise, for upload to be allowed from a data reporting standpoint, the * user should not qualify to see the legacy policy notification flow and also * not qualify to see the Terms of Use acceptance flow. + * * @return {Boolean} True if we are allowed to upload data, false otherwise. */ canUpload() { diff --git a/toolkit/components/telemetry/app/TelemetryScheduler.sys.mjs b/toolkit/components/telemetry/app/TelemetryScheduler.sys.mjs @@ -198,6 +198,7 @@ export var TelemetryScheduler = { /** * Checks if we can send a daily ping or not. + * * @param {Object} nowDate A date object. * @return {Boolean} True if we can send the daily ping, false otherwise. */ @@ -223,6 +224,7 @@ export var TelemetryScheduler = { /** * Checks if we can send a regular ping or not. + * * @param {Object} nowDate A date object. * @return {Boolean} True if we can send the regular pings, false otherwise. */ @@ -239,6 +241,7 @@ export var TelemetryScheduler = { /** * An helper function to save an aborted-session ping. + * * @param {Number} now The current time, in milliseconds. * @param {Object} [competingPayload=null] If we are coalescing the daily and the * aborted-session pings, this is the payload for the former. Note @@ -303,6 +306,7 @@ export var TelemetryScheduler = { /** * Performs a scheduler tick. This function manages Telemetry recurring operations. + * * @param {Boolean} [dispatchOnIdle=false] If true, the tick is dispatched in the * next idle cycle of the main thread. * @return {Promise} A promise, only used when testing, resolved when the scheduled @@ -354,6 +358,7 @@ export var TelemetryScheduler = { /** * Implements the scheduler logic. + * * @return {Promise} Resolved when the scheduled task completes. Only used in tests. */ _schedulerTickLogic() { diff --git a/toolkit/components/telemetry/app/TelemetrySend.sys.mjs b/toolkit/components/telemetry/app/TelemetrySend.sys.mjs @@ -115,6 +115,7 @@ function isV4PingFormat(aPing) { /** * Check if the provided ping is a deletion-request ping. + * * @param {Object} aPing The ping to check. * @return {Boolean} True if the ping is a deletion-request ping, false otherwise. */ @@ -124,6 +125,7 @@ function isDeletionRequestPing(aPing) { /** * Generate a string suitable for including in a profiler marker as a ping description. + * * @param {Object} aPing The ping to describe. */ function getPingMarkerString(aPing) { @@ -137,6 +139,7 @@ function getPingMarkerString(aPing) { /** * Save the provided ping as a pending ping. + * * @param {Object} aPing The ping to save. * @return {Promise} A promise resolved when the ping is saved. */ @@ -879,6 +882,7 @@ export var TelemetrySendImpl = { /** * Discard old pings from the pending pings and detect overdue ones. + * * @return {Boolean} True if we have overdue pings, false otherwise. */ async _checkPendingPings() { @@ -1575,6 +1579,7 @@ export var TelemetrySendImpl = { /** * Check if sending is temporarily disabled. + * * @return {Boolean} True if we can send pings to the server right now, false if * sending is temporarily disabled. */ @@ -1635,6 +1640,7 @@ export var TelemetrySendImpl = { /** * Return a promise that allows to wait on pending pings. + * * @return {Object<Promise>} A promise resolved when all the pending pings promises * are resolved. */ diff --git a/toolkit/components/telemetry/app/TelemetryStorage.sys.mjs b/toolkit/components/telemetry/app/TelemetryStorage.sys.mjs @@ -260,6 +260,7 @@ export var TelemetryStorage = { /** * Saves session data to disk. + * * @param {Object} sessionData The session data. * @return {Promise} Resolved when the data was saved. */ @@ -269,6 +270,7 @@ export var TelemetryStorage = { /** * Loads session data from a session data file. + * * @return {Promise<object>} Resolved with the session data in object form. */ loadSessionData() { @@ -416,6 +418,7 @@ export var TelemetryStorage = { /** * Loads a ping file. + * * @param {String} aFilePath The path of the ping file. * @return {Promise<Object>} A promise resolved with the ping content or rejected if the * ping contains invalid data. @@ -427,6 +430,7 @@ export var TelemetryStorage = { /** * Remove FHR database files. This is temporary and will be dropped in * the future. + * * @return {Promise} Resolved when the database files are deleted. */ removeFHRDatabase() { @@ -435,6 +439,7 @@ export var TelemetryStorage = { /** * Only used in tests, builds an archived ping path from the ping metadata. + * * @param {String} aPingId The ping id. * @param {Object} aDate The ping creation date. * @param {String} aType The ping type. @@ -503,6 +508,7 @@ SaveSerializer.prototype = { /** * Make sure to flush all the pending operations. + * * @return {Promise} A promise resolved when all the pending operations have completed. */ flushTasks() { @@ -800,6 +806,7 @@ var TelemetryStorageImpl = { /** * Loads session data from the session data file. + * * @return {Promise<Object>} A promise resolved with an object on success, * with null otherwise. */ @@ -879,6 +886,7 @@ var TelemetryStorageImpl = { /** * Removes pings which are too old from the pings archive. + * * @return {Promise} Resolved when the ping age check is complete. */ async _purgeOldPings() { @@ -983,6 +991,7 @@ var TelemetryStorageImpl = { /** * Enforce a disk quota for the pings archive. + * * @return {Promise} Resolved when the quota check is complete. */ async _enforceArchiveQuota() { @@ -1164,6 +1173,7 @@ var TelemetryStorageImpl = { /** * Enforce a disk quota for the pending pings. + * * @return {Promise} Resolved when the quota check is complete. */ async _enforcePendingPingsQuota() { @@ -1558,6 +1568,7 @@ var TelemetryStorageImpl = { /** * Return a promise that allows to wait on pending pings being saved. + * * @return {Object<Promise>} A promise resolved when all the pending pings save promises * are resolved. */ @@ -1856,6 +1867,7 @@ var TelemetryStorageImpl = { /** * Loads a ping file. + * * @param {String} aFilePath The path of the ping file. * @param {Boolean} [aCompressed=false] If |true|, expects the file to be compressed using lz4. * @return {Promise<Object>} A promise resolved with the ping content or rejected if the @@ -2040,6 +2052,7 @@ var TelemetryStorageImpl = { /** * Remove FHR database files. This is temporary and will be dropped in * the future. + * * @return {Promise} Resolved when the database files are deleted. */ async removeFHRDatabase() { @@ -2107,6 +2120,7 @@ function getPingDirectory() { /** * Build the path to the archived ping. + * * @param {String} aPingId The ping id. * @param {Object} aDate The ping creation date. * @param {String} aType The ping type. @@ -2127,6 +2141,7 @@ function getArchivedPingPath(aPingId, aDate, aType) { /** * Get the size of the ping file on the disk. + * * @return {Integer} The file size, in bytes, of the ping file or 0 on errors. */ var getArchivedPingSize = async function (aPingId, aDate, aType) { @@ -2145,6 +2160,7 @@ var getArchivedPingSize = async function (aPingId, aDate, aType) { /** * Get the size of the pending ping file on the disk. + * * @return {Integer} The file size, in bytes, of the ping file or 0 on errors. */ var getPendingPingSize = async function (aPingId) { @@ -2159,6 +2175,7 @@ var getPendingPingSize = async function (aPingId) { /** * Check if a directory name is in the "YYYY-MM" format. + * * @param {String} aDirName The name of the pings archive directory. * @return {Boolean} True if the directory name is in the right format, false otherwise. */ @@ -2169,6 +2186,7 @@ function isValidArchiveDir(aDirName) { /** * Gets a date object from an archive directory name. + * * @param {String} aDirName The name of the pings archive directory. Must be in the YYYY-MM * format. * @return {Object} A Date object or null if the dir name is not valid. diff --git a/toolkit/components/telemetry/app/TelemetryUtils.sys.mjs b/toolkit/components/telemetry/app/TelemetryUtils.sys.mjs @@ -156,6 +156,7 @@ export var TelemetryUtils = { /** * Check if the difference between the times is within the provided tolerance. + * * @param {Number} t1 A time in milliseconds. * @param {Number} t2 A time in milliseconds. * @param {Number} tolerance The tolerance, in milliseconds. @@ -168,6 +169,7 @@ export var TelemetryUtils = { /** * Get the next midnight for a date. + * * @param {Object} date The date object to check. * @return {Object} The Date object representing the next midnight. */ @@ -179,6 +181,7 @@ export var TelemetryUtils = { /** * Get the midnight which is closer to the provided date. + * * @param {Object} date The date object to check. * @param {Number} tolerance The tolerance within we find the closest midnight. * @return {Object} The Date object representing the closes midnight, or null if midnight @@ -207,6 +210,7 @@ export var TelemetryUtils = { /** * Find how many months passed between two dates. + * * @param {Object} aStartDate The starting date. * @param {Object} aEndDate The ending date. * @return {Integer} The number of months between the two dates. @@ -222,6 +226,7 @@ export var TelemetryUtils = { /** * Date.toISOString() gives us UTC times, this gives us local times in * the ISO date format. See http://www.w3.org/TR/NOTE-datetime + * * @param {Object} date The input date. * @return {String} The local time ISO string. */ diff --git a/toolkit/components/telemetry/pings/HealthPing.sys.mjs b/toolkit/components/telemetry/pings/HealthPing.sys.mjs @@ -79,6 +79,7 @@ export var TelemetryHealthPing = { /** * Record a failure to send a ping out. + * * @param {String} failureType The type of failure (e.g. "timeout", ...). * @returns {Promise} Test-only, resolved when the ping is stored or sent. */ @@ -88,6 +89,7 @@ export var TelemetryHealthPing = { /** * Record that a ping was discarded and its type. + * * @param {String} pingType The type of discarded ping (e.g. "main", ...). * @returns {Promise} Test-only, resolved when the ping is stored or sent. */ @@ -97,6 +99,7 @@ export var TelemetryHealthPing = { /** * Assemble payload. + * * @param {String} reason A string indicating the triggering reason (e.g. "immediate", "delayed", "shutdown"). * @returns {Object} The assembled payload. */ @@ -120,6 +123,7 @@ export var TelemetryHealthPing = { /** * Sort input dictionary descending by value. + * * @param {Object} failures A dictionary of failures subtype and count. * @returns {Object} Sorted failures by value. */ @@ -139,6 +143,7 @@ export var TelemetryHealthPing = { /** * Assemble the failure information and submit it. + * * @param {String} reason A string indicating the triggering reason (e.g. "immediate", "delayed", "shutdown"). * @returns {Promise} Test-only promise that resolves when the ping was stored or sent (if any). */ @@ -175,6 +180,7 @@ export var TelemetryHealthPing = { /** * Accumulate failure information and trigger a ping immediately or on timeout. + * * @param {String} failureType The type of failure (e.g. "timeout", ...). * @param {String} failureSubType The subtype of failure (e.g. ping type, ...). * @returns {Promise} Test-only, resolved when the ping is stored or sent. @@ -234,6 +240,7 @@ export var TelemetryHealthPing = { /** * Submit latest ping on shutdown. + * * @returns {Promise} Test-only, resolved when the ping is stored or sent. */ shutdown() { diff --git a/toolkit/components/telemetry/pings/TelemetrySession.sys.mjs b/toolkit/components/telemetry/pings/TelemetrySession.sys.mjs @@ -71,6 +71,7 @@ export var Policy = { /** * Get the ping type based on the payload. + * * @param {Object} aPayload The ping payload. * @return {String} A string representing the ping type. */ @@ -161,6 +162,7 @@ export var TelemetrySession = Object.freeze({ }, /** * Returns the current telemetry payload. + * * @param reason Optional, the reason to trigger the payload. * @param clearSubsession Optional, whether to clear subsession specific data. * @returns Object @@ -254,6 +256,7 @@ export var TelemetrySession = Object.freeze({ /** * Does the "heavy" Telemetry initialization later on, so we * don't impact startup performance. + * * @return {Promise} Resolved when the initialization completes. */ delayedInit() { @@ -267,6 +270,7 @@ export var TelemetrySession = Object.freeze({ }, /** * Marks the "new-profile" ping as sent in the telemetry state file. + * * @return {Promise} A promise resolved when the new telemetry state is saved to disk. */ markNewProfilePingSent() { @@ -366,6 +370,7 @@ var Impl = { /** * Gets a series of simple measurements (counters). At the moment, this * only returns startup data from nsIAppStartup.getStartupInfo(). + * * @param {Boolean} isSubsession True if this is a subsession, false otherwise. * @param {Boolean} clearSubsession True if a new subsession is being started, false otherwise. * @@ -475,6 +480,7 @@ var Impl = { /** * Get a snapshot of the scalars and clear them. + * * @param {subsession} If true, then we collect the data for a subsession. * @param {clearSubsession} If true, we need to clear the subsession. * @param {keyed} Take a snapshot of keyed or non keyed scalars. @@ -877,6 +883,7 @@ var Impl = { /** * Does the "heavy" Telemetry initialization later on, so we * don't impact startup performance. + * * @return {Promise} Resolved when the initialization completes. */ delayedInit() { @@ -1260,6 +1267,7 @@ var Impl = { /** * Gather and send a daily ping. + * * @return {Promise} Resolved when the ping is sent. */ _sendDailyPing() { @@ -1293,6 +1301,7 @@ var Impl = { /** * Loads session data from the session data file. + * * @return {Promise<object>} A promise which is resolved with an object when * loading has completed, with null otherwise. */ @@ -1391,6 +1400,7 @@ var Impl = { /** * Saves the aborted session ping to disk. + * * @param {Object} [aProvidedPayload=null] A payload object to be used as an aborted * session ping. The reason of this payload is changed to aborted-session. * If not provided, a new payload is gathered. diff --git a/toolkit/components/telemetry/tests/unit/head.js b/toolkit/components/telemetry/tests/unit/head.js @@ -141,6 +141,7 @@ const PingServer = { /** * Decode the payload of an HTTP request into a ping. + * * @param {Object} request The data representing an HTTP request (nsIHttpRequest). * @return {Object} The decoded ping payload. */ diff --git a/toolkit/components/telemetry/tests/unit/test_PingAPI.js b/toolkit/components/telemetry/tests/unit/test_PingAPI.js @@ -19,6 +19,7 @@ ChromeUtils.defineLazyGetter(this, "gPingsArchivePath", function () { /** * Fakes the archive storage quota. + * * @param {Integer} aArchiveQuota The new quota, in bytes. */ function fakeStorageQuota(aArchiveQuota) { diff --git a/toolkit/components/telemetry/tests/unit/test_TelemetrySendOldPings.js b/toolkit/components/telemetry/tests/unit/test_TelemetrySendOldPings.js @@ -55,6 +55,7 @@ var createSavedPings = async function (aPingInfos) { /** * Fakes the pending pings storage quota. + * * @param {Integer} aPendingQuota The new quota, in bytes. */ function fakePendingPingsQuota(aPendingQuota) { diff --git a/toolkit/components/thumbnails/PageThumbs.sys.mjs b/toolkit/components/thumbnails/PageThumbs.sys.mjs @@ -146,6 +146,7 @@ export var PageThumbs = { /** * Gets the thumbnail image's url for a given web page's url. + * * @param aUrl The web page's url that is depicted in the thumbnail. * @return The thumbnail image's url. */ @@ -204,6 +205,7 @@ export var PageThumbs = { * Note, when dealing with remote content, this api draws into the passed * canvas asynchronously. Pass aCallback to receive an async callback after * canvas painting has completed. + * * @param aBrowser The browser to capture a thumbnail from. * @param aCanvas The canvas to draw to. The thumbnail will be scaled to match * the dimensions of this canvas. If callers pass a 0x0 canvas, the canvas @@ -412,6 +414,7 @@ export var PageThumbs = { /** * Captures a thumbnail for the given browser and stores it to the cache. + * * @param aBrowser The browser to capture a thumbnail for. */ captureAndStore: async function PageThumbs_captureAndStore(aBrowser) { @@ -607,6 +610,7 @@ export var PageThumbs = { /** * Unregister an expiration filter. + * * @param aFilter A filter that was previously passed to addExpirationFilter. */ removeExpirationFilter: function PageThumbs_removeExpirationFilter(aFilter) { @@ -615,6 +619,7 @@ export var PageThumbs = { /** * Creates a new hidden canvas element. + * * @param aWindow The document of this window will be used to create the * canvas. If not given, the hidden window will be used. * @return The newly created canvas. diff --git a/toolkit/components/thumbnails/test/head.js b/toolkit/components/thumbnails/test/head.js @@ -36,6 +36,7 @@ registerCleanupFunction(function () { /** * Captures a screenshot for the currently selected tab, stores it in the cache, * retrieves it from the cache and compares pixel color values. + * * @param aRed The red component's intensity. * @param aGreen The green component's intensity. * @param aBlue The blue component's intensity. @@ -57,6 +58,7 @@ async function captureAndCheckColor(aRed, aGreen, aBlue, aMessage) { * For a given URL, loads the corresponding thumbnail * to a canvas and passes its image data to the callback. * Note, not compat with e10s! + * * @param aURL The url associated with the thumbnail. * @returns Promise */ @@ -82,6 +84,7 @@ async function retrieveImageDataForURL(aURL) { /** * Returns the file of the thumbnail with the given URL. + * * @param aURL The URL of the thumbnail. */ function thumbnailFile(aURL) { @@ -90,6 +93,7 @@ function thumbnailFile(aURL) { /** * Checks if a thumbnail for the given URL exists. + * * @param aURL The url associated to the thumbnail. */ function thumbnailExists(aURL) { @@ -99,6 +103,7 @@ function thumbnailExists(aURL) { /** * Removes the thumbnail for the given URL. + * * @param aURL The URL associated with the thumbnail. */ function removeThumbnail(aURL) { diff --git a/toolkit/components/timermanager/UpdateTimerManager.sys.mjs b/toolkit/components/timermanager/UpdateTimerManager.sys.mjs @@ -22,6 +22,7 @@ XPCOMUtils.defineLazyPreferenceGetter( /** * Logs a string to the error console. + * * @param string * The string to write to the error console. * @param bool @@ -37,6 +38,7 @@ function LOG(string, alwaysLog = false) { /** * A manager for timers. Manages timers that fire over long periods of time * (e.g. days, weeks, months). + * * @constructor */ export function TimerManager() { diff --git a/toolkit/components/url-classifier/UrlClassifierLib.sys.mjs b/toolkit/components/url-classifier/UrlClassifierLib.sys.mjs @@ -136,6 +136,7 @@ RequestBackoff.prototype.noteServerResponse = function (status) { /** * We consider 302, 303, 307, 4xx, and 5xx http responses to be errors. + * * @param status Number http status * @return Boolean true if we consider this http status an error */ diff --git a/toolkit/components/url-classifier/UrlClassifierListManager.sys.mjs b/toolkit/components/url-classifier/UrlClassifierListManager.sys.mjs @@ -87,6 +87,7 @@ class PROT_ListManager { /** * Register a new table table + * * @param tableName - the name of the table * @param updateUrl - the url for updating the table * @param gethashUrl - the url for fetching hash completions @@ -200,6 +201,7 @@ class PROT_ListManager { /** * Returns true if any table associated with the updateUrl requires updates. + * * @param updateUrl - the updateUrl */ #updatesNeeded(updateUrl) { @@ -469,6 +471,7 @@ class PROT_ListManager { /** * Method that fires the actual HTTP update request. * First we reset any tables that have disappeared. + * * @param tableData List of table data already in the database, in the form * tablename;<chunk ranges>\n */ @@ -697,6 +700,7 @@ class PROT_ListManager { /** * Callback function if the update request succeeded. + * * @param waitForUpdate String The number of seconds that the client should * wait before requesting again. */ @@ -791,6 +795,7 @@ class PROT_ListManager { /** * Callback function if the update request succeeded. + * * @param result String The error code of the failure */ #updateError(table, updateUrl, result) { @@ -810,6 +815,7 @@ class PROT_ListManager { /** * Callback function when the download failed + * * @param status String http status or an empty string if connection refused. */ #downloadError(table, updateUrl, status) { diff --git a/toolkit/components/url-classifier/tests/UrlClassifierTestUtils.sys.mjs b/toolkit/components/url-classifier/tests/UrlClassifierTestUtils.sys.mjs @@ -372,6 +372,7 @@ export var UrlClassifierTestUtils = { /** * Handle the next "urlclassifier-before-block-channel" event. + * * @param {Object} options * @param {String} [options.filterOrigin] - Only handle event for channels * with matching origin. diff --git a/toolkit/components/url-classifier/tests/performance/perftest_exceptionListLookup.js b/toolkit/components/url-classifier/tests/performance/perftest_exceptionListLookup.js @@ -28,6 +28,7 @@ var perfMetadata = { /** * Convert a JS object from RemoteSettings to an nsIUrlClassifierExceptionListEntry. + * * @param {Object} rsObject - The JS object from RemoteSettings to convert. * @returns {nsIUrlClassifierExceptionListEntry} The converted nsIUrlClassifierExceptionListEntry. */ diff --git a/toolkit/components/url-classifier/tests/unit/test_urlClassifierExceptionList.js b/toolkit/components/url-classifier/tests/unit/test_urlClassifierExceptionList.js @@ -15,6 +15,7 @@ const ALLOW_LIST_CONVENIENCE_PREF = /** * Convert a JS object from RemoteSettings to an nsIUrlClassifierExceptionListEntry. * Copied from UrlClassifierExceptionListService.sys.mjs with modifications. + * * @param {Object} rsObject - The JS object from RemoteSettings to convert. * @returns {nsIUrlClassifierExceptionListEntry} The converted nsIUrlClassifierExceptionListEntry. */ diff --git a/toolkit/components/utils/ClientEnvironment.sys.mjs b/toolkit/components/utils/ClientEnvironment.sys.mjs @@ -243,6 +243,7 @@ export class ClientEnvironmentBase { /** * Gets the windows build number by querying the OS directly. The initial * version was copied from toolkit/components/telemetry/app/TelemetryEnvironment.sys.mjs + * * @returns {number | null} The build number, or null on non-Windows platform or if there is an error. */ get windowsBuildNumber() { diff --git a/toolkit/components/utils/FilterExpressions.sys.mjs b/toolkit/components/utils/FilterExpressions.sys.mjs @@ -63,6 +63,7 @@ export var FilterExpressions = { /** * Return an array of the given object's own keys (specifically, its enumerable * properties), or undefined if the argument isn't an object. + * * @param {Object} obj * @return {Array[String]|undefined} */ @@ -78,6 +79,7 @@ function keys(obj) { * Return an array of the given object's values (specifically, its own * enumerable string-keyed property values), or undefined if the argument isn't * an object. + * * @param {Object} obj * @return {Array|undefined} */ @@ -91,6 +93,7 @@ function values(obj) { /** * Return the length of an array + * * @param {Array} arr * @return {number} */ @@ -101,6 +104,7 @@ function length(arr) { /** * Given an input array and property name, return an array with each element of * the original array replaced with the given property of that element. + * * @param {Array} arr * @param {string} prop * @return {Array} @@ -112,6 +116,7 @@ function mapToProperty(arr, prop) { /** * Find all the values that are present in both lists. Returns undefined if * the arguments are not both Arrays. + * * @param {Array} listA * @param {Array} listB * @return {Array|undefined} @@ -127,6 +132,7 @@ function operatorIntersect(listA, listB) { /** * Matches a string against a regular expression. Returns null if there are * no matches or an Array of matches. + * * @param {string} str * @param {string} pattern * @param {string} flags @@ -140,6 +146,7 @@ function regExpMatch(str, pattern, flags) { /** * Compares v1 to v2 and returns 0 if they are equal, a negative number if * v1 < v2 or a positive number if v1 > v2. + * * @param {string} v1 * @param {string} v2 * @return {number} diff --git a/toolkit/components/utils/Sampling.sys.mjs b/toolkit/components/utils/Sampling.sys.mjs @@ -9,6 +9,7 @@ const hashMultiplier = Math.pow(2, hashBits) - 1; export var Sampling = { /** * Map from the range [0, 1] to [0, 2^48]. + * * @param {number} frac A float from 0.0 to 1.0. * @return {string} A 48 bit number represented in hex, padded to 12 characters. */ diff --git a/toolkit/components/viewsource/content/viewSourceUtils.js b/toolkit/components/viewsource/content/viewSourceUtils.js @@ -27,6 +27,7 @@ var gViewSourceUtils = { /** * Get the ViewSourcePage actor. + * * @param object An object with `browsingContext` field */ getPageActor({ browsingContext }) { diff --git a/toolkit/content/aboutLogging/profileSaveUploadLogic.mjs b/toolkit/content/aboutLogging/profileSaveUploadLogic.mjs @@ -15,6 +15,7 @@ const $ = document.querySelector.bind(document); * The pref "toolkit.aboutlogging.uploadProfileUrl" can change it in case it is * needed. It is commented out in modules/libpref/init/all.js so that users * don't see it, because this is mostly only useful for tests. + * * @returns {string} */ function uploadProfileUrl() { @@ -27,6 +28,7 @@ function uploadProfileUrl() { /** * A handy function to return a string version of a date and time looking like * YYYYMMDDHHMMSS, that can be used in a file name. + * * @param {Date} date * @reurns {string} */ @@ -73,11 +75,13 @@ export class ProfileSaveOrUploadDialog { #errorElement = $("#save-upload-error"); /** * The gzipped profile data + * * @type {Uint8Array | null} */ #profileData = null; /** * This controls which elements are displayed. See #updateVisibilities. + * * @type {"idle" | "uploading" | "uploaded" | "saved" | "error"} */ #state = "idle"; @@ -93,6 +97,7 @@ export class ProfileSaveOrUploadDialog { /** * This is called to start the upload or save process. + * * @param {Uint8Array} profileData */ init(profileData) { @@ -109,6 +114,7 @@ export class ProfileSaveOrUploadDialog { /** * Set the state and update the visibility of the various elements. + * * @param {"idle" | "uploading" | "uploaded" | "saved" | "error"} state */ #setState(state) { @@ -219,6 +225,7 @@ export class ProfileSaveOrUploadDialog { /** * This functions sets the text and the value to the progress element while * uploading a profile. + * * @param {number} val A number between 0 and 1. */ #setProgressValue(val) { @@ -229,6 +236,7 @@ export class ProfileSaveOrUploadDialog { /** * This saves the profile to a local file, in the preferred downloads * directory. + * * @returns {Promise<void>} */ #saveProfileLocally = async () => { @@ -256,6 +264,7 @@ export class ProfileSaveOrUploadDialog { /** * This uploads the profile, handling all the messages displayed to the user. + * * @returns {Promise<void>} */ #uploadProfileData = async () => { @@ -331,6 +340,7 @@ export class ProfileSaveOrUploadDialog { /** * This uses the Web Share API to share the URL using various ways. * Note that this doesn't work on Desktop (Bug 1958347). + * * @returns {Promise<void>} */ #shareUploadedUrl = async () => { diff --git a/toolkit/content/aboutLogging/profileStorage.mjs b/toolkit/content/aboutLogging/profileStorage.mjs @@ -11,6 +11,7 @@ const STORE_NAME = "uploadedProfiles"; /** * Initialize the IndexedDB database for storing uploaded profile information. + * * @returns {Promise<IDBDatabase>} */ function initDB() { @@ -39,6 +40,7 @@ function initDB() { /** * Save uploaded profile information to IndexedDB. + * * @param {Object} profileInfo * @param {string} profileInfo.jwtToken - The JWT token returned by the server * @param {string} profileInfo.profileToken - The profile token extracted from JWT @@ -69,6 +71,7 @@ export async function saveUploadedProfile(profileInfo) { /** * Get all uploaded profiles from IndexedDB. + * * @returns {Promise<Array>} Array of uploaded profile information */ export async function getAllUploadedProfiles() { @@ -91,6 +94,7 @@ export async function getAllUploadedProfiles() { /** * Delete an uploaded profile from IndexedDB. + * * @param {number} profileId - The ID of the profile to delete * @returns {Promise<void>} */ @@ -110,6 +114,7 @@ export async function deleteUploadedProfile(profileId) { /** * Get a specific uploaded profile by ID. + * * @param {number} profileId - The ID of the profile to retrieve * @returns {Promise<Object|null>} The profile information or null if not found */ diff --git a/toolkit/content/aboutLogging/uploadedProfilesManager.mjs b/toolkit/content/aboutLogging/uploadedProfilesManager.mjs @@ -11,6 +11,7 @@ const $ = document.querySelector.bind(document); * This returns the server endpoint URL to delete a profile. * The pref "toolkit.aboutlogging.deleteProfileUrl" can change it in case it is * needed. It's mostly used for tests. + * * @param {string} profileToken - The profile token to delete * @returns {string} */ @@ -24,6 +25,7 @@ function deleteProfileUrl(profileToken) { /** * Deletes a profile from the profiler server using the JWT token. + * * @param {string} profileToken - The profile token (hash) for the profile * @param {string} jwtToken - The JWT token for the profile * @throws {Error} Throws an error with meaningful message if deletion fails @@ -119,6 +121,7 @@ export class UploadedProfilesManager { /** * Show an error message to the user. + * * @param {string} errorText - The error message to display */ #showError(errorText) { @@ -157,6 +160,7 @@ export class UploadedProfilesManager { /** * Render the list of profiles in the UI. + * * @param {Array} profiles - Array of profile objects */ #renderProfiles(profiles) { @@ -226,6 +230,7 @@ export class UploadedProfilesManager { /** * Handle click on delete button. + * * @param {Event} event */ async #handleDeleteClick(event) { diff --git a/toolkit/content/aboutTelemetry.js b/toolkit/content/aboutTelemetry.js @@ -1445,6 +1445,7 @@ var Search = { /** * Helper function to render JS objects with white space between top level elements * so that they look better in the browser + * * @param aObject JavaScript object or array to render * @return String */ @@ -1536,6 +1537,7 @@ var GenericTable = { /** * Returns a n-column table. + * * @param rows An array of arrays, each containing data to render * for one row. * @param headings The column header strings. @@ -1624,6 +1626,7 @@ var KeyedHistogram = { var AddonDetails = { /** * Render the addon details section as a series of headers followed by key/value tables + * * @param aPing A ping object to render the data from. */ render(aPing) { @@ -1754,6 +1757,7 @@ class Scalars extends Section { /** * Render the scalar data - if present - from the payload in a simple key-value table. + * * @param aPayload A payload object to render the data from. */ static render(aPayload) { @@ -1804,6 +1808,7 @@ class KeyedScalars extends Section { /** * Render the keyed scalar data - if present - from the payload in a simple key-value table. + * * @param aPayload A payload object to render the data from. */ static render(aPayload) { @@ -1816,6 +1821,7 @@ class KeyedScalars extends Section { var Events = { /** * Render the event data - if present - from the payload in a simple table. + * * @param aPayload A payload object to render the data from. */ render(aPayload) { diff --git a/toolkit/content/contentAreaUtils.js b/toolkit/content/contentAreaUtils.js @@ -553,6 +553,7 @@ function internalPersist(persistArgs) { * Structure for holding info about automatically supplied parameters for * internalSave(...). This allows parameters to be supplied so the user does not * need to be prompted for file info. + * * @param aFileAutoChosen This is an nsIFile object that has been * pre-determined as the filename for the target to save to * @param aUriAutoChosen This is the nsIURI object for the target @@ -565,6 +566,7 @@ function AutoChosen(aFileAutoChosen, aUriAutoChosen) { /** * Structure for holding info about a URL and the target filename it should be * saved to. This structure is populated by initFileInfo(...). + * * @param aSuggestedFileName This is used by initFileInfo(...) when it * cannot 'discover' the filename from the url * @param aFileName The target filename @@ -590,6 +592,7 @@ function FileInfo( * Determine what the 'default' filename string is, its file extension and the * filename without the extension. This filename is used when prompting the user * for confirmation in the file picker dialog. + * * @param aFI A FileInfo structure into which we'll put the results of this method. * @param aURL The String representation of the URL of the document being saved * @param aURLCharset The charset of aURL. @@ -656,6 +659,7 @@ function initFileInfo( /** * Given the Filepicker Parameters (aFpP), show the file picker dialog, * prompting the user to confirm (or change) the fileName. + * * @param aFpP * A structure (see definition in internalSave(...) method) * containing all the data used within this method. diff --git a/toolkit/content/preferences/AsyncSetting.mjs b/toolkit/content/preferences/AsyncSetting.mjs @@ -34,12 +34,14 @@ export class AsyncSetting extends EventEmitter { /** * Setup any external listeners that are required for managing this * setting's state. When the state needs to update the Setting.emitChange method should be called. + * * @returns {Function | void} Teardown function to clean up external listeners. */ setup() {} /** * Get the value of this setting. + * * @abstract * @returns {Promise<boolean | number | string | void>} */ @@ -47,6 +49,7 @@ export class AsyncSetting extends EventEmitter { /** * Set the value of this setting. + * * @abstract * @param value {any} The value from the input that triggered the update. * @returns {Promise<void>} @@ -55,6 +58,7 @@ export class AsyncSetting extends EventEmitter { /** * Whether the control should be disabled. + * * @returns {Promise<boolean>} */ async disabled() { @@ -63,6 +67,7 @@ export class AsyncSetting extends EventEmitter { /** * Whether the control should be visible. + * * @returns {Promise<boolean>} */ async visible() { @@ -72,6 +77,7 @@ export class AsyncSetting extends EventEmitter { /** * Override the initial control config. This will be spread into the * initial config, with this object taking precedence. + * * @returns {Promise<Object>} */ async getControlConfig() { @@ -81,6 +87,7 @@ export class AsyncSetting extends EventEmitter { /** * Callback fired after a user has changed the setting's value. Useful for * recording telemetry. + * * @param value {any} * @returns {Promise<void>} */ diff --git a/toolkit/content/tests/browser/browser_about_logging.js b/toolkit/content/tests/browser/browser_about_logging.js @@ -41,6 +41,7 @@ function clearUploadedProfilesDB(content) { /** * This function will select a node from the XPath. * This function has been copied from the devtools' performance panel's tests. + * * @returns {HTMLElement?} */ function getElementByXPath(document, path) { diff --git a/toolkit/content/tests/browser/head.js b/toolkit/content/tests/browser/head.js @@ -192,6 +192,7 @@ function once(target, name) { /** * check if current wakelock is equal to expected state, if not, then wait until * the wakelock changes its state to expected state. + * * @param needLock * the wakolock should be locked or not * @param isForegroundLock diff --git a/toolkit/content/tests/widgets/head.js b/toolkit/content/tests/widgets/head.js @@ -36,6 +36,7 @@ function getElementWithinVideo(video, aValue) { /** * Runs querySelectorAll on an element's shadow root. + * * @param {Element} element * @param {string} selector */ diff --git a/toolkit/content/widgets/calendar.js b/toolkit/content/widgets/calendar.js @@ -106,6 +106,7 @@ Calendar.prototype = { /** * Render the items onto the DOM nodes + * * @param {Object} * { * {Array<DOMElement>} elements @@ -251,6 +252,7 @@ Calendar.prototype = { /** * Handle events + * * @param {DOMEvent} event */ handleEvent(event) { @@ -400,6 +402,7 @@ Calendar.prototype = { /** * Find Data-id of the next element to focus on the daysView grid + * * @param {Object} nextDate: Data object of the next element to focus */ _calculateNextId(nextDate) { @@ -413,6 +416,7 @@ Calendar.prototype = { /** * Comparing two date objects to ensure they produce the same date + * * @param {Date} dateObj1: Date object from the updated state * @param {Date} dateObj2: Date object from the previous state * @return {Boolean} If two date objects are the same day @@ -428,6 +432,7 @@ Calendar.prototype = { /** * Comparing two date objects to ensure they produce the same day of the month, * while being on different months + * * @param {Date} dateObj1: Date object from the updated state * @param {Date} dateObj2: Date object from the previous state * @return {Boolean} If two date objects are the same day of the month @@ -438,6 +443,7 @@ Calendar.prototype = { /** * Manage focus for the keyboard navigation for the daysView grid + * * @param {Number} offsetDays: The direction and the number of days to move * the focus by, where a negative number (i.e. -1) * moves the focus to the previous day diff --git a/toolkit/content/widgets/datekeeper.js b/toolkit/content/widgets/datekeeper.js @@ -42,6 +42,7 @@ function DateKeeper(props) { /** * Initialize DateKeeper + * * @param {Number} year * @param {Number} month * @param {Number} day @@ -126,6 +127,7 @@ function DateKeeper(props) { /** * Set new calendar month. The year is always treated as full year, so the * short-form is not supported. + * * @param {Object} date parts * { * {Number} year [optional] @@ -146,6 +148,7 @@ function DateKeeper(props) { /** * Set selection date + * * @param {Number} year * @param {Number} month * @param {Number} day @@ -158,6 +161,7 @@ function DateKeeper(props) { /** * Set month. Makes sure the day is <= the last day of the month + * * @param {Number} month */ setMonth(month) { @@ -166,6 +170,7 @@ function DateKeeper(props) { /** * Set year. Makes sure the day is <= the last day of the month + * * @param {Number} year */ setYear(year) { @@ -174,6 +179,7 @@ function DateKeeper(props) { /** * Set month by offset. Makes sure the day is <= the last day of the month + * * @param {Number} offset */ setMonthByOffset(offset) { @@ -182,6 +188,7 @@ function DateKeeper(props) { /** * Generate the array of months + * * @return {Array<Object>} * { * {Number} value: Month in int @@ -213,6 +220,7 @@ function DateKeeper(props) { /** * Generate the array of years + * * @return {Array<Object>} * { * {Number} value: Year in int @@ -255,6 +263,7 @@ function DateKeeper(props) { /** * Get days for calendar + * * @return {Array<Object>} * { * {Date} dateObj @@ -348,6 +357,7 @@ function DateKeeper(props) { /** * Check if a date is off step given a starting point and the next increment + * * @param {Date} start * @param {Date} next * @return {Boolean} @@ -369,6 +379,7 @@ function DateKeeper(props) { /** * Get week headers for calendar + * * @param {Number} firstDayOfWeek * @param {Array<Number>} weekends * @return {Array<Object>} @@ -395,6 +406,7 @@ function DateKeeper(props) { /** * Get the first day on a calendar month + * * @param {Date} dateObj * @param {Number} firstDayOfWeek * @return {Date} @@ -420,6 +432,7 @@ function DateKeeper(props) { /** * Helper function for creating UTC dates + * * @param {...[Number]} parts * @return {Date} */ diff --git a/toolkit/content/widgets/datepicker.js b/toolkit/content/widgets/datepicker.js @@ -19,6 +19,7 @@ function DatePicker(context) { DatePicker.prototype = { /** * Initializes the date picker. Set the default states and properties. + * * @param {Object} props * { * {Number} year [optional] @@ -551,6 +552,7 @@ function DatePicker(context) { /** * Handle events + * * @param {DOMEvent} event */ handleEvent(event) { diff --git a/toolkit/content/widgets/findbar.js b/toolkit/content/widgets/findbar.js @@ -654,6 +654,7 @@ /** * Sets the findbar diacritic-matching mode + * * @param {Number} diacriticMatching 0 - ignore diacritics, * 1 - match diacritics, * 2 - auto = match diacritics if the diff --git a/toolkit/content/widgets/moz-button/moz-button.mjs b/toolkit/content/widgets/moz-button/moz-button.mjs @@ -77,6 +77,7 @@ class MenuController { /** * Retrieves the panel-list element matching the host's menuId. + * * @returns {HTMLElement | null} */ getPanelList() { @@ -101,6 +102,7 @@ class MenuController { /** * Handles opening/closing the panel-list when the host is clicked or activated via keyboard. + * * @param {MouseEvent|KeyboardEvent} event */ openPanelList = event => { diff --git a/toolkit/content/widgets/moz-card/moz-card.mjs b/toolkit/content/widgets/moz-card/moz-card.mjs @@ -21,7 +21,6 @@ import { MozLitElement } from "chrome://global/content/lit-utils.mjs"; * is visible. You can use the "expanded" attribute to force the accordion * card to show its content on initial render. * - * * @property {string} heading - The heading text that will be used for the card. * @property {string} iconSrc - Path to the icon that should be displayed in the card. * @property {string} type - (optional) The type of card. No type specified diff --git a/toolkit/content/widgets/moz-message-bar/moz-message-bar.mjs b/toolkit/content/widgets/moz-message-bar/moz-message-bar.mjs @@ -70,36 +70,42 @@ export default class MozMessageBar extends MozLitElement { /** * The type of the displayed message. + * * @type {MozMessageBarType} */ this.type = "info"; /** * Whether or not the element is dismissable. + * * @type {boolean} */ this.dismissable = false; /** * The message text. + * * @type {string | undefined} */ this.message = undefined; /** * l10n ID for the message. + * * @type {string | undefined} */ this.messageL10nId = undefined; /** * Any args needed for the message l10n ID. + * * @type {Record<string, string> | undefined} */ this.messageL10nArgs = undefined; /** * The heading of the message. + * * @type {string | undefined} */ this.heading = undefined; diff --git a/toolkit/content/widgets/moz-support-link/moz-support-link.mjs b/toolkit/content/widgets/moz-support-link/moz-support-link.mjs @@ -24,6 +24,11 @@ export default class MozSupportLink extends HTMLAnchorElement { * Handles setting up the SUPPORT_URL preference getter. * Without this, the tests for this component may not behave * as expected. +<<<<<<< HEAD +======= + * + * @private +>>>>>>> b0875b52eeb8 (Bug 1998787 - Automatic fixes for enabling ESLint jsdoc/tag-line rule everywhere. r?#frontend-codestlye-reviewers) * @memberof MozSupportLink */ #register() { diff --git a/toolkit/content/widgets/spinner.js b/toolkit/content/widgets/spinner.js @@ -321,6 +321,7 @@ function Spinner(props, context) { /** * Handle events + * * @param {DOMEvent} event */ handleEvent(event) { @@ -471,6 +472,7 @@ function Spinner(props, context) { /** * Find the index by offset + * * @param {Number} offset: Offset value in pixel. * @return {Number} Index number */ diff --git a/toolkit/content/widgets/timekeeper.js b/toolkit/content/widgets/timekeeper.js @@ -35,6 +35,7 @@ function TimeKeeper(props) { TimeKeeper.prototype = { /** * Getters for different time units. + * * @return {Number} */ get hour() { @@ -58,6 +59,7 @@ function TimeKeeper(props) { /** * Get the ranges of different time units. + * * @return {Object} * { * {Array<Number>} dayPeriod @@ -108,6 +110,7 @@ function TimeKeeper(props) { /** * Set day-period (AM/PM) + * * @param {Number} dayPeriod: 0 as AM, 12 as PM */ setDayPeriod(dayPeriod) { @@ -124,6 +127,7 @@ function TimeKeeper(props) { /** * Set hour in 24hr format (0 ~ 23) + * * @param {Number} hour */ setHour(hour) { @@ -132,6 +136,7 @@ function TimeKeeper(props) { /** * Set minute (0 ~ 59) + * * @param {Number} minute */ setMinute(minute) { @@ -140,6 +145,7 @@ function TimeKeeper(props) { /** * Set second (0 ~ 59) + * * @param {Number} second */ setSecond(second) { @@ -148,6 +154,7 @@ function TimeKeeper(props) { /** * Set millisecond (0 ~ 999) + * * @param {Number} millisecond */ setMillisecond(millisecond) { @@ -268,6 +275,7 @@ function TimeKeeper(props) { /** * Get the milliseconds range + * * @param {Number} hour * @param {Number} minute * @param {Number} second diff --git a/toolkit/content/widgets/timepicker.js b/toolkit/content/widgets/timepicker.js @@ -19,6 +19,7 @@ function TimePicker(context) { TimePicker.prototype = { /** * Initializes the time picker. Set the default states and properties. + * * @param {Object} props * { * {Number} hour [optional]: Hour in 24 hours format (0~23), default is current hour diff --git a/toolkit/crashreporter/CrashSubmit.sys.mjs b/toolkit/crashreporter/CrashSubmit.sys.mjs @@ -488,6 +488,7 @@ export var CrashSubmit = { /** * Get the list of pending crash IDs, excluding those marked to be ignored + * * @param minFileDate * A Date object. Any files last modified before that date will be ignored * diff --git a/toolkit/crashreporter/test/unit/head_crashreporter.js b/toolkit/crashreporter/test/unit/head_crashreporter.js @@ -41,7 +41,6 @@ function sendCommandAsync(command) { * If true, the subprocess may return with a zero exit code. * Certain types of crashes may not cause the process to * exit with an error. - * */ async function do_crash(setup, callback, canReturnZero) { // get current process filename (xpcshell) @@ -274,7 +273,6 @@ async function do_triggered_content_crash(trigger, callback) { * If true, the subprocess may return with a zero exit code. * Certain types of crashes may not cause the process to * exit with an error. - * */ async function do_backgroundtask_crash( crashType, diff --git a/toolkit/modules/CreditCard.sys.mjs b/toolkit/modules/CreditCard.sys.mjs @@ -217,6 +217,7 @@ export class CreditCard { /** * Normalizes a credit card number. + * * @param {string} number * @return {string | null} * @memberof CreditCard diff --git a/toolkit/modules/FileUtils.sys.mjs b/toolkit/modules/FileUtils.sys.mjs @@ -17,6 +17,7 @@ export var FileUtils = { /** * Gets a directory at the specified hierarchy under a nsIDirectoryService * key. + * * @param key * The Directory Service Key to start from * @param pathArray @@ -34,6 +35,7 @@ export var FileUtils = { /** * Opens a file output stream for writing. + * * @param file * The file to write to. * @param modeFlags @@ -54,6 +56,7 @@ export var FileUtils = { /** * Opens an atomic file output stream for writing. + * * @param file * The file to write to. * @param modeFlags @@ -76,6 +79,7 @@ export var FileUtils = { /** * Opens a safe file output stream for writing. + * * @param file * The file to write to. * @param modeFlags @@ -108,6 +112,7 @@ export var FileUtils = { /** * Closes an atomic file output stream. + * * @param stream * The stream to close. */ @@ -125,6 +130,7 @@ export var FileUtils = { /** * Closes a safe file output stream. + * * @param stream * The stream to close. */ diff --git a/toolkit/modules/GMPInstallManager.sys.mjs b/toolkit/modules/GMPInstallManager.sys.mjs @@ -185,6 +185,7 @@ GMPInstallManager.prototype = { /** * Determines the root to use for verifying content signatures. + * * @param url * The Balrog URL, i.e. the return value of _getURL(). */ @@ -216,6 +217,7 @@ GMPInstallManager.prototype = { /** * Records telemetry results on if fetching update.xml from Balrog succeeded * when content signature was used to verify the response from Balrog. + * * @param didGetAddonList * A boolean indicating if an update.xml containing the addon list was * successfully fetched (true) or not (false). @@ -270,6 +272,7 @@ GMPInstallManager.prototype = { * Records telemetry results on if fetching update.xml from Balrog succeeded * when cert pinning was used to verify the response from Balrog. This * should be removed once we're no longer using cert pinning. + * * @param didGetAddonList * A boolean indicating if an update.xml containing the addon list was * successfully fetched (true) or not (false). @@ -321,6 +324,7 @@ GMPInstallManager.prototype = { /** * Performs an addon check. + * * @return a promise which will be resolved or rejected. * The promise is resolved with an object with properties: * addons: array of addons @@ -526,6 +530,7 @@ GMPInstallManager.prototype = { }, /** * Installs the specified addon and calls a callback when done. + * * @param gmpAddon The GMPAddon object to install * @return a promise which will be resolved or rejected * The promise will resolve with an array of paths that were extracted @@ -585,6 +590,7 @@ GMPInstallManager.prototype = { * Wrapper for checkForAddons and installAddon. * Will only install if not already installed and will log the results. * This will only install/update the OpenH264 and EME plugins + * * @return a promise which will be resolved if all addons could be installed * successfully, rejected otherwise. */ @@ -771,6 +777,7 @@ GMPAddon.prototype = { }, /** * If all the fields aren't specified don't consider this addon valid + * * @return true if the addon is parsed and valid */ get isValid() { @@ -813,6 +820,7 @@ GMPAddon.prototype = { /** * Constructs a GMPExtractor object which is used to extract a GMP zip * into the specified location. + * * @param zipPath The path on disk of the zip file to extract * @param relativePath The relative path components inside the profile directory * to extract the zip to. @@ -863,6 +871,7 @@ GMPExtractor.prototype = { /** * Constructs an object which downloads and initiates an install of * the specified GMPAddon object. + * * @param gmpAddon The addon to install. */ export function GMPDownloader(gmpAddon) { @@ -872,6 +881,7 @@ export function GMPDownloader(gmpAddon) { GMPDownloader.prototype = { /** * Starts the download process for an addon. + * * @return a promise which will be resolved or rejected * See GMPInstallManager.installAddon for resolve/rejected info */ diff --git a/toolkit/modules/GMPUtils.sys.mjs b/toolkit/modules/GMPUtils.sys.mjs @@ -20,6 +20,7 @@ export var GMPUtils = { /** * Checks whether or not a given plugin is hidden. Hidden plugins are neither * downloaded nor displayed in the addons manager. + * * @param aPlugin * The plugin to check. */ @@ -41,6 +42,7 @@ export var GMPUtils = { /** * Checks whether or not a given plugin is supported by the current OS. + * * @param aPlugin * The plugin to check. */ @@ -73,6 +75,7 @@ export var GMPUtils = { * Checks whether or not a given plugin is visible in the addons manager * UI and the "enable DRM" notification box. This can be used to test * plugins that aren't yet turned on in the mozconfig. + * * @param aPlugin * The plugin to check. */ @@ -84,6 +87,7 @@ export var GMPUtils = { * Checks whether or not a given plugin is forced-supported. This is used * in automated tests to override the checks that prevent GMPs running on an * unsupported platform. + * * @param aPlugin * The plugin to check. */ @@ -195,6 +199,7 @@ export var GMPPrefs = { /** * Obtains the specified string preference in relation to the specified plugin. + * * @param aKey The preference key value to use. * @param aDefaultValue The default value if no preference exists. * @param aPlugin The plugin to scope the preference to. @@ -215,6 +220,7 @@ export var GMPPrefs = { /** * Obtains the specified int preference in relation to the specified plugin. + * * @param aKey The preference key value to use. * @param aDefaultValue The default value if no preference exists. * @param aPlugin The plugin to scope the preference to. @@ -229,6 +235,7 @@ export var GMPPrefs = { /** * Obtains the specified bool preference in relation to the specified plugin. + * * @param aKey The preference key value to use. * @param aDefaultValue The default value if no preference exists. * @param aPlugin The plugin to scope the preference to. @@ -243,6 +250,7 @@ export var GMPPrefs = { /** * Sets the specified string preference in relation to the specified plugin. + * * @param aKey The preference key value to use. * @param aVal The value to set. * @param aPlugin The plugin to scope the preference to. @@ -253,6 +261,7 @@ export var GMPPrefs = { /** * Sets the specified bool preference in relation to the specified plugin. + * * @param aKey The preference key value to use. * @param aVal The value to set. * @param aPlugin The plugin to scope the preference to. @@ -263,6 +272,7 @@ export var GMPPrefs = { /** * Sets the specified int preference in relation to the specified plugin. + * * @param aKey The preference key value to use. * @param aVal The value to set. * @param aPlugin The plugin to scope the preference to. @@ -274,6 +284,7 @@ export var GMPPrefs = { /** * Checks whether or not the specified preference is set in relation to the * specified plugin. + * * @param aKey The preference key value to use. * @param aPlugin The plugin to scope the preference to. * @return true if the preference is set, false otherwise. @@ -285,6 +296,7 @@ export var GMPPrefs = { /** * Resets the specified preference in relation to the specified plugin to its * default. + * * @param aKey The preference key value to use. * @param aPlugin The plugin to scope the preference to. */ @@ -294,6 +306,7 @@ export var GMPPrefs = { /** * Scopes the specified preference key to the specified plugin. + * * @param aKey The preference key value to use. * @param aPlugin The plugin to scope the preference to. * @return A preference key scoped to the specified plugin. diff --git a/toolkit/modules/Geometry.sys.mjs b/toolkit/modules/Geometry.sys.mjs @@ -347,6 +347,7 @@ Rect.prototype = { /** * Blends two rectangles together. + * * @param rect Rectangle to blend this one with * @param scalar Ratio from 0 (returns a clone of this rect) to 1 (clone of rect). * @return New blended rectangle. diff --git a/toolkit/modules/LightweightThemeConsumer.sys.mjs b/toolkit/modules/LightweightThemeConsumer.sys.mjs @@ -577,6 +577,7 @@ function _hasDarkFrame(doc, theme, colors, hasTheme) { * Sets dark mode attributes on root, if required. We must do this here, * instead of in each color's processColor function, because multiple colors * are considered. + * * @param {Document} doc * @param {Element} root * @param {object} colors @@ -638,6 +639,7 @@ function _setDarkModeAttributes(doc, root, theme, colors, hasTheme) { * scheme. We consider both the background and foreground (i.e. usually text) * colors because some text colors can be dark enough for our heuristics, but * still contrast well enough with a dark background + * * @param {Document} doc * @param {object} colors * @param {string?} textPropertyName diff --git a/toolkit/modules/NewTabUtils.sys.mjs b/toolkit/modules/NewTabUtils.sys.mjs @@ -63,6 +63,7 @@ const DEFAULT_SMALL_FAVICON_WIDTH = 16; /** * Calculate the MD5 hash for a string. + * * @param aValue * The string to convert. * @return The base64 representation of the MD5 hash. @@ -76,6 +77,7 @@ function toHash(aValue) { /** * Properly convert internationalized domain names. + * * @param {string} host Domain hostname. * @returns {string} Hostname suitable to be displayed. */ @@ -163,6 +165,7 @@ LinksStorage.prototype = { /** * Gets the value for a given key from the storage. + * * @param aKey The storage key (a string). * @param aDefault A default value if the key doesn't exist. * @return The value for the given key. @@ -178,6 +181,7 @@ LinksStorage.prototype = { /** * Sets the storage value for a given key. + * * @param aKey The storage key (a string). * @param aValue The value to set. */ @@ -188,6 +192,7 @@ LinksStorage.prototype = { /** * Removes the storage value for a given key. + * * @param aKey The storage key (a string). */ remove: function Storage_remove(aKey) { @@ -227,6 +232,7 @@ var PinnedLinks = { /** * Pins a link at the given position. + * * @param aLink The link to pin. * @param aIndex The grid index to pin the cell at. * @return true if link changes, false otherwise @@ -244,6 +250,7 @@ var PinnedLinks = { /** * Unpins a given link. + * * @param aLink The link to unpin. */ unpin: function PinnedLinks_unpin(aLink) { @@ -271,6 +278,7 @@ var PinnedLinks = { /** * Checks whether a given link is pinned. + * * @params aLink The link to check. * @return whether The link is pinned. */ @@ -287,6 +295,7 @@ var PinnedLinks = { /** * Finds the index of a given link in the list of pinned links. + * * @param aLink The link to find an index for. * @return The link's index. */ @@ -304,6 +313,7 @@ var PinnedLinks = { /** * Transforms link into a "history" link + * * @param aLink The link to change * @return true if link changes, false otherwise */ @@ -317,6 +327,7 @@ var PinnedLinks = { /** * Replaces existing link with another link. + * * @param aUrl The url of existing link * @param aLink The replacement link */ @@ -371,6 +382,7 @@ var BlockedLinks = { /** * Blocks a given link. Adjusts siteMap accordingly, and notifies listeners. + * * @param aLink The link to block. */ block: function BlockedLinks_block(aLink) { @@ -384,6 +396,7 @@ var BlockedLinks = { /** * Unblocks a given link. Adjusts siteMap accordingly, and notifies listeners. + * * @param aLink The link to unblock. */ unblock: function BlockedLinks_unblock(aLink) { @@ -403,6 +416,7 @@ var BlockedLinks = { /** * Returns whether a given link is blocked. + * * @param aLink The link to check. */ isBlocked: function BlockedLinks_isBlocked(aLink) { @@ -411,6 +425,7 @@ var BlockedLinks = { /** * Checks whether the list of blocked links is empty. + * * @return Whether the list is empty. */ isEmpty: function BlockedLinks_isEmpty() { @@ -462,6 +477,7 @@ var PlacesProvider = { /** * Gets the current set of links delivered by this provider. + * * @param aCallback The function that the array of links is passed to. */ getLinks: function PlacesProvider_getLinks(aCallback) { @@ -536,6 +552,7 @@ var PlacesProvider = { /** * Registers an object that will be notified when the provider's links change. + * * @param aObserver An object with the following optional properties: * * onLinkChanged: A function that's called when a single link * changes. It's passed the provider and the link object. Only the @@ -1386,6 +1403,7 @@ var Links = { /** * Adds a link provider. + * * @param aProvider The link provider. */ addProvider: function Links_addProvider(aProvider) { @@ -1395,6 +1413,7 @@ var Links = { /** * Removes a link provider. + * * @param aProvider The link provider. */ removeProvider: function Links_removeProvider(aProvider) { @@ -1405,6 +1424,7 @@ var Links = { /** * Populates the cache with fresh links from the providers. + * * @param aCallback The callback to call when finished (optional). * @param aForce When true, populates the cache even when it's already filled. */ @@ -1451,6 +1471,7 @@ var Links = { /** * Gets the current set of links contained in the grid. + * * @return The links in the grid. */ getLinks: function Links_getLinks() { @@ -1506,6 +1527,7 @@ var Links = { /** * Compares two links. + * * @param aLink1 The first link. * @param aLink2 The second link. * @return A negative number if aLink1 is ordered before aLink2, zero if @@ -1593,6 +1615,7 @@ var Links = { /** * Calls getLinks on the given provider and populates our cache for it. + * * @param aProvider The provider whose cache will be populated. * @param aCallback The callback to call when finished. * @param aForce When true, populates the provider's cache even when it's @@ -1638,6 +1661,7 @@ var Links = { /** * Merges the cached lists of links from all providers whose lists are cached. + * * @return The merged list. */ _getMergedProviderLinks: function Links__getMergedProviderLinks() { @@ -1685,6 +1709,7 @@ var Links = { /** * Called by a provider to notify us when a single link changes. + * * @param aProvider The provider whose link changed. * @param aLink The link that changed. If the link is new, it must have all * of the _sortProperties. Otherwise, it may have as few or as @@ -1938,6 +1963,7 @@ export var NewTabUtils = { /** * Extract a "site" from a url in a way that multiple urls of a "site" returns * the same "site." + * * @param aUrl Url spec string * @return The "site" string or null */ @@ -2012,6 +2038,7 @@ export var NewTabUtils = { /** * Undoes all sites that have been removed from the grid and keep the pinned * tabs. + * * @param aCallback the callback method. */ undoAll: function NewTabUtils_undoAll(aCallback) { @@ -2023,6 +2050,7 @@ export var NewTabUtils = { /** * Get the effective top level domain of a host. + * * @param {string} host The host to be analyzed. * @return {str} The suffix or empty string if there's no suffix. */ @@ -2087,6 +2115,7 @@ export var NewTabUtils = { /** * retrieves positive UTC offset, rounded to the nearest integer number greater than 0. * (If less than 0, then add 24.) + * * @param {str} [surfaceID] Optional surface ID to constrain time zone to reduce identifying telemetry. * @returns {Number} utc_offset. Output is clamped if surfaceID is specified, and 0 if surfaceID present and not supported. */ diff --git a/toolkit/modules/PopupNotifications.sys.mjs b/toolkit/modules/PopupNotifications.sys.mjs @@ -195,6 +195,7 @@ Notification.prototype = { /** * The PopupNotifications object manages popup notifications for a given browser * window. + * * @param tabbrowser * window's TabBrowser. Used to observe tab switching events and * for determining the active browser element. @@ -380,6 +381,7 @@ PopupNotifications.prototype = { /** * Retrieve one or many Notification object/s associated with the browser/ID pair. + * * @param {string|string[]} id * The Notification ID or an array of IDs to search for. * @param [browser] @@ -402,6 +404,7 @@ PopupNotifications.prototype = { /** * Adds a new popup notification. + * * @param browser * The <xul:browser> element associated with the notification. Must not * be null. @@ -798,6 +801,7 @@ PopupNotifications.prototype = { /** * Removes one or many Notifications. + * * @param {Notification|Notification[]} notification - The Notification object/s to remove. * @param {Boolean} [isCancel] - Whether to signal, in the notification event, that removal * should be treated as cancel. This is currently used to cancel permission requests diff --git a/toolkit/modules/PrefUtils.sys.mjs b/toolkit/modules/PrefUtils.sys.mjs @@ -10,6 +10,7 @@ const kPrefBranches = { export var PrefUtils = { /** * Get a preference of any type from the named branch. + * * @param {string} pref * @param {object} [options] * @param {"default"|"user"} [options.branchName="user"] One of "default" or "user" @@ -56,6 +57,7 @@ export var PrefUtils = { /** * Set a preference on the named branch + * * @param {string} pref * @param {string|boolean|integer|null} value The value to set. * @param {object} options diff --git a/toolkit/modules/Preferences.sys.mjs b/toolkit/modules/Preferences.sys.mjs @@ -212,6 +212,7 @@ Preferences.isSet = function (prefName) { /** * Whether or not the given pref has a user-set value. Use isSet instead, * which is equivalent. + * * @deprecated */ Preferences.modified = function (prefName) { @@ -355,6 +356,7 @@ Preferences.resetBranch = function (prefBranch = "") { /** * A string identifying the branch of the preferences tree to which this * instance provides access. + * * @private */ Preferences._branchStr = ""; @@ -362,12 +364,14 @@ Preferences._branchStr = ""; /** * The cached preferences branch object this instance encapsulates, or null. * Do not use! Use _prefBranch below instead. + * * @private */ Preferences._cachedPrefBranch = null; /** * The preferences branch object for this instance. + * * @private */ Object.defineProperty(Preferences, "_prefBranch", { diff --git a/toolkit/modules/PropertyListUtils.sys.mjs b/toolkit/modules/PropertyListUtils.sys.mjs @@ -194,6 +194,7 @@ export var PropertyListUtils = Object.freeze({ /** * Wraps a 64-bit stored in the form of a string primitive as a String object, * which we can later distiguish from regular string values. + * * @param aPrimitive * a number in the form of either a primitive string or a primitive number. * @return a String wrapper around aNumberStr that can later be identified @@ -500,6 +501,7 @@ BinaryPropertyListReader.prototype = { /** * Read array from the buffer and wrap it as a js array. + * * @param aObjectOffset * the offset in the buffer at which the array starts. * @param aNumberOfObjects @@ -536,6 +538,7 @@ BinaryPropertyListReader.prototype = { /** * Reads dictionary from the buffer and wraps it as a Map object. + * * @param aObjectOffset * the offset in the buffer at which the dictionary starts * @param aNumberOfObjects @@ -572,6 +575,7 @@ BinaryPropertyListReader.prototype = { /** * Reads an object at the spcified index in the object table + * * @param aObjectIndex * index at the object table * @return the property list object at the given index. @@ -707,6 +711,7 @@ XMLPropertyListReader.prototype = { /** * Convert a dom element to a property list object. + * * @param aDOMElt * a dom element in a xml tree of a property list. * @return a js object representing the property list object. @@ -820,6 +825,7 @@ XMLPropertyListReader.prototype = { * Simple handler method to proxy calls to dict/Map objects to implement the * setAsLazyGetter API. With this, a value can be set as a function that will * evaluate its value and only be called when it's first retrieved. + * * @member _lazyGetters * Set() object to hold keys invoking LazyGetter. * @method get diff --git a/toolkit/modules/Sqlite.sys.mjs b/toolkit/modules/Sqlite.sys.mjs @@ -310,6 +310,7 @@ function unregisterVacuumParticipant(connectionData) { /** * Create a ConsoleInstance logger with a given prefix. + * * @param {string} prefix The prefix to use when logging. * @returns {ConsoleInstance} a console logger. */ @@ -471,6 +472,7 @@ ConnectionData.prototype = Object.freeze({ /** * This should only be used by the VacuumManager component. + * * @see unsafeRawConnection for an official (but still unsafe) API. */ get databaseConnection() { diff --git a/toolkit/modules/SubDialog.sys.mjs b/toolkit/modules/SubDialog.sys.mjs @@ -17,6 +17,7 @@ const HTML_NS = "http://www.w3.org/1999/xhtml"; /** * The SubDialog resize callback. + * * @callback SubDialog~resizeCallback * @param {DOMNode} title - The title element of the dialog. * @param {xul:browser} frame - The browser frame of the dialog. @@ -25,6 +26,7 @@ const HTML_NS = "http://www.w3.org/1999/xhtml"; /** * SubDialog constructor creates a new subdialog from a template and appends * it to the parentElement. + * * @param {DOMNode} template - The template is copied to create a new dialog. * @param {DOMNode} parentElement - New dialog is appended onto parentElement. * @param {String} id - A unique identifier for the dialog. @@ -785,6 +787,7 @@ SubDialog.prototype = { /** * Setup dialog event listeners. + * * @param {Boolean} [includeLoad] - Whether to register load/unload listeners. */ _addDialogEventListeners(includeLoad = true) { @@ -834,6 +837,7 @@ SubDialog.prototype = { /** * Remove dialog event listeners. + * * @param {Boolean} [includeLoad] - Whether to remove load/unload listeners. */ _removeDialogEventListeners(includeLoad = true) { @@ -876,6 +880,7 @@ SubDialog.prototype = { * Focus the dialog content. * If the embedded document defines a custom focus handler it will be called. * Otherwise we will focus the first focusable element in the content window. + * * @param {boolean} [isInitialFocus] - Whether the dialog is focused for the * first time after opening. */ @@ -954,6 +959,7 @@ export class SubDialogManager { * New dialogs are pushed to the end of the _dialogs array. * Depending on the orderType either the last element (stack) or the first * element (queue) in the array will be the top and visible. + * * @type {SubDialog[]} */ this._dialogs = []; @@ -1079,6 +1085,7 @@ export class SubDialogManager { /** * Abort open dialogs. + * * @param {function} [filterFn] - Function which should return true for * dialogs that should be aborted and false for dialogs that should remain * open. Defaults to aborting all dialogs. diff --git a/toolkit/modules/WebChannel.sys.mjs b/toolkit/modules/WebChannel.sys.mjs @@ -250,7 +250,6 @@ WebChannel.prototype = { * Can be null; if not null, should be a ContentDOMReference. * @param sendingContext.principal {Principal} * The <Principal> of the EventTarget where the message was sent. - * */ deliver(data, sendingContext) { if (this._deliverCallback) { diff --git a/toolkit/modules/tests/modules/OSKeyStoreTestUtils.sys.mjs b/toolkit/modules/tests/modules/OSKeyStoreTestUtils.sys.mjs @@ -26,6 +26,7 @@ export var OSKeyStoreTestUtils = { * Checks whether or not the test can be run by bypassing * the OS login dialog. We do not want the user to be able to * do so with in official builds. + * * @returns {boolean} True if the test can be performed. */ canTestOSKeyStoreLogin() { diff --git a/toolkit/modules/tests/xpcshell/test_GMPInstallManager.js b/toolkit/modules/tests/xpcshell/test_GMPInstallManager.js @@ -1846,6 +1846,7 @@ mockRequest.prototype = { /** * Creates a new zip file containing a file with the specified data + * * @param zipName The name of the zip file * @param data The data to go inside the zip for the filename entry1.info */ @@ -1911,6 +1912,7 @@ function revertContentSigTestPrefs(previousUrlOverride) { /** * A helper to check that glean metrics have expected counts. + * * @param expectedGleanValues a object that has properties with names set to glean metrics to be checked * and the values are the expected count. Eg { cert_pin_success: 1 }. */ diff --git a/toolkit/mozapps/downloads/DownloadUtils.sys.mjs b/toolkit/mozapps/downloads/DownloadUtils.sys.mjs @@ -157,6 +157,7 @@ export var DownloadUtils = { /** * Helper function that returns a transfer string, a time remaining string, * and a new value of "last seconds". + * * @param aCurrBytes * Number of bytes transferred so far * @param [optional] aMaxBytes @@ -449,6 +450,7 @@ export var DownloadUtils = { /** * Converts a number of seconds to "downloading file opens in X" status. + * * @param aSeconds * Seconds to convert into the time format. * @return status object, example: diff --git a/toolkit/mozapps/extensions/AddonManager.sys.mjs b/toolkit/mozapps/extensions/AddonManager.sys.mjs @@ -273,6 +273,7 @@ async function promiseCallProvider(aProvider, aMethod, ...aArgs) { /** * Gets the currently selected locale for display. + * * @return the selected locale or "en-US" if none is selected */ function getLocale() { @@ -510,6 +511,7 @@ export var AMBrowserExtensionsImport; /** * This is the real manager, kept here rather than in AddonManager to keep its * contents hidden from API users. + * * @class * @lends AddonManager */ @@ -985,6 +987,7 @@ var AddonManagerInternal = { /** * Shuts down the addon manager and all registered providers, this must clean * up everything in order for automated tests to fake restarts. + * * @return Promise{null} that resolves when all providers and dependent modules * have finished shutting down */ @@ -1325,6 +1328,7 @@ var AddonManagerInternal = { /** * Performs a background update check by starting an update for all add-ons * that can be updated. + * * @return Promise{null} Resolves when the background update check is complete * (the resulting addon installations may still be in progress). */ @@ -4043,6 +4047,7 @@ export var AddonManagerPrivate = { /** * This is the public API that UI and developers should be calling. All methods * just forward to AddonManagerInternal. + * * @class */ export var AddonManager = { @@ -4863,6 +4868,7 @@ export class EnvironmentAddonBuilder { /** * Enforces the parameter to a boolean value. + * * @param aValue The input value. * @return {Boolean|Object} If aValue is a boolean or a number, returns its truthfulness * value. Otherwise, return null. @@ -4876,6 +4882,7 @@ export class EnvironmentAddonBuilder { /** * Get the initial set of addons. + * * @returns Promise<void> when the initial load is complete. */ async init() { @@ -5117,6 +5124,7 @@ export class EnvironmentAddonBuilder { /** * Get the addon data in object form. + * * @return Promise<object> containing the addon data. */ async _getActiveAddons() { @@ -5214,6 +5222,7 @@ export class EnvironmentAddonBuilder { /** * Get the currently active theme data in object form. + * * @return Promise<object> containing the active theme data. */ async _getActiveTheme() { diff --git a/toolkit/mozapps/extensions/Blocklist.sys.mjs b/toolkit/mozapps/extensions/Blocklist.sys.mjs @@ -249,6 +249,7 @@ const Utils = { /** * Checks if a version is higher than or equal to the minVersion (if provided) * and lower than or equal to the maxVersion (if provided). + * * @param {string} version * The version to test. * @param {string?} minVersion @@ -273,6 +274,7 @@ const Utils = { /** * Tests if this versionRange matches the item specified, and has a matching * targetApplication id and version. + * * @param {Object} versionRange * The versionRange to check against * @param {string} itemVersion @@ -358,6 +360,7 @@ const Utils = { /** * Create a blocklist URL for the given blockID + * * @param {String} id the blockID to use * @returns {String} the blocklist URL. */ @@ -1493,6 +1496,7 @@ ChromeUtils.defineLazyGetter(lazy, "gAppOS", function () { /** * Logs a string to the error console. + * * @param {string} string * The string to write to the error console.. */ diff --git a/toolkit/mozapps/extensions/internal/AddonRepository.sys.mjs b/toolkit/mozapps/extensions/internal/AddonRepository.sys.mjs @@ -408,6 +408,7 @@ export var AddonRepository = { /** * Clear and delete the AddonRepository database + * * @return Promise{null} resolves when the database is deleted */ _clearCache() { @@ -418,6 +419,7 @@ export var AddonRepository = { /** * Create a ServiceRequest instance. + * * @return ServiceRequest returns a ServiceRequest instance. */ _createServiceRequest() { @@ -1026,6 +1028,7 @@ var AddonDatabase = { /** * Flush any pending I/O on the addons.json file + * * @return: Promise{null} * Resolves when the pending I/O (writing out or deleting * addons.json) completes diff --git a/toolkit/mozapps/extensions/internal/ProductAddonChecker.sys.mjs b/toolkit/mozapps/extensions/internal/ProductAddonChecker.sys.mjs @@ -623,6 +623,7 @@ export const ProductAddonChecker = { export const ProductAddonCheckerTestUtils = { /** * Used to override ServiceRequest calls with a mock request. + * * @param mockRequest The mocked ServiceRequest object. * @param callback Method called with the overridden ServiceRequest. The override * is undone after the callback returns. diff --git a/toolkit/mozapps/extensions/internal/XPIProvider.sys.mjs b/toolkit/mozapps/extensions/internal/XPIProvider.sys.mjs @@ -1774,6 +1774,7 @@ var XPIStates = { /** * Find the highest priority location of an add-on by ID and return the * XPIState. + * * @param {string} aId * The add-on IDa * @param {function} aFilter @@ -1882,7 +1883,6 @@ var XPIStates = { * The name of the add-on location. * @param {string} aId * The ID of the add-on. - * */ removeAddon(aLocation, aId) { logger.debug(`Removing XPIState for ${aLocation}: ${aId}`); diff --git a/toolkit/mozapps/extensions/test/xpcshell/head_addons.js b/toolkit/mozapps/extensions/test/xpcshell/head_addons.js @@ -420,6 +420,7 @@ function checkAddon(id, addon, expected) { * Tests that an add-on does appear in the crash report annotations, if * crash reporting is enabled. The test will fail if the add-on is not in the * annotation. + * * @param aId * The ID of the add-on * @param aVersion @@ -447,6 +448,7 @@ function do_check_in_crash_annotation(aId, aVersion) { * Tests that an add-on does not appear in the crash report annotations, if * crash reporting is enabled. The test will fail if the add-on is in the * annotation. + * * @param aId * The ID of the add-on * @param aVersion diff --git a/toolkit/mozapps/extensions/test/xpcshell/test_XPIStates.js b/toolkit/mozapps/extensions/test/xpcshell/test_XPIStates.js @@ -38,6 +38,7 @@ var lastTimestamp = Date.now(); /** * Helper function to touch a file and then test whether we detect the change. + * * @param XS The XPIState object. * @param aPath File path to touch. * @param aChange True if we should notice the change, False if we shouldn't. diff --git a/toolkit/mozapps/extensions/test/xpinstall/browser_block_fullscreen_prompt.js b/toolkit/mozapps/extensions/test/xpinstall/browser_block_fullscreen_prompt.js @@ -6,6 +6,7 @@ /** * Spawns content task in browser to enter / leave fullscreen + * * @param browser - Browser to use for JS fullscreen requests * @param {Boolean} fullscreenState - true to enter fullscreen, false to leave */ diff --git a/toolkit/mozapps/handling/ContentDispatchChooser.sys.mjs b/toolkit/mozapps/handling/ContentDispatchChooser.sys.mjs @@ -31,6 +31,7 @@ export class nsContentDispatchChooser { * protocol of aURI, we show a permission prompt first. * If the caller has permission and a preferred handler is set, we skip the * dialogs and directly open the handler. + * * @param {nsIHandlerInfo} aHandler - Info about protocol and handlers. * @param {nsIURI} aURI - URI to be handled. * @param {nsIPrincipal} [aPrincipal] - Principal which triggered the load. @@ -123,6 +124,7 @@ export class nsContentDispatchChooser { /** * Get the name of the application set to handle the the protocol. + * * @param {nsIHandlerInfo} aHandler - Info about protocol and handlers. * @returns {string|null} - Human readable handler name or null if the user * is expected to set a handler. @@ -142,6 +144,7 @@ export class nsContentDispatchChooser { /** * Show permission or/and app chooser prompt. + * * @param {nsIHandlerInfo} aHandler - Info about protocol and handlers. * @param {nsIPrincipal} aPrincipal - Principal which triggered the load. * @param {boolean} aHasPermission - Whether the caller has permission to @@ -276,6 +279,7 @@ export class nsContentDispatchChooser { /** * Test if a given principal has the open-protocol-handler permission for a * specific protocol. + * * @param {string} scheme - Scheme of the protocol. * @param {nsIPrincipal} aPrincipal - Principal to test for permission. * @returns {boolean} - true if permission is set, false otherwise. @@ -318,6 +322,7 @@ export class nsContentDispatchChooser { /** * Get open-protocol-handler permission key for a protocol. + * * @param {string} aProtocolScheme - Scheme of the protocol. * @returns {string} - Permission key. */ @@ -333,6 +338,7 @@ export class nsContentDispatchChooser { * Opens a dialog as a SubDialog on tab level. * If we don't have a BrowsingContext or tab level dialogs are not supported, * we will fallback to a standalone window. + * * @param {string} aDialogURL - URL of the dialog to open. * @param {Object} aDialogArgs - Arguments passed to the dialog. * @param {BrowsingContext} [aBrowsingContext] - BrowsingContext associated @@ -399,6 +405,7 @@ export class nsContentDispatchChooser { /** * Update the open-protocol-handler permission for the site which triggered * the dialog. Sites with this permission may skip this dialog. + * * @param {nsIPrincipal} aPrincipal - subject to update the permission for. * @param {string} aScheme - Scheme of protocol to allow. * @param {boolean} aAllow - Whether to set / unset the permission. @@ -439,6 +446,7 @@ export class nsContentDispatchChooser { /** * Determine if we can use a principal to store permissions. + * * @param {nsIPrincipal} aPrincipal - Principal to test. * @returns {boolean} - true if we can store permissions, false otherwise. */ diff --git a/toolkit/mozapps/handling/content/appChooser.js b/toolkit/mozapps/handling/content/appChooser.js @@ -293,6 +293,7 @@ let dialog = { /** * Update the handler info to reflect the user choice. + * * @param {boolean} skipAsk - Whether we should persist the application * choice and skip asking next time. */ diff --git a/toolkit/mozapps/handling/content/permissionDialog.js b/toolkit/mozapps/handling/content/permissionDialog.js @@ -78,6 +78,7 @@ let dialog = { /** * We only show the website address if the origin is not user-readable * in the address bar. + * * @returns {boolean} - true if principal is top level and user-readable, * false otherwise. * If the triggering principal is null this method always returns false. @@ -184,6 +185,7 @@ let dialog = { * It's usually the prePath of the site that wants to navigate to * the external protocol, though we use the OS syntax for paths if * the request comes from `file://`. + * * @returns {string|null} - text to show, or null if we can't derive an * readable string from the triggering principal. */ diff --git a/toolkit/mozapps/update/AppUpdater.sys.mjs b/toolkit/mozapps/update/AppUpdater.sys.mjs @@ -890,6 +890,7 @@ AppUpdater.STATUS = { /** * Logs a string to the error console. If enabled, also logs to the update * messages file. + * * @param string * The string to write to the error console. */ diff --git a/toolkit/mozapps/update/UpdateLog.sys.mjs b/toolkit/mozapps/update/UpdateLog.sys.mjs @@ -170,6 +170,7 @@ deactivateUpdateLogFile(); /** * Logs a string to the error console. + * * @param string * The string to write to the error console. */ diff --git a/toolkit/mozapps/update/UpdateService.sys.mjs b/toolkit/mozapps/update/UpdateService.sys.mjs @@ -881,6 +881,7 @@ function getCanUseBits(transient = true) { /** * Logs a string to the error console. If enabled, also logs to the update * messages file. + * * @param string * The string to write to the error console. */ @@ -891,6 +892,7 @@ function LOG(string) { /** * Gets the specified directory at the specified hierarchy under the * update root directory and creates it if it doesn't exist. + * * @param pathArray * An array of path components to locate beneath the directory * specified by |key| @@ -963,6 +965,7 @@ function getInstallDirRoot() { /** * Gets the file at the specified hierarchy under the update root directory. + * * @param pathArray * An array of path components to locate beneath the directory * specified by |key|. The last item in this array must be the @@ -998,6 +1001,7 @@ function maybeMapErrorCode(code) { /** * Returns human readable status text from the updates.properties bundle * based on an error code + * * @param code * The error code to look up human readable status text for * @param defaultCode @@ -1033,6 +1037,7 @@ function getStatusTextFromCode(code, defaultCode) { * Get the Ready Update directory. This is the directory that an update * should reside in after download has completed but before it has been * installed and cleaned up. + * * @return The ready updates directory, as a nsIFile object */ function getReadyUpdateDir() { @@ -1043,6 +1048,7 @@ function getReadyUpdateDir() { * Get the Downloading Update directory. This is the directory that an update * should reside in during download. Once download is completed, it will be * moved to the Ready Update directory. + * * @return The downloading update directory, as a nsIFile object */ function getDownloadingUpdateDir() { @@ -1138,6 +1144,7 @@ function onStateAccessSuccess() { /** * Reads the update state from the update.status file in the specified * directory. + * * @param dir * The dir to look for an update.status file in * @return The status value of the update. @@ -1538,6 +1545,7 @@ async function cleanupActiveUpdates() { /** * Writes a string of text to a file. A newline will be appended to the data * written to the file. This function only works with ASCII text. + * * @param file An nsIFile indicating what file to write to. * @param text A string containing the text to write to the file. * @throws Errors from file stream will be propagated. @@ -1779,6 +1787,7 @@ function handleUpdateFailure(update) { /** * Return the first UpdatePatch with the given type. + * * @param update * A nsIUpdate object to search through for a patch of the desired * type. @@ -2311,6 +2320,7 @@ class Update { /** * Implements nsIUpdate + * * @param update * An <update> element to initialize this object with * @throws if the update contains no patches @@ -2690,6 +2700,7 @@ export class UpdateService { /** * UpdateService * A Service for managing the discovery and installation of software updates. + * * @constructor */ constructor() { @@ -2738,6 +2749,7 @@ export class UpdateService { /** * Handle Observer Service notifications + * * @param subject * The subject of the notification * @param topic @@ -3481,6 +3493,7 @@ export class UpdateService { /** * Notified when a timer fires + * * @param _timer * The timer that fired */ @@ -3509,6 +3522,7 @@ export class UpdateService { /** * Checks for updates in the background. + * * @param isNotify * Whether or not a background update check was initiated by the * application update timer notification. @@ -3715,6 +3729,7 @@ export class UpdateService { * Determine the update from the specified updates that should be offered. * If both valid major and minor updates are available the minor update will * be offered. + * * @param updates * An array of available nsIUpdate items * @return The nsIUpdate to offer. @@ -3893,6 +3908,7 @@ export class UpdateService { /** * Determine which of the specified updates should be installed and begin the * download/installation process or notify the user about the update. + * * @param updates * An array of available updates */ @@ -4591,6 +4607,7 @@ export class UpdateManager { /** * A service to manage active and past updates. + * * @constructor */ constructor() { @@ -4712,6 +4729,7 @@ export class UpdateManager { /** * Loads an updates.xml formatted file into an array of nsIUpdate items. + * * @param fileName * The file name in the updates directory to load. * @return The array of nsIUpdate items held in the file. @@ -4884,6 +4902,7 @@ export class UpdateManager { /** * Serializes an array of updates to an XML file or removes the file if the * array length is 0. + * * @param updates * An array of nsIUpdate objects * @param fileName @@ -5933,6 +5952,7 @@ class Downloader { /** * Manages the download of updates + * * @param background * Whether or not this downloader is operating in background * update mode. @@ -6037,6 +6057,7 @@ class Downloader { /** * Select the patch to use given the current state of updateDir and the given * set of update patches. + * * @param update * A nsIUpdate object to select a patch from * @return A nsIUpdatePatch object to download @@ -6305,6 +6326,7 @@ class Downloader { /** * Download and stage the given update. + * * @param update * A nsIUpdate object to download a patch for. Cannot be null. */ @@ -6654,6 +6676,7 @@ class Downloader { /** * When the async request begins + * * @param request * The nsIRequest object for the transfer */ @@ -6681,6 +6704,7 @@ class Downloader { /** * When new data has been downloaded + * * @param request * The nsIRequest object for the transfer * @param progress @@ -6734,6 +6758,7 @@ class Downloader { /** * When we have new status text + * * @param request * The nsIRequest object for the transfer * @param status @@ -6755,6 +6780,7 @@ class Downloader { /** * When data transfer ceases + * * @param request * The nsIRequest object for the transfer * @param status diff --git a/toolkit/mozapps/update/UpdateServiceStub.sys.mjs b/toolkit/mozapps/update/UpdateServiceStub.sys.mjs @@ -511,6 +511,7 @@ function cleanupDir(dir, recurse) { /** * Logs a string to the error console. + * * @param string * The string to write to the error console. */ diff --git a/toolkit/mozapps/update/content/history.js b/toolkit/mozapps/update/content/history.js @@ -75,6 +75,7 @@ var gUpdateHistory = { /** * Formats a date into human readable form + * * @param seconds * A date in seconds since 1970 epoch * @returns A human readable date string diff --git a/toolkit/mozapps/update/tests/data/shared.js b/toolkit/mozapps/update/tests/data/shared.js @@ -361,6 +361,7 @@ function writeFile(aFile, aText) { /** * Attempts to remove a file. Does not fail if the file does not exist. + * * @param file * The `nsIFile` to remove. */ diff --git a/tools/profiler/tests/ProfilerTestUtils.sys.mjs b/tools/profiler/tests/ProfilerTestUtils.sys.mjs @@ -287,6 +287,7 @@ export var ProfilerTestUtils = { /** * This function pauses the profiler before getting the profile. Then after * getting the data, the profiler is stopped, and all profiler data is removed. + * * @returns {Promise<Profile>} */ async stopNowAndGetProfile() { @@ -310,6 +311,7 @@ export var ProfilerTestUtils = { * This function ensures there's at least one sample, then pauses the profiler * before getting the profile. Then after getting the data, the profiler is * stopped, and all profiler data is removed. + * * @returns {Promise<Profile>} */ async waitSamplingAndStopAndGetProfile() { diff --git a/tools/profiler/tests/shared-head.js b/tools/profiler/tests/shared-head.js @@ -35,6 +35,7 @@ async function wait(time) { * so it is licence MIT and: * Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com). * See the full license in https://raw.githubusercontent.com/sindresorhus/escape-string-regexp/main/license. + * * @param {string} string The string to be escaped * @returns {string} The result */ diff --git a/tools/profiler/tests/xpcshell/test_feature_fileioall.js b/tools/profiler/tests/xpcshell/test_feature_fileioall.js @@ -99,6 +99,7 @@ add_task(async () => { /** * Start the profiler and get FileIO markers. + * * @param {TestConfig} * @returns {Profile} */ diff --git a/uriloader/exthandler/ExtHandlerService.sys.mjs b/uriloader/exthandler/ExtHandlerService.sys.mjs @@ -561,6 +561,7 @@ HandlerService.prototype = { /** * Private method to inject stored handler information into an nsIHandlerInfo * instance. + * * @param handlerInfo the nsIHandlerInfo instance to write to * @param storedHandlers the stored handlers * @param keepPreferredApp whether to keep the handlerInfo's diff --git a/uriloader/exthandler/tests/mochitest/browser_protocol_ask_dialog_permission.js b/uriloader/exthandler/tests/mochitest/browser_protocol_ask_dialog_permission.js @@ -52,6 +52,7 @@ const NULL_PRINCIPAL_SCHEME = Services.scriptSecurityManager /** * Get the open protocol handler permission key for a given protocol scheme. + * * @param {string} aProtocolScheme - Scheme of protocol to construct permission * key with. */ @@ -84,6 +85,7 @@ function initTestHandlers() { /** * Update whether the protocol handler dialog is shown for our test protocol + * handler. + * * @param {string} scheme - Scheme of the protocol to change the ask state for. * @param {boolean} ask - true => show dialog, false => skip dialog. */ @@ -96,6 +98,7 @@ function updateAlwaysAsk(scheme, ask) { /** * Test whether the protocol handler dialog is set to show for our * test protocol + handler. + * * @param {string} scheme - Scheme of the protocol to test the ask state for. * @param {boolean} ask - true => show dialog, false => skip dialog. */ @@ -109,6 +112,7 @@ function testAlwaysAsk(scheme, ask) { /** * Triggers the load via a server redirect. + * * @param {string} serverRedirect - The redirect type. */ function useServerRedirect(serverRedirect) { @@ -138,6 +142,7 @@ function useServerRedirect(serverRedirect) { /** * Triggers the load with a specific principal or the browser's current * principal. + * * @param {nsIPrincipal} [principal] - Principal to use to trigger the load. */ function useTriggeringPrincipal(principal = undefined) { @@ -153,6 +158,7 @@ function useTriggeringPrincipal(principal = undefined) { /** * Navigates to a test URL with the given protocol scheme and waits for the * result. + * * @param {MozBrowser} browser - Browser to navigate. * @param {string} scheme - Scheme of the test url. e.g. irc * @param {Object} [options] - Test options. @@ -320,6 +326,7 @@ async function testOpenProto( /** * Inspects the checkbox state and interacts with it. + * * @param {dialog} dialogEl * @param {string} dialogType - String identifier of dialog type. * Either "permission" or "chooser". @@ -377,6 +384,7 @@ async function testCheckbox( /** * Wait for the test handler to be opened. + * * @param {MozBrowser} browser - The browser the load should occur in. * @param {string} scheme - Scheme which triggered the handler to open. */ @@ -390,6 +398,7 @@ function waitForHandlerURL(browser, scheme) { /** * Test for open-protocol-handler permission. + * * @param {nsIPrincipal} principal - The principal to test the permission on. * @param {string} scheme - Scheme to generate permission key. * @param {boolean} hasPerm - Whether we expect the princial to set the @@ -407,6 +416,7 @@ function testPermission(principal, scheme, hasPerm) { /** * Get the checkbox element of the dialog used to remember the handler choice or * store the permission. + * * @param {SubDialog} dialog - Protocol handler dialog embedded in a SubDialog. * @param {string} dialogType - Type of the dialog which holds the checkbox. * @returns {HTMLInputElement} - Checkbox of the dialog. @@ -435,6 +445,7 @@ function getDialogType(dialog) { /** * Exit a protocol handler SubDialog and wait for it to be fully closed. + * * @param {MozBrowser} browser - Browser element of the tab where the dialog is * shown. * @param {SubDialog} dialog - SubDialog object which holds the protocol handler diff --git a/uriloader/exthandler/tests/mochitest/head.js b/uriloader/exthandler/tests/mochitest/head.js @@ -184,6 +184,7 @@ async function waitForSubDialog(browser, url, state) { /** * Wait for protocol permission dialog open/close. + * * @param {MozBrowser} browser - Browser element the dialog belongs to. * @param {boolean} state - true: dialog open, false: dialog close * @returns {Promise<SubDialog>} - Returns a promise which resolves with the @@ -199,6 +200,7 @@ async function waitForProtocolPermissionDialog(browser, state) { /** * Get the dialog element which is a child of the SubDialogs browser frame. + * * @param {SubDialog} subDialog - Dialog to get the dialog element for. */ function getDialogElementFromSubDialog(subDialog) { @@ -209,12 +211,12 @@ function getDialogElementFromSubDialog(subDialog) { /** * Accept the next protocol permission dialog. + * * @param {MozBrowser} browser - Browser element the dialog belongs to. * @returns {Promise} - Returns a promise which resolves once the dialog has * been accepted. * * Note: This function will bypass the security delay. - * */ async function acceptNextProtocolPermissionDialog(browser) { let dialog = await waitForProtocolPermissionDialog(browser, true); @@ -234,6 +236,7 @@ async function acceptNextProtocolPermissionDialog(browser) { /** * Wait for protocol app chooser dialog open/close. + * * @param {MozBrowser} browser - Browser element the dialog belongs to. * @param {boolean} state - true: dialog open, false: dialog close * @returns {Promise<SubDialog>} - Returns a promise which resolves with the @@ -362,6 +365,7 @@ const EXT_PROTO_URI_MAILTO = "mailto:test@example.com"; /** * Creates and iframe and navigate to an external protocol from the iframe. + * * @param {MozBrowser} browser - Browser to spawn iframe in. * @param {string} sandboxAttr - Sandbox attribute value for the iframe. * @param {'trustedClick'|'untrustedClick'|'trustedLocationAPI'|'untrustedLocationAPI'|'frameSrc'|'frameSrcRedirect'} triggerMethod @@ -486,6 +490,7 @@ async function navigateExternalProtoFromIframe( /** * Wait for the sandbox error message which is shown in the web console when an * external protocol navigation from a sandboxed context is blocked. + * * @returns {Promise} - Promise which resolves once message has been logged. */ function waitForExtProtocolSandboxError() { @@ -510,6 +515,7 @@ function waitForExtProtocolSandboxError() { /** * Run the external protocol sandbox test using iframes. + * * @param {Object} options * @param {boolean} options.blocked - Whether the navigation should be blocked. * @param {string} options.sandbox - See {@link navigateExternalProtoFromIframe}.