commit caf2698f2e35b2218c25b585a51df396649bb968 parent fd62657728ec5007c2bb30b9acd620f56683facd Author: Mark Banner <standard8@mozilla.com> Date: Mon, 22 Dec 2025 12:39:07 +0000 Bug 2004680 - Fix ESLint rule jsdoc/check-tag-names issues in browser. r=firefox-desktop-core-reviewers ,sessionstore-reviewers,tabbrowser-reviewers,omc-reviewers,home-newtab-reviewers,Gijs,nbarrett,mconley,emcminn,sthompson Differential Revision: https://phabricator.services.mozilla.com/D275755 Diffstat:
33 files changed, 122 insertions(+), 128 deletions(-)
diff --git a/browser/actors/AboutReaderParent.sys.mjs b/browser/actors/AboutReaderParent.sys.mjs @@ -259,8 +259,9 @@ export class AboutReaderParent extends JSWindowActorParent { * * @param url The article URL. * @param browser The browser where the article is currently loaded. - * @return {Promise} - * @resolves JS object representing the article, or null if no article is found. + * @return {Promise<?object>} + * Resolves to the JS object representing the article, or null if no article + * is found. */ async _getArticle(url) { return lazy.ReaderMode.downloadAndParseDocument(url).catch(e => { diff --git a/browser/actors/FormValidationParent.sys.mjs b/browser/actors/FormValidationParent.sys.mjs @@ -143,8 +143,8 @@ export class FormValidationParent extends JSWindowActorParent { * Shows the form validation popup at a specified position or updates the * messaging and position if the popup is already displayed. * - * @aBrowser - Browser element that requests the popup. - * @aPanelData - Object that contains popup information + * @param {MozBrowser} aBrowser - Browser element that requests the popup. + * @param {object} aPanelData - Object that contains popup information * aPanelData stucture detail: * screenRect - the screen rect of the target element. * position - popup positional string constants. diff --git a/browser/actors/PromptParent.sys.mjs b/browser/actors/PromptParent.sys.mjs @@ -130,10 +130,8 @@ export class PromptParent extends JSWindowActorParent { * @param {object} args * The arguments passed up from the BrowsingContext to be passed * directly to the modal prompt. - * @return {Promise} - * Resolves when the modal prompt is dismissed. - * @resolves {object} - * The arguments returned from the modal prompt. + * @return {Promise<object>} + * Resolves with the arguments returned from the modal prompt. */ async openPromptWithTabDialogBox(args) { const COMMON_DIALOG = "chrome://global/content/commonDialog.xhtml"; diff --git a/browser/actors/ScreenshotsComponentChild.sys.mjs b/browser/actors/ScreenshotsComponentChild.sys.mjs @@ -221,8 +221,8 @@ export class ScreenshotsComponentChild extends JSWindowActorChild { /** * Resolves when the document is ready to have an overlay injected into it. * - * @returns {Promise} - * @resolves {boolean} true when document is ready or rejects + * @returns {Promise<boolean>} + * Resolves to true when document is ready or rejects. */ documentIsReady() { const document = this.document; diff --git a/browser/base/content/browser.js b/browser/base/content/browser.js @@ -3353,12 +3353,12 @@ const DynamicShortcutTooltip = { /** * Extracts linkNode and href for the current click target. * + * Note: linkNode will be null if the click wasn't on an anchor + * element (or XLink). + * * @param event * The click event. * @return [href, linkNode]. - * - * @note linkNode will be null if the click wasn't on an anchor - * element (or XLink). */ function hrefAndLinkNodeForClickEvent(event) { function isHTMLLink(aNode) { @@ -3408,11 +3408,12 @@ function hrefAndLinkNodeForClickEvent(event) { /** * Called whenever the user clicks in the content area. * + * Note: the default event is prevented if the click is handled. + * * @param event * The click event. * @param isPanelClick * Whether the event comes from an extension panel. - * @note default event is prevented if the click is handled. */ function contentAreaClick(event, isPanelClick) { if (!event.isTrusted || event.defaultPrevented || event.button != 0) { diff --git a/browser/base/content/test/general/head.js b/browser/base/content/test/general/head.js @@ -137,9 +137,8 @@ function promiseWaitForEvent( * @param aWindow * The window to focus and wait for. * - * @return {Promise} - * @resolves When the window is focused. - * @rejects Never. + * @returns {Promise<void>} + * Resolved when the window is focused. */ function promiseWaitForFocus(aWindow) { return new Promise(resolve => { diff --git a/browser/base/content/test/plugins/head.js b/browser/base/content/test/plugins/head.js @@ -88,9 +88,8 @@ function promiseForPluginInfo(aId, aBrowser) { * @param aWindow * The window to focus and wait for. * - * @return {Promise} - * @resolves When the window is focused. - * @rejects Never. + * @returns {Promise<void>} + * Resolved when the window is focused. */ function promiseWaitForFocus(aWindow) { return new Promise(resolve => { diff --git a/browser/base/content/test/referrer/head.js b/browser/base/content/test/referrer/head.js @@ -137,8 +137,8 @@ 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. + * @returns {Promise<string>} + * Resolves to the text of the (trimmed) referrer when extracted. */ function referrerResultExtracted(aWindow) { return SpecialPowers.spawn(aWindow.gBrowser.selectedBrowser, [], function () { @@ -150,8 +150,8 @@ 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. + * @returns {Promise<void>} + * Resolves when the window is loaded. */ function delayedStartupFinished(aWindow) { return new Promise(function (resolve) { @@ -168,8 +168,8 @@ 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. + * @returns {Promise} + * Resolves to the tab once it's loaded. */ function someTabLoaded() { return BrowserTestUtils.waitForNewTab(gTestWindow.gBrowser, null, true); @@ -178,8 +178,8 @@ 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. + * @returns {Promise<Window>} + * Resolves to the new window once it's open and loaded. */ function newWindowOpened() { return TestUtils.topicObserved("browser-delayed-startup-finished").then( @@ -192,8 +192,8 @@ function newWindowOpened() { * * @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} - * @resolves With the menu popup when the context menu is open. + * @returns {Promise} + * Resolves with the menu popup when the context menu is open. */ function contextMenuOpened(aWindow, aLinkId) { let popupShownPromise = BrowserTestUtils.waitForEvent( @@ -222,8 +222,8 @@ 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. + * @returns {Promise<void>} + * Resolves when the source url for this test case is loaded. */ function referrerTestCaseLoaded(aTestNumber, aParams) { let test = getReferrerTest(aTestNumber); diff --git a/browser/base/content/test/siteIdentity/head.js b/browser/base/content/test/siteIdentity/head.js @@ -59,9 +59,9 @@ function isSecurityState(browser, expectedState) { * Test the state of the identity box and control center to make * sure they are correctly showing the expected mixed content states. * - * @note The checks are done synchronously, but new code should wait on the - * returned Promise object to ensure the identity panel has closed. - * Bug 1221114 is filed to fix the existing code. + * Note: The checks are done synchronously, but new code should wait on the + * returned Promise object to ensure the identity panel has closed. + * Bug 1221114 is filed to fix the existing code. * * @param tabbrowser * @param Object states @@ -72,8 +72,8 @@ function isSecurityState(browser, expectedState) { * passiveLoaded: true|false, * } * - * @return {Promise} - * @resolves When the operation has finished and the identity panel has closed. + * @returns {Promise<void>} + * Resolves when the operation has finished and the identity panel has closed. */ async function assertMixedContentBlockingState(tabbrowser, states = {}) { if ( diff --git a/browser/base/content/test/tabPrompts/browser_multiplePrompts.js b/browser/base/content/test/tabPrompts/browser_multiplePrompts.js @@ -10,8 +10,8 @@ * @param {number} promptCount How many dialogs we expected to have been * opened. * - * @return {Promise} - * @resolves {undefined} Once the dialogs have all been closed. + * @returns {Promise<void>} + * Resolves once the dialogs have all been closed. */ async function closeDialogs(tab, dialogCount) { let dialogElementsCount = dialogCount; diff --git a/browser/base/content/test/tabcrashed/browser_multipleCrashedTabs.js b/browser/base/content/test/tabcrashed/browser_multipleCrashedTabs.js @@ -18,9 +18,8 @@ const PAGE_3 = "http://example.net"; * The browser to check. * @param expected (Boolean) * True if we expect the "multiple" state to be set. - * @returns Promise - * @resolves undefined - * When the check has completed. + * @returns {Promise<void>} + * Resolves when the check has completed. */ async function assertShowingMultipleUI(browser, expected) { let showingMultiple = await SpecialPowers.spawn(browser, [], async () => { @@ -49,9 +48,8 @@ function snapshotCount(snapshot) { * * @param tab (<xul:tab>) * The tab to switch to and crash. - * @returns Promise - * @resolves undefined - * When about:tabcrashed is loaded. + * @returns {Promise<void>} + * Resolves when about:tabcrashed is loaded. */ async function switchToAndCrashTab(tab) { let browser = tab.linkedBrowser; diff --git a/browser/base/content/test/webrtc/browser_global_mute_toggles.js b/browser/base/content/test/webrtc/browser_global_mute_toggles.js @@ -39,8 +39,8 @@ add_setup(async function () { * @param {<xul:browser>} browser - The browser running in the content process * to be monitored. * @param {boolean} isMuted - True if the muted topic should be fired. - * @return {Promise} - * @resolves {undefined} When the notification fires. + * @returns {Promise<void>} + * Resovles when the notification fires. */ function waitForCameraMuteState(browser, isMuted) { let topic = isMuted ? "getUserMedia:muteVideo" : "getUserMedia:unmuteVideo"; @@ -59,8 +59,8 @@ function waitForCameraMuteState(browser, isMuted) { * @param {<xul:browser>} browser - The browser running in the content process * to be monitored. * @param {boolean} isMuted - True if the muted topic should be fired. - * @return {Promise} - * @resolves {undefined} When the notification fires. + * @returns {Promise<void>} + * Resolves when the notification fires. */ function waitForMicrophoneMuteState(browser, isMuted) { let topic = isMuted ? "getUserMedia:muteAudio" : "getUserMedia:unmuteAudio"; diff --git a/browser/base/content/test/webrtc/browser_notification_silencing.js b/browser/base/content/test/webrtc/browser_notification_silencing.js @@ -26,8 +26,8 @@ const TEST_PAGE = TEST_ROOT + "get_user_media.html"; * * @param {<xul:browser>} aBrowser - The window to run the test on. This browser * should have TEST_PAGE loaded. - * @return Promise - * @resolves undefined - When the test on the browser is complete. + * @returns {Promise<void>} + * Resolves when the test on the browser is complete. */ async function testNotificationSilencing(aBrowser) { let hasIndicator = Services.wm diff --git a/browser/base/content/test/webrtc/browser_tab_switch_warning.js b/browser/base/content/test/webrtc/browser_tab_switch_warning.js @@ -28,8 +28,8 @@ const CTRL_TAB_RUO_PREF = "browser.ctrlTab.sortByRecentlyUsed"; * * @param {boolean} doFirstTabSwitch - True if this function should take * care of doing the "freebie" tab switch for you. - * @return {Promise} - * @resolves {undefined} - Once the simulation is set up. + * @returns {Promise<void>} + * Resolves once the simulation is set up. */ async function pretendToShareDisplay(doFirstTabSwitch) { Assert.equal( @@ -59,8 +59,8 @@ async function pretendToShareDisplay(doFirstTabSwitch) { * @param {DOM Window} aWindow - The window that we're simulating sharing. * @param {boolean} doFirstTabSwitch - True if this function should take * care of doing the "freebie" tab switch for you. Defaults to true. - * @return {Promise} - * @resolves {undefined} - Once the simulation is set up. + * @returns {Promise<void>} + * Resolves once the simulation is set up. */ async function pretendToShareWindow(aWindow, doFirstTabSwitch = true) { // Poke into webrtcUI so that it thinks that the current browser @@ -82,8 +82,8 @@ async function pretendToShareWindow(aWindow, doFirstTabSwitch = true) { * * @param {boolean} doFirstTabSwitch - True if this function should take * care of doing the "freebie" tab switch for you. Defaults to true. - * @return {Promise} - * @resolves {undefined} - Once the simulation is set up. + * @returns {Promise<void>} + * Resolves once the simulation is set up. */ async function pretendToShareScreen(doFirstTabSwitch = true) { // Poke into webrtcUI so that it thinks that the current screen is being @@ -101,8 +101,8 @@ async function pretendToShareScreen(doFirstTabSwitch = true) { * 1. Switch back to the first tab if it's not already selected. * 2. Check if the tab switch warning panel is open, and if so, close it. * - * @return {Promise} - * @resolves {undefined} - Once the state is reset. + * @returns {Promise<void>} + * Resolves once the state is reset. */ async function resetDisplaySharingState() { let firstTabBC = gBrowser.browsers[0].browsingContext; @@ -125,8 +125,8 @@ async function resetDisplaySharingState() { * Checks to make sure that a tab switch warning doesn't show * within WARNING_PANEL_TIMEOUT_MS milliseconds. * - * @return {Promise} - * @resolves {undefined} - Once the check is complete. + * @returns {Promise<void>} + * Resolves once the check is complete. */ async function ensureNoWarning() { let timerExpired = false; @@ -167,8 +167,8 @@ async function ensureNoWarning() { * a particular tab. * * @param {<xul:tab>} tab - The tab that the warning should be anchored to. - * @return {Promise} - * @resolves {undefined} - Once the check is complete. + * @returns {Promise<void>} + * Resolves once the check is complete. */ async function ensureWarning(tab) { let popupShowingEvent = await BrowserTestUtils.waitForEvent( diff --git a/browser/base/content/test/webrtc/head.js b/browser/base/content/test/webrtc/head.js @@ -1310,8 +1310,8 @@ async function runTests(tests, options = {}) { * @param {boolean} remember - True to persist the permission to the * SitePermissions database as SitePermissions.SCOPE_PERSISTENT. Note that * callers are responsible for clearing this persistent permission. - * @return {Promise} - * @resolves {undefined} - Once the sharing is complete. + * @returns {Promise<void>} + * Resolves once sharing is complete. */ async function shareDevices( browser, diff --git a/browser/base/content/test/zoom/browser_zoom_commands.js b/browser/base/content/test/zoom/browser_zoom_commands.js @@ -18,8 +18,7 @@ const TEST_PAGE_URL = * The keys are "enlarge", "reduce" and "reset" for readability, * and internally this function maps those keys to the appropriate * commands. - * @returns Promise - * @resolves undefined + * @returns {Promise<void>} */ async function waitForCommandEnabledState(expectedState) { const COMMAND_MAP = { diff --git a/browser/components/asrouter/modules/ASRouter.sys.mjs b/browser/components/asrouter/modules/ASRouter.sys.mjs @@ -2325,7 +2325,7 @@ export class _ASRouter { * recursion. we call this from loadMessagesFromAllProviders in order to * fire the messagesLoaded trigger. * @returns {Promise<object>} - * @resolves {message} an object with the routed message + * Resolves to an object with the routed message. */ async sendTriggerMessage( { browser, ...trigger }, diff --git a/browser/components/downloads/DownloadsCommon.sys.mjs b/browser/components/downloads/DownloadsCommon.sys.mjs @@ -579,11 +579,11 @@ export var DownloadsCommon = { * @param options.useSystemDefault * Optional value indicating how to handle launching this download, * this call only. Will override the associated mimeInfo.preferredAction - * @return {Promise} - * @resolves When the instruction to launch the file has been - * successfully given to the operating system or handled internally - * @rejects JavaScript exception if there was an error trying to launch - * the file. + * @returns {Promise<void>} + * Resolves when the instruction to launch the file has been successfully + * given to the operating system or handled internally. + * @rejects + * With a JavaScript exception if there was an error trying to launch the file. */ async openDownload(download, options) { // some download objects got serialized and need reconstituting @@ -663,12 +663,12 @@ export var DownloadsCommon = { * - "chooseOpen" to offer "open" and "confirmBlock". * } * - * @return {Promise} - * @resolves String representing the action that should be executed: - * - "open" to allow the download and open the file. - * - "unblock" to allow the download without opening the file. - * - "confirmBlock" to delete the blocked data permanently. - * - "cancel" to do nothing and cancel the operation. + * @returns {Promise<string>} + * Resolves to a string representing the action that should be executed: + * - "open" to allow the download and open the file. + * - "unblock" to allow the download without opening the file. + * - "confirmBlock" to delete the blocked data permanently. + * - "cancel" to do nothing and cancel the operation. */ async confirmUnblockDownload({ verdict, @@ -1186,7 +1186,7 @@ const DownloadsViewPrototype = { * @param download * Download object that was just added. * - * @note Subclasses should override this and still call the base method. + * Note: Subclasses should override this and still call the base method. */ onDownloadAdded(download) { this._oldDownloadStates.set( @@ -1202,7 +1202,7 @@ const DownloadsViewPrototype = { * * The onDownloadChanged notification will always be sent afterwards. * - * @note Subclasses should override this. + * Note: Subclasses should override this. */ onDownloadStateChanged() { throw Components.Exception("", Cr.NS_ERROR_NOT_IMPLEMENTED); @@ -1215,7 +1215,7 @@ const DownloadsViewPrototype = { * Note that progress notification changes are throttled at the Downloads.sys.mjs * API level, and there is no throttling mechanism in the front-end. * - * @note Subclasses should override this and still call the base method. + * Note: Subclasses should override this and still call the base method. */ onDownloadChanged(download) { let oldState = this._oldDownloadStates.get(download); @@ -1234,7 +1234,7 @@ const DownloadsViewPrototype = { * @param download * Download object that is being removed. * - * @note Subclasses should override this. + * Note: Subclasses should override this. */ onDownloadRemoved(download) { this._oldDownloadStates.delete(download); @@ -1244,7 +1244,7 @@ const DownloadsViewPrototype = { * Private function used to refresh the internal properties being sent to * each registered view. * - * @note Subclasses should override this. + * Note: Subclasses should override this. */ _refreshProperties() { throw Components.Exception("", Cr.NS_ERROR_NOT_IMPLEMENTED); @@ -1253,7 +1253,7 @@ const DownloadsViewPrototype = { /** * Private function used to refresh an individual view. * - * @note Subclasses should override this. + * Note: Subclasses should override this. */ _updateView() { throw Components.Exception("", Cr.NS_ERROR_NOT_IMPLEMENTED); diff --git a/browser/components/downloads/content/downloads.js b/browser/components/downloads/content/downloads.js @@ -231,7 +231,7 @@ var DownloadsPanel = { /** * Indicates whether the panel is showing. * - * @note this includes the hiding state. + * Note: this includes the hiding state. */ get isPanelShowing() { return this._waitingDataForOpen || this.panel.state != "closed"; diff --git a/browser/components/downloads/test/browser/head.js b/browser/components/downloads/test/browser/head.js @@ -439,9 +439,8 @@ function openLibrary(aLeftPaneRoot) { * @param aDownload * The Download object to wait upon. * - * @return {Promise} - * @resolves When the download has reached its progress. - * @rejects Never. + * @returns {Promise<void>} + * Resolves when the download has reached its progress. */ function promiseDownloadHasProgress(aDownload, progress) { return new Promise(resolve => { diff --git a/browser/components/screenshots/fileHelpers.mjs b/browser/components/screenshots/fileHelpers.mjs @@ -274,9 +274,9 @@ function appendFiltersForContentType( * containing all the data used within this method. * @param win * The window used for opening the file picker - * @return Promise - * @resolve a boolean. When true, it indicates that the file picker dialog - * is accepted. + * @returns {Promise<boolean>} + * Resolves when the dialog is closed. When resolved to true, it indicates that + * the file picker dialog is accepted. */ function promiseTargetFile(aFpP, win) { return (async function () { diff --git a/browser/components/sessionstore/test/browser_354894_perwindowpb.js b/browser/components/sessionstore/test/browser_354894_perwindowpb.js @@ -9,7 +9,7 @@ * working. * * @see https://bugzilla.mozilla.org/show_bug.cgi?id=354894 - * @note It is implicitly tested that restoring the last window works when + * Note: It is implicitly tested that restoring the last window works when * non-browser windows are around. The "Run Tests" window as well as the main * browser window (wherein the test code gets executed) won't be considered * browser windows. To achiveve this said main browser window has its windowtype @@ -17,10 +17,10 @@ * This is crucial, because otherwise there would be two browser windows around, * said main test window and the one opened by the tests, and hence the new * logic wouldn't be executed at all. - * @note Mac only tests the new notifications, as restoring the last window is + * Note: Mac only tests the new notifications, as restoring the last window is * not enabled on that platform (platform shim; the application is kept running * although there are no windows left) - * @note There is a difference when closing a browser window with + * Note: There is a difference when closing a browser window with * BrowserCommands.tryToCloseWindow() as opposed to close(). The former will make * nsSessionStore restore a window next time it gets a chance and will post * notifications. The latter won't. @@ -210,7 +210,7 @@ function closeWindowForRestoration(win) { /** * Normal in-session restore * - * @note: Non-Mac only + * Note: Non-Mac only * * Should do the following: * 1. Open a new browser window @@ -260,7 +260,7 @@ add_task(async function test_open_close_normal() { /** * PrivateBrowsing in-session restore * - * @note: Non-Mac only + * Note: Non-Mac only * * Should do the following: * 1. Open a new browser window A @@ -321,7 +321,7 @@ add_task(async function test_open_close_private_browsing() { * Open some popup window to check it isn't restored. Instead nothing at all * should be restored * - * @note: Non-Mac only + * Note: Non-Mac only * * Should do the following: * 1. Open a popup @@ -402,7 +402,7 @@ add_task(async function test_open_close_only_popup() { * Open some windows and do undoCloseWindow. This should prevent any * restoring later in the test * - * @note: Non-Mac only + * Note: Non-Mac only * * Should do the following: * 1. Open two browser windows and close them again @@ -461,7 +461,7 @@ add_task(async function test_open_close_restore_from_popup() { /** * Test if closing can be denied on Mac. * - * @note: Mac only + * Note: Mac only */ add_task(async function test_mac_notifications() { if (!IS_MAC) { diff --git a/browser/components/tabbrowser/SmartTabGrouping.sys.mjs b/browser/components/tabbrowser/SmartTabGrouping.sys.mjs @@ -1573,7 +1573,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 + * @param {string[]} otherDocuments other clusters that we'll compare against * @return keywords and documents that represent the cluster */ getRepresentativeDocsAndKeywords(otherDocuments = []) { diff --git a/browser/components/tabbrowser/content/browser-ctrlTab.js b/browser/components/tabbrowser/content/browser-ctrlTab.js @@ -54,17 +54,17 @@ var tabPreviews = { * 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 - * for the tab, or if the tab is still loading, a snapshot is taken and - * returned as a canvas. It may be cached as a canvas (separately from + * @returns {Promise<HTMLCanvasElement|Image|null>} + * Resolves to an HTMLCanvasElement if a thumbnail can NOT be captured and + * stored for the tab, or if the tab is still loading (a snapshot is taken + * and returned as a canvas). It may be cached as a canvas (separately from * thumbnail storage) in aTab.__thumbnail if the tab is finished loading. If * the snapshot CAN be stored as a thumbnail, the snapshot is converted to a * blob image and drawn in the returned canvas, but the image is added to * thumbnail storage and cached in aTab.__thumbnail. - * @resolves {Image} A cached blob image from a previous thumbnail capture. - * e.g. <img src="moz-page-thumb://thumbnails/?url=foo.com&revision=bar"> - * @resolves {null} If a thumbnail cannot be captured for any reason (e.g. + * Resolves to an Image if a cached blob image from a previous thumbnail + * capture exists (e.g. <img src="moz-page-thumb://thumbnails/?url=foo.com&revision=bar">). + * Resolves to null if a thumbnail cannot be captured for any reason (e.g. * because the tab is discarded) and there is no cached/stored thumbnail. */ get: async function tabPreviews_get(aTab) { @@ -98,13 +98,13 @@ var tabPreviews = { * * @param {MozTabbrowserTab} aTab The tab to capture a preview for. * @param {boolean} aShouldCache Cache/store the captured thumbnail? - * @returns {Promise<HTMLCanvasElement|null>} Resolves to... - * @resolves {HTMLCanvasElement} A snapshot of the tab's content. If the + * @returns {Promise<HTMLCanvasElement|null>} + * Resolves to an HTMLCanvasElement snapshot of the tab's content. If the * snapshot is safe for storage and aShouldCache is true, the snapshot is * converted to a blob image, stored and cached, and drawn in the returned * canvas. The thumbnail can then be recovered even if the browser is * discarded. Otherwise, the canvas itself is cached in aTab.__thumbnail. - * @resolves {null} If a fatal exception occurred during thumbnail capture. + * Resolves to null if a fatal exception occurred during thumbnail capture. */ capture: async function tabPreviews_capture(aTab, aShouldCache) { let browser = aTab.linkedBrowser; diff --git a/browser/components/tabbrowser/content/browser-fullZoom.js b/browser/components/tabbrowser/content/browser-fullZoom.js @@ -329,8 +329,7 @@ var FullZoom = { * whether or not the ZoomManager.zoom level is at 1.0. This is specifically * for when using scaling zoom via the pinch gesture which doesn't cause * the ZoomManager.zoom level to change. - * @returns Promise - * @resolves undefined + * @returns {Promise<void>} */ updateCommands: async function FullZoom_updateCommands( forceResetEnabled = false diff --git a/browser/components/tabbrowser/test/browser/tabs/browser_tabCloseProbes.js b/browser/components/tabbrowser/test/browser/tabs/browser_tabCloseProbes.js @@ -49,8 +49,8 @@ function assertCount(snapshot, expectedCount) { * The Telemetry histogram to examine. * @param expectedCount (int) * What we expect the number of incremented counts to become. - * @return (Promise) - * @resolves When the histogram snapshot count becomes the expected count. + * @returns {Promise<void>} + * Resolves when the histogram snapshot count becomes the expected count. */ function waitForSnapshotCount(histogram, expectedCount) { return BrowserTestUtils.waitForCondition(() => { diff --git a/browser/extensions/newtab/content-src/components/ComponentPerfTimer/ComponentPerfTimer.jsx b/browser/extensions/newtab/content-src/components/ComponentPerfTimer/ComponentPerfTimer.jsx @@ -42,7 +42,7 @@ export class ComponentPerfTimer extends React.Component { /** * Call the given callback after the upcoming frame paints. * - * @note Both setTimeout and requestAnimationFrame are throttled when the page + * Note: Both setTimeout and requestAnimationFrame are throttled when the page * is hidden, so this callback may get called up to a second or so after the * requestAnimationFrame "paint" for hidden tabs. * diff --git a/browser/extensions/newtab/content-src/lib/perf-service.mjs b/browser/extensions/newtab/content-src/lib/perf-service.mjs @@ -44,7 +44,7 @@ _PerfService.prototype = { * Used to ensure that timestamps from the add-on code and the content code * are comparable. * - * @note If this is called from a context without a window + * Note: If this is called from a context without a window * (eg a JSM in chrome), it will return the timeOrigin of the XUL hidden * window, which appears to be the first created window (and thus * timeOrigin) in the browser. Note also, however, there is also a private @@ -79,7 +79,7 @@ _PerfService.prototype = { * * @throws {Error} "No Marks with the name ..." if none are available * - * @note Always surround calls to this by try/catch. Otherwise your code + * Note: Always surround calls to this by try/catch. Otherwise your code * may fail when the `privacy.resistFingerprinting` pref is true. When * this pref is set, all attempts to get marks will likely fail, which will * cause this method to throw. diff --git a/browser/extensions/newtab/data/content/activity-stream.bundle.js b/browser/extensions/newtab/data/content/activity-stream.bundle.js @@ -5894,7 +5894,7 @@ _PerfService.prototype = { * Used to ensure that timestamps from the add-on code and the content code * are comparable. * - * @note If this is called from a context without a window + * Note: If this is called from a context without a window * (eg a JSM in chrome), it will return the timeOrigin of the XUL hidden * window, which appears to be the first created window (and thus * timeOrigin) in the browser. Note also, however, there is also a private @@ -5929,7 +5929,7 @@ _PerfService.prototype = { * * @throws {Error} "No Marks with the name ..." if none are available * - * @note Always surround calls to this by try/catch. Otherwise your code + * Note: Always surround calls to this by try/catch. Otherwise your code * may fail when the `privacy.resistFingerprinting` pref is true. When * this pref is set, all attempts to get marks will likely fail, which will * cause this method to throw. @@ -5990,7 +5990,7 @@ class ComponentPerfTimer extends (external_React_default()).Component { /** * Call the given callback after the upcoming frame paints. * - * @note Both setTimeout and requestAnimationFrame are throttled when the page + * Note: Both setTimeout and requestAnimationFrame are throttled when the page * is hidden, so this callback may get called up to a second or so after the * requestAnimationFrame "paint" for hidden tabs. * diff --git a/browser/extensions/newtab/lib/TelemetryFeed.sys.mjs b/browser/extensions/newtab/lib/TelemetryFeed.sys.mjs @@ -1971,7 +1971,7 @@ export class TelemetryFeed { * be valid values of the perf object, as defined in pings.js and the * data*.md documentation. * - * @note Any existing keys with the same names already in the + * Note: Any existing keys with the same names already in the * session perf object will be overwritten by values passed in here. * * @param {string} port The session with which this is associated diff --git a/browser/extensions/newtab/test/unit/utils.js b/browser/extensions/newtab/test/unit/utils.js @@ -321,7 +321,7 @@ FakePerformance.prototype = { callsToMark: 0, /** - * @note The "startTime" for each mark is simply the number of times mark + * Note: The "startTime" for each mark is simply the number of times mark * has been called in this object. */ mark(name) { diff --git a/browser/modules/BrowserUsageTelemetry.sys.mjs b/browser/modules/BrowserUsageTelemetry.sys.mjs @@ -1707,7 +1707,7 @@ export let BrowserUsageTelemetry = { /** * Tracks the window count and registers the listeners for the tab count. * - * @param{Object} win The window object. + * @param {object} win The window object. */ _onWindowOpen(win) { // Make sure to have a |nsIDOMWindow|. @@ -1891,8 +1891,9 @@ export let BrowserUsageTelemetry = { * @param {Array<string>} [msixPackagePrefixes] Optional, list of prefixes to consider "existing" installs when looking at installed MSIX packages. Defaults to prefixes for builds produced in Firefox automation. - * @return {Promise<object>} A JSON object containing install telemetry. - * @resolves When the event has been recorded, or if the data file was not found. + * @returns {Promise<object>} + * Resolves to a JSON object containing install telemetry when the event has + * been recorded, or if the data file was not found. * @rejects JavaScript exception on any failure. */ async collectInstallationTelemetry( diff --git a/browser/modules/test/browser/browser_UsageTelemetry_domains.js b/browser/modules/test/browser/browser_UsageTelemetry_domains.js @@ -15,8 +15,8 @@ Services.obs.notifyObservers(null, TELEMETRY_SUBSESSION_TOPIC); * @param {xul:browser} browser * A xul:browser. * - * @return {Promise} - * @resolves When navigating to a non-error page. + * @returns {Promise<void>} + * Resolves when a non-error page has been navigated to. */ function browserLocationChanged(browser) { return new Promise(resolve => {