commit 1c5b20a293a72f13f5cca0214f9e5f7520c096f5 parent 0a9a458465bab11be728333f99b5aa9b56793c0d Author: Mark Banner <standard8@mozilla.com> Date: Thu, 16 Oct 2025 10:55:58 +0000 Bug 1994217 - Enable ESLint rule jsdoc/no-bad-blocks. r=frontend-codestyle-reviewers,webdriver-reviewers,credential-management-reviewers,search-reviewers,fxview-reviewers,places-reviewers,whimboo,nsharpley,scunnane,Gijs,mtigley,daisuke Mainly manual fixes to fix issues found in the jsdoc comments now that they're recognised correctly. Also removes some configuration that is no longer needed as it is now the default. Differential Revision: https://phabricator.services.mozilla.com/D268569 Diffstat:
21 files changed, 126 insertions(+), 184 deletions(-)
diff --git a/browser/components/enterprisepolicies/helpers/BookmarksPolicies.sys.mjs b/browser/components/enterprisepolicies/helpers/BookmarksPolicies.sys.mjs @@ -64,10 +64,10 @@ export const BookmarksPolicies = { BOOKMARK_GUID_PREFIX: "PolB-", FOLDER_GUID_PREFIX: "PolF-", - /* + /** * Process the bookmarks specified by the policy engine. * - * @param param + * @param {object[]} param * This will be an array of bookmarks objects, as * described on the top of this file. */ @@ -88,13 +88,13 @@ export const BookmarksPolicies = { }, }; -/* +/** * This function calculates the differences between the existing bookmarks * that are managed by the policy engine (which are known through a guid * prefix) and the specified bookmarks in the policy file. * They can differ if the policy file has changed. * - * @param specifiedBookmarks + * @param {object[]} specifiedBookmarks * This will be an array of bookmarks objects, as * described on the top of this file. */ diff --git a/browser/components/extensions/ExtensionControlledPopup.sys.mjs b/browser/components/extensions/ExtensionControlledPopup.sys.mjs @@ -2,8 +2,8 @@ * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ -/* - * @fileOverview +/** + * @file * This module exports a class that can be used to handle displaying a popup * doorhanger with a primary action to not show a popup for this extension again * and a secondary action disables the addon, or brings the user to their settings. @@ -46,7 +46,8 @@ ChromeUtils.defineLazyGetter(lazy, "distributionAddonsList", function () { }); export class ExtensionControlledPopup { - /* Provide necessary options for the popup. + /** + * Provide necessary options for the popup. * * @param {object} opts Options for configuring popup. * @param {string} opts.confirmedType @@ -78,20 +79,20 @@ export class ExtensionControlledPopup { * @param {string} opts.learnMoreLink * The name of the SUMO page to link to, this is added to * app.support.baseURL. - * @param optional {string} opts.preferencesLocation + * @param {string} [opts.preferencesLocation] * If included, the name of the preferences tab that will be opened * by the secondary action. If not included, the secondary option will * disable the addon. - * @param optional {string} opts.preferencesEntrypoint + * @param {string} [opts.preferencesEntrypoint] * The entrypoint to pass to preferences telemetry. - * @param {function} opts.onObserverAdded + * @param {Function} opts.onObserverAdded * A callback that is triggered when an observer is registered to * trigger the popup on the next observerTopic. - * @param {function} opts.onObserverRemoved + * @param {Function} opts.onObserverRemoved * A callback that is triggered when the observer is removed, * either because the popup is opening or it was explicitly * cancelled by calling removeObserver. - * @param {function} opts.beforeDisableAddon + * @param {Function} opts.beforeDisableAddon * A function that is called before disabling an extension when the * user decides to disable the extension. If this function is async * then the extension won't be disabled until it is fulfilled. diff --git a/browser/components/firefoxview/OpenTabs.sys.mjs b/browser/components/firefoxview/OpenTabs.sys.mjs @@ -170,11 +170,11 @@ class OpenTabsTarget extends EventTarget { ); } - /* + /** * @param {string} type * Either "TabChange" or "TabRecencyChange" - * @param {Object|Function} listener - * @param {Object} [options] + * @param {object | Function} listener + * @param {object} [options] */ addEventListener(type, listener, options) { let hadListeners = this.haveAnyListeners; @@ -186,10 +186,10 @@ class OpenTabsTarget extends EventTarget { } } - /* + /** * @param {string} type * Either "TabChange" or "TabRecencyChange" - * @param {Object|Function} listener + * @param {object | Function} listener */ removeEventListener(type, listener) { let hadListeners = this.haveAnyListeners; @@ -340,7 +340,7 @@ class OpenTabsTarget extends EventTarget { } } - /* + /** * @param {Window} win * @param {boolean} sortByRecency * @returns {Array<Tab>} @@ -363,7 +363,7 @@ class OpenTabsTarget extends EventTarget { return this.currentWindows.flatMap(win => this.getTabsForWindow(win)); } - /* + /** * @returns {Array<Tab>} * A by-recency-sorted, aggregated list of tabs from all the same-privateness browser windows. */ diff --git a/browser/components/places/tests/browser/browser_forgetthissite.js b/browser/components/places/tests/browser/browser_forgetthissite.js @@ -189,10 +189,10 @@ async function testForgetAboutThisSite( await teardown(organizer); } -/* - * Opens the history view in the PlacesOrganziner window - * @returns {Promise} - * @resolves The PlacesOrganizer +/** + * Opens the history view in the Library window + * + * @returns {Promise<PlacesOrganizer>} */ async function promiseHistoryView() { let organizer = await promiseLibrary(); @@ -209,9 +209,10 @@ async function promiseHistoryView() { return organizer; } -/* - * @returns {Promise} - * @resolves once the popup is shown +/** + * @param {XULElement} popup + * @returns {Promise<void>} + * Resolves once the popup is shown */ function promisePopupShown(popup) { return new Promise(resolve => { diff --git a/browser/components/protocolhandler/WebProtocolHandlerRegistrar.sys.mjs b/browser/components/protocolhandler/WebProtocolHandlerRegistrar.sys.mjs @@ -90,12 +90,12 @@ WebProtocolHandlerRegistrar.prototype = { } }, - /* This function can be called multiple times and (re-)initializes the cache + /** + * This function can be called multiple times and (re-)initializes the cache * if the feature is toggled on. If called with the feature off it will also * unregister the observers. * * @param {boolean} firstInit - * */ init(firstInit = false) { if (firstInit) { @@ -285,7 +285,8 @@ WebProtocolHandlerRegistrar.prototype = { return xreDirProvider.getInstallHash(); }, - /* Private method to check if we are already the default protocolhandler + /** + * Private method to check if we are already the default protocolhandler * for `protocol`. * * @param {string} protocol name, e.g. mailto (without ://) @@ -415,65 +416,6 @@ WebProtocolHandlerRegistrar.prototype = { return handler; }, - /* - * Function to store a value associated to a domain using the content pref - * service. - * - * @param {string} domain: the domain for this setting - * @param {string} setting: the name of the setting - * @param {string} value: the actual setting to be stored - * @param {string} context (optional): private window or not - * @returns {string} the stored preference (see: nsIContentPrefService2.idl) - */ - async _saveSiteSpecificSetting(domain, setting, value, context = null) { - const gContentPrefs = Cc["@mozilla.org/content-pref/service;1"].getService( - Ci.nsIContentPrefService2 - ); - - return new Promise((resolve, reject) => { - gContentPrefs.set(domain, setting, value, context, { - handleResult(pref) { - resolve(pref); - }, - handleCompletion() {}, - handleError(err) { - reject(err); - }, - }); - }); - }, - - /* - * Function to return a stored value from the content pref service. Returns - * a promise, so await can be used to synchonize the retrieval. - * - * @param {string} domain: the domain for this setting - * @param {string} setting: the name of the setting - * @param {string} context (optional): private window or not - * @param {string} def (optional): the default value to return - * @returns {string} either stored value or "" - */ - async _getSiteSpecificSetting(domain, setting, context = null, def = null) { - const gContentPrefs = Cc["@mozilla.org/content-pref/service;1"].getService( - Ci.nsIContentPrefService2 - ); - - return await new Promise((resolve, reject) => { - gContentPrefs.getByDomainAndName(domain, setting, context, { - _result: def, - handleResult(pref) { - this._result = pref.value; - }, - handleCompletion(_) { - resolve(this._result); - }, - handleError(err) { - reject(err); - }, - }); - }); - }, - /** * See nsIWebProtocolHandlerRegistrar */ @@ -580,7 +522,7 @@ WebProtocolHandlerRegistrar.prototype = { ); }, - /* + /** * Special implementation for mailto: A prompt (notificationbox.js) is only * shown if there is a realistic chance that we can really set the OS default, * e.g. if we have been properly installed and the current page is not already diff --git a/browser/components/shell/ShellService.sys.mjs b/browser/components/shell/ShellService.sys.mjs @@ -134,13 +134,13 @@ let ShellServiceInternal = { return false; }, - /* + /** * Check if UserChoice is impossible. * * Separated for easy stubbing in tests. * - * @return string telemetry result like "Err*", or null if UserChoice - * is possible. + * @returns {string} + * Telemetry result like "Err*", or null if UserChoice is possible. */ _userChoiceImpossibleTelemetryResult() { let winShellService = this.shellService.QueryInterface( @@ -155,10 +155,11 @@ let ShellServiceInternal = { return null; }, - /* + /** * Accommodate `setDefaultPDFHandlerOnlyReplaceBrowsers` feature. - * @return true if Firefox should set itself as default PDF handler, false - * otherwise. + * + * @returns {boolean} + * True if Firefox should set itself as default PDF handler, false otherwise. */ _shouldSetDefaultPDFHandler() { if ( @@ -247,14 +248,15 @@ let ShellServiceInternal = { }; }, - /* + /** * Set the default browser through the UserChoice registry keys on Windows. * * NOTE: This does NOT open the System Settings app for manual selection * in case of failure. If that is desired, catch the exception and call * setDefaultBrowser(). * - * @return Promise, resolves when successful, rejects with Error on failure. + * @returns {Promise<void>} + * Resolves when successful, rejects with Error on failure. */ async setAsDefaultUserChoice() { if (AppConstants.platform != "win") { diff --git a/docshell/test/navigation/test_load_history_entry.html b/docshell/test/navigation/test_load_history_entry.html @@ -77,20 +77,22 @@ SimpleTest.finish(); } - /* - * @prevLocation - * if undefined, it is because there is no page to go back to - * - * @isCrossDocumentLoad - * did we just open a different document - * @hashChangeExpected - * Would we get a hash change event if we navigated backwards and forwards in history? - * This is framed with respect to the previous step, e.g. in the previous step was the - * hash different from the location we have navigated to just before calling this function? - * When we navigate forwards or backwards, we need to wait for this event - * because clickLink() also waits for hashchange event and - * if this function gets called before clickLink(), sometimes hashchange - * events from this function will leak to clickLink. + /** + * @param {Window} testWin + * @param {object} shistory + * @param {number} expectedNumSHEntries + * @param {?string} prevLocation + * If undefined, it is because there is no page to go back to. + * @param {boolean} [isCrossDocumentLoad] + * Did we just open a different document? + * @param {boolean} [hashChangeExpected] + * Would we get a hash change event if we navigated backwards and forwards in history? + * This is framed with respect to the previous step, e.g. in the previous step was the + * hash different from the location we have navigated to just before calling this function? + * When we navigate forwards or backwards, we need to wait for this event + * because clickLink() also waits for hashchange event and + * if this function gets called before clickLink(), sometimes hashchange + * events from this function will leak to clickLink. */ async function doAfterEachTest(testWin, shistory, expectedNumSHEntries, prevLocation, isCrossDocumentLoad = false, hashChangeExpected = true) { diff --git a/remote/shared/NavigableManager.sys.mjs b/remote/shared/NavigableManager.sys.mjs @@ -71,7 +71,8 @@ class NavigableManagerClass { return null; } - /* Retrieve the browsing context corresponding to the provided navigabl id. + /** + * Retrieve the browsing context corresponding to the provided navigabl id. * * @param {string} id * A browsing context unique id (created by getIdForBrowsingContext). diff --git a/remote/shared/messagehandler/MessageHandlerRegistry.sys.mjs b/remote/shared/messagehandler/MessageHandlerRegistry.sys.mjs @@ -61,10 +61,10 @@ export function getMessageHandlerClass(type) { * after crossing a technical boundary (eg process, thread...). */ export class MessageHandlerRegistry extends EventEmitter { - /* - * @param {String} type + /** + * @param {string} type * MessageHandler type, one of MessageHandler.type. - * @param {Object} context + * @param {object} context * The context object, which depends on the type. */ constructor(type, context) { diff --git a/remote/shared/messagehandler/ModuleCache.sys.mjs b/remote/shared/messagehandler/ModuleCache.sys.mjs @@ -90,7 +90,7 @@ export class ModuleCache { #modules; #protocol; - /* + /** * @param {MessageHandler} messageHandler * The MessageHandler instance which owns this ModuleCache instance. */ diff --git a/toolkit/components/doh/TRRPerformance.sys.mjs b/toolkit/components/doh/TRRPerformance.sys.mjs @@ -280,14 +280,17 @@ export class TRRRacer { ); } - /* + /** * Given an array of { trr, time }, returns the trr with smallest mean time. * Separate from _getFastestTRR for easy unit-testing. * - * @returns The TRR with the fastest average time. - * If returnRandomDefault is false-y, returns undefined if no valid - * times were present in the results. Otherwise, returns one of the - * present TRRs at random. + * @param {{trr: string[], time: number}[]} results + * @param {boolean} returnRandomDefault + * @returns {string} + * The TRR with the fastest average time. + * If returnRandomDefault is false-y, returns undefined if no valid + * times were present in the results. Otherwise, returns one of the + * present TRRs at random. */ _getFastestTRRFromResults(results, returnRandomDefault = false) { // First, organize the results into a map of TRR -> array of times diff --git a/toolkit/components/extensions/ExtensionCommon.sys.mjs b/toolkit/components/extensions/ExtensionCommon.sys.mjs @@ -2248,7 +2248,7 @@ LocaleData.prototype = { * content process). */ class EventManager { - /* + /** * A persistent event must provide module and name. Additionally the * module must implement primeListeners in the ExtensionAPI class. * @@ -2366,7 +2366,7 @@ class EventManager { this.remove = new Map(); } - /* + /** * Information about listeners to persistent events is associated with * the extension to which they belong. Any extension thas has such * listeners has a property called `persistentListeners` that is a diff --git a/toolkit/components/formautofill/FormAutofillParent.sys.mjs b/toolkit/components/formautofill/FormAutofillParent.sys.mjs @@ -2,12 +2,12 @@ * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ -/* +/** * Implements a service used to access storage and communicate with content. * * A "fields" array is used to communicate with FormAutofillChild. Each item * represents a single input field in the content page as well as its - * @autocomplete properties. The schema is as below. Please refer to + * `@autocomplete` properties. The schema is as below. Please refer to * FormAutofillChild.js for more details. * * [ diff --git a/toolkit/components/formautofill/default/FormAutofillPrompter.sys.mjs b/toolkit/components/formautofill/default/FormAutofillPrompter.sys.mjs @@ -826,7 +826,7 @@ export class AddressEditDoorhanger extends AutofillDoorhanger { return div; } - /* + /** * This method generates a unique input ID using the field name of the address field. * * @param {string} fieldName The name of the address field diff --git a/toolkit/components/formautofill/shared/FormAutofillSection.sys.mjs b/toolkit/components/formautofill/shared/FormAutofillSection.sys.mjs @@ -83,35 +83,32 @@ export class FormAutofillSection { return this.fieldDetails.map(field => field.fieldName); } - /* + /** * Examine the section is a valid section or not based on its fieldDetails or * other information. This method must be overrided. * * @returns {boolean} True for a valid section, otherwise false - * */ isValidSection() { throw new TypeError("isValidSection method must be overrided"); } - /* + /** * Examine the section is an enabled section type or not based on its * preferences. This method must be overrided. * * @returns {boolean} True for an enabled section type, otherwise false - * */ isEnabled() { throw new TypeError("isEnabled method must be overrided"); } - /* + /** * Examine the section is createable for storing the profile. This method * must be overrided. * - * @param {Object} _record The record for examining createable + * @param {object} _record The record for examining createable * @returns {boolean} True for the record is createable, otherwise false - * */ isRecordCreatable(_record) { throw new TypeError("isRecordCreatable method must be overridden"); diff --git a/toolkit/components/places/TaggingService.sys.mjs b/toolkit/components/places/TaggingService.sys.mjs @@ -541,13 +541,17 @@ class TagSearch { export function TagAutoCompleteSearch() {} TagAutoCompleteSearch.prototype = { - /* + /** * Search for a given string and notify a listener of the result. * - * @param searchString - The string to search for - * @param searchParam - An extra parameter - * @param previousResult - A previous result to use for faster searching - * @param listener - A listener to notify when the search is complete + * @param {string} searchString + * The string to search for. + * @param {string} searchParam + * An extra parameter. + * @param {nsIAutoCompleteResult} previousResult + * A previous result to use for faster searching. + * @param {nsIAutoCompleteObserver} listener + * A listener to notify when the search is complete. */ startSearch(searchString, searchParam, previousResult, listener) { if (this._search) { diff --git a/toolkit/components/places/tests/PlacesTestUtils.sys.mjs b/toolkit/components/places/tests/PlacesTestUtils.sys.mjs @@ -121,7 +121,7 @@ export var PlacesTestUtils = Object.freeze({ } }, - /* + /** * Add Favicons * * @param {Map} faviconURLs keys are page URLs, values are their @@ -153,16 +153,17 @@ export var PlacesTestUtils = Object.freeze({ await Promise.all(faviconPromises); }, - /* + /** * Helper function to call PlacesUtils.favicons.setFaviconForPage() and waits * finishing setting. This function throws an error if the status of * PlacesUtils.favicons.setFaviconForPage() is not success. * - * @param {string or nsIURI} pageURI - * @param {string or nsIURI} faviconURI - * @param {string or nsIURI} faviconDataURL - * @param {Number} [optional] expiration - * @return {Promise} waits for finishing setting + * @param {string|nsIURI} pageURI + * @param {string|nsIURI} faviconURI + * @param {string|nsIURI} faviconDataURL + * @param {number} [expiration] + * @param {boolean} [isRichIcon] + * @returns {Promise<void>} waits for finishing setting */ setFaviconForPage( pageURI, diff --git a/toolkit/components/places/tests/unit/test_bookmarks_html_corrupt.js b/toolkit/components/places/tests/unit/test_bookmarks_html_corrupt.js @@ -44,12 +44,10 @@ add_task(async function test_corrupt_database() { await database_check(); }); -/* +/** * Check for imported bookmarks correctness * - * @return {Promise} - * @resolves When the checks are finished. - * @rejects Never. + * @returns {Promise<void>} */ var database_check = async function () { // BOOKMARKS MENU diff --git a/toolkit/components/search/SearchSettings.sys.mjs b/toolkit/components/search/SearchSettings.sys.mjs @@ -75,7 +75,7 @@ export class SearchSettings { */ #searchService = null; - /* + /** * The user's settings file read from disk so we can persist metadata for * engines that are default or hidden, the user's locale and region, hashes * for the loadPath, and hashes for default and private default engines. @@ -83,37 +83,44 @@ export class SearchSettings { * to the settings. * * Structure of settings: - * Object { version: <number>, - * engines: [...], - * metaData: {...}, - * } + * + * ``` + * Object { + * version: <number>, + * engines: [...], + * metaData: {...}, + * } + * ``` * * Settings metaData is the active metadata for setting and getting attributes. * When a new metadata attribute is set, we save it to #settings.metaData and * write #settings to disk. * * #settings.metaData attributes: + * * @property {string} current - * The current user-set default engine. The associated hash is called - * 'hash'. + * The current user-set default engine. The associated hash is called + * 'hash'. * @property {string} private - * The current user-set private engine. The associated hash is called - * 'privateHash'. - * The current and prviate objects have associated hash fields to validate - * the value is set by the application. + * The current user-set private engine. The associated hash is called + * 'privateHash'. + * The current and prviate objects have associated hash fields to validate + * the value is set by the application. * @property {string} appDefaultEngine + * The identifier of the current application default engine. * @property {string} channel - * Configuration is restricted to the specified channel. ESR is an example - * of a channel. + * Configuration is restricted to the specified channel. ESR is an example + * of a channel. * @property {string} distroID - * Specifies which distribution the default engine is included in. + * Specifies which distribution the default engine is included in. * @property {string} experiment - * Specifies if the application is running on an experiment. + * Specifies if the application is running on an experiment. * @property {string} locale + * The current locale. * @property {string} region + * The current region. * @property {boolean} useSavedOrder - * True if the user's order information stored in settings is used. - * + * True if the user's order information stored in settings is used. */ #settings = null; diff --git a/tools/lint/eslint/eslint-plugin-mozilla/lib/configs/require-jsdoc.mjs b/tools/lint/eslint/eslint-plugin-mozilla/lib/configs/require-jsdoc.mjs @@ -27,13 +27,4 @@ export default { "jsdoc/require-yields": "error", "jsdoc/require-yields-check": "error", }, - settings: { - jsdoc: { - // This changes what's allowed in JSDocs, enabling more type-inference - // friendly types. This is the default in eslint-plugin-jsdoc versions - // since May 2023, but we're still on 39.9 and need opt-in for now. - // https://github.com/gajus/eslint-plugin-jsdoc/issues/834 - mode: "typescript", - }, - }, }; diff --git a/tools/lint/eslint/eslint-plugin-mozilla/lib/configs/valid-jsdoc.mjs b/tools/lint/eslint/eslint-plugin-mozilla/lib/configs/valid-jsdoc.mjs @@ -15,19 +15,11 @@ export default { "jsdoc/check-tag-names": "error", "jsdoc/check-types": "error", "jsdoc/empty-tags": "error", + "jsdoc/no-bad-blocks": "error", "jsdoc/no-multi-asterisks": "error", "jsdoc/require-param-type": "error", "jsdoc/require-returns-type": "error", "jsdoc/tag-lines": ["error", "any", { startLines: 1 }], "jsdoc/valid-types": "error", }, - settings: { - jsdoc: { - // This changes what's allowed in JSDocs, enabling more type-inference - // friendly types. This is the default in eslint-plugin-jsdoc versions - // since May 2023, but we're still on 39.9 and need opt-in for now. - // https://github.com/gajus/eslint-plugin-jsdoc/issues/834 - mode: "typescript", - }, - }, };