commit 78734c2bf38171b9379ac0a40c3dc260f675b318
parent 4e56f69348ac0cec472f441a6719e81dd25f40f1
Author: Nicolas Chevobbe <nchevobbe@mozilla.com>
Date: Thu, 16 Oct 2025 05:02:48 +0000
Bug 1994372 - [devtools] Enable rollout-valid-jsdoc and rollout-require-jsdoc for devtools/startup. r=devtools-reviewers,frontend-codestyle-reviewers,jdescottes.
Differential Revision: https://phabricator.services.mozilla.com/D268663
Diffstat:
5 files changed, 60 insertions(+), 12 deletions(-)
diff --git a/devtools/startup/DevToolsShim.sys.mjs b/devtools/startup/DevToolsShim.sys.mjs
@@ -52,6 +52,8 @@ export const DevToolsShim = {
/**
* Returns true if DevTools are enabled. This now only depends on the policy.
* TODO: Merge isEnabled and isDisabledByPolicy.
+ *
+ * @returns {boolean}
*/
isEnabled() {
return !this.isDisabledByPolicy();
@@ -60,6 +62,8 @@ export const DevToolsShim = {
/**
* Returns true if the devtools are completely disabled and can not be enabled. All
* entry points should return without throwing, initDevTools should never be called.
+ *
+ * @returns {boolean}
*/
isDisabledByPolicy() {
return Services.prefs.getBoolPref(DEVTOOLS_POLICY_DISABLED_PREF, false);
@@ -68,7 +72,7 @@ export const DevToolsShim = {
/**
* Check if DevTools have already been initialized.
*
- * @return {Boolean} true if DevTools are initialized.
+ * @returns {boolean} true if DevTools are initialized.
*/
isInitialized() {
return !!this._gDevTools;
@@ -78,7 +82,7 @@ export const DevToolsShim = {
* Returns the array of the existing toolboxes. This method is part of the compatibility
* layer for webextensions.
*
- * @return {Array<Toolbox>}
+ * @returns {Array<Toolbox>}
* An array of toolboxes.
*/
getToolboxes() {
@@ -92,7 +96,7 @@ export const DevToolsShim = {
/**
* Register an instance of gDevTools. Should be called by DevTools during startup.
*
- * @param {DevTools} a devtools instance (from client/framework/devtools)
+ * @param {DevTools} gDevTools - A DevTools instance (from client/framework/devtools)
*/
register(gDevTools) {
this._gDevTools = gDevTools;
@@ -124,6 +128,9 @@ export const DevToolsShim = {
* This method is used by browser/components/extensions/ext-devtools.js for the events:
* - toolbox-ready
* - toolbox-destroyed
+ *
+ * @param {string} event
+ * @param {Function} listener
*/
on(event, listener) {
if (this.isInitialized()) {
@@ -136,6 +143,9 @@ export const DevToolsShim = {
/**
* This method is currently only used by devtools code, but is kept here for consistency
* with on().
+ *
+ * @param {string} event
+ * @param {Function} listener
*/
off(event, listener) {
if (this.isInitialized()) {
@@ -148,8 +158,7 @@ export const DevToolsShim = {
/**
* Called from SessionStore.sys.mjs in mozilla-central when saving the current state.
*
- * @param {Object} state
- * A SessionStore state object that gets modified by reference
+ * @param {object} state - A SessionStore state object that gets modified by reference
*/
saveDevToolsSession(state) {
if (!this.isInitialized()) {
@@ -162,6 +171,8 @@ export const DevToolsShim = {
/**
* Called from SessionStore.sys.mjs in mozilla-central when restoring a previous session.
* Will always be called, even if the session does not contain DevTools related items.
+ *
+ * @param {object} session
*/
restoreDevToolsSession(session) {
if (!this.isEnabled()) {
@@ -192,7 +203,7 @@ export const DevToolsShim = {
* @param {ElementIdentifier} domReference
* Identifier generated by ContentDOMReference. It is a unique pair of
* BrowsingContext ID and a numeric ID.
- * @return {Promise} a promise that resolves when the accessible node is selected in the
+ * @returns {Promise} a promise that resolves when the accessible node is selected in the
* accessibility inspector or that resolves immediately if DevTools are not
* enabled.
*/
@@ -220,7 +231,7 @@ export const DevToolsShim = {
* @param {ElementIdentifier} domReference
* Identifier generated by ContentDOMReference. It is a unique pair of
* BrowsingContext ID and a numeric ID.
- * @return {Promise} a promise that resolves when the node is selected in the inspector
+ * @returns {Promise} a promise that resolves when the node is selected in the inspector
* markup view or that resolves immediately if DevTools are not enabled.
*/
inspectNode(tab, domReference) {
@@ -251,7 +262,7 @@ export const DevToolsShim = {
* Initialize DevTools via DevToolsStartup if needed. This method throws if DevTools are
* not enabled.
*
- * @param {String} reason
+ * @param {string} [reason]
* optional, if provided should be a valid entry point for DEVTOOLS_ENTRY_POINT
* in toolkit/components/telemetry/Histograms.json
* and devtools:entry_point in devtools/client/shared/metrics.yaml
diff --git a/devtools/startup/DevToolsStartup.sys.mjs b/devtools/startup/DevToolsStartup.sys.mjs
@@ -18,7 +18,7 @@
* Only once any of these entry point is fired, this module ensures starting
* core modules like 'devtools-browser.js' that hooks the browser windows
* and ensure setting up tools.
- **/
+ */
const kDebuggerPrefs = [
"devtools.debugger.remote-enabled",
@@ -71,6 +71,9 @@ ChromeUtils.defineLazyGetter(lazy, "KeyShortcutsBundle", function () {
*
* This means that language pack users might get a new Beta version but will not
* have a language pack with the new strings yet.
+ *
+ * @param {string} id
+ * @returns {string|null}
*/
function getLocalizedKeyShortcut(id) {
try {
@@ -552,6 +555,8 @@ DevToolsStartup.prototype = {
/**
* Called when receiving the "browser-delayed-startup-finished" event for a new
* top-level window.
+ *
+ * @param {Window} window
*/
onWindowReady(window) {
if (
@@ -573,6 +578,12 @@ DevToolsStartup.prototype = {
JsonView.initialize();
},
+ /**
+ * Called when receiving the "browser-delayed-startup-finished" event for a top-level
+ * window for the first time.
+ *
+ * @param {Window} window
+ */
onFirstWindowReady(window) {
if (this.devtoolsFlag) {
this.handleDevToolsFlag(window);
@@ -592,6 +603,8 @@ DevToolsStartup.prototype = {
* But instead of implementing the actual actions, defer to DevTools codebase.
* In most cases, it only needs to call this.initDevTools which handles the rest.
* We do that to prevent loading any DevTools module until the user intent to use them.
+ *
+ * @param {Window} window
*/
hookWindow(window) {
// Key Shortcuts need to be added on all the created windows.
@@ -790,7 +803,7 @@ DevToolsStartup.prototype = {
* Check if the user is a DevTools user by looking at our selfxss pref.
* This preference is incremented everytime the console is used (up to 5).
*
- * @return {Boolean} true if the user can be considered as a devtools user.
+ * @returns {boolean} true if the user can be considered as a devtools user.
*/
isDevToolsUser() {
const selfXssCount = Services.prefs.getIntPref("devtools.selfxss.count", 0);
@@ -820,6 +833,10 @@ DevToolsStartup.prototype = {
/**
* This method attaches on the key elements to the devtools keyset.
+ *
+ * @param {Document} doc
+ * @param {Array<object>} keyShortcuts
+ * @param {XULElement} [keyset]
*/
attachKeys(doc, keyShortcuts, keyset = doc.getElementById("devtoolsKeyset")) {
const window = doc.defaultView;
@@ -837,6 +854,9 @@ DevToolsStartup.prototype = {
/**
* This method removes keys from the devtools keyset.
+ *
+ * @param {Document} doc
+ * @param {Array<object>} keyShortcuts
*/
removeKeys(doc, keyShortcuts) {
for (const key of keyShortcuts) {
@@ -850,6 +870,7 @@ DevToolsStartup.prototype = {
/**
* We only want to have the keyboard shortcuts active when the menu button is on.
* This function either adds or removes the elements.
+ *
* @param {boolean} isEnabled
*/
toggleProfilerKeyShortcuts(isEnabled) {
@@ -1082,6 +1103,9 @@ DevToolsStartup.prototype = {
*
* --start-debugger-server ws:
* Start the WebSocket server on the default port (taken from d.d.remote-port)
+ *
+ * @param {nsICommandLine} cmdLine
+ * @param {boolean|string} portOrPath
*/
handleDevToolsServerFlag(cmdLine, portOrPath) {
if (!this._isRemoteDebuggingEnabled()) {
@@ -1168,10 +1192,10 @@ DevToolsStartup.prototype = {
* because this codepath is only used the first time a toolbox is opened for a
* tab.
*
- * @param {String} reason
+ * @param {string} reason
* One of "KeyShortcut", "SystemMenu", "HamburgerMenu", "ContextMenu",
* "CommandLine".
- * @param {String} key
+ * @param {string} key
* The key used by a key shortcut.
*/
sendEntryPointTelemetry(reason, key = "") {
@@ -1275,6 +1299,8 @@ DevToolsStartup.prototype = {
/**
* Called by setSlowScriptDebugHandler, when a tab freeze because of a slow running script
+ *
+ * @param {XULFrameElement} tab
*/
async slowScriptDebugHandler(tab) {
const require = this.initDevTools("SlowScript");
@@ -1371,6 +1397,8 @@ const JsonView = {
/**
* Save JSON to a file needs to be implemented here
* in the parent process.
+ *
+ * @param {object} message
*/
onSave(message) {
const browser = message.target;
diff --git a/devtools/startup/tests/browser/browser_shim_disable_devtools.js b/devtools/startup/tests/browser/browser_shim_disable_devtools.js
@@ -152,6 +152,8 @@ function waitForDelayedStartupFinished(win) {
/**
* Helper to call the toggle devtools shortcut.
+ *
+ * @param {Window} win
*/
function synthesizeToggleToolboxKey(win) {
info("Trigger the toogle toolbox shortcut");
diff --git a/devtools/startup/tests/xpcshell/test_devtools_shim.js b/devtools/startup/tests/xpcshell/test_devtools_shim.js
@@ -40,6 +40,11 @@ function createMockDevTools() {
/**
* Check if a given method was called an expected number of times, and finally check the
* arguments provided to the last call, if appropriate.
+ *
+ * @param {object} mock
+ * @param {string} method
+ * @param {number} length
+ * @param {Array} lastArgs
*/
function checkCalls(mock, method, length, lastArgs) {
Assert.strictEqual(
diff --git a/eslint-rollouts.config.mjs b/eslint-rollouts.config.mjs
@@ -303,6 +303,7 @@ export default [
"uriloader/**",
"widget/tests/window_composition_text_querycontent.xhtml",
],
+ ignores: ["devtools/startup/**"],
rules: mozilla.turnOff(mozilla.configs["flat/valid-jsdoc"].rules),
},
{
@@ -467,6 +468,7 @@ export default [
"widget/tests/file*.js",
"widget/tests/window_composition_text_querycontent.xhtml",
],
+ ignores: ["devtools/startup/**"],
rules: mozilla.turnOff(mozilla.configs["flat/require-jsdoc"].rules),
},
{
