tor-browser

commit 557804ef699c54da0530081123296e7f9362a3fc
parent 8c928f228848c5f8457a325e32211d0ce55e28ca
Author: Duncan McIntosh <dmcintosh@mozilla.com>
Date:   Wed,  5 Nov 2025 18:43:12 +0000

Bug 1998061 - Part 1: Improve documentation in BackupService and make STATUS_OBSERVER_PREFS non-private. r=hsohaney

The main fix here is STATUS_OBSERVER_PREFS---I think that the documentation
generator can't understand a private static getter. The rest were me
noticing that much of the documentation could be improved in the first
place, so I've tagged that along.

Differential Revision: https://phabricator.services.mozilla.com/D271283

Diffstat:
M
browser/components/backup/BackupService.sys.mjs
 | 
35
++++++++++++++++++++++++++++++-----

1 file changed, 30 insertions(+), 5 deletions(-)
diff --git a/browser/components/backup/BackupService.sys.mjs b/browser/components/backup/BackupService.sys.mjs
@@ -870,8 +870,14 @@ export class BackupService extends EventTarget {
   #wasRestorePreviouslyDisabled = false;
 
   /**
-   * Monitors prefs that are relevant to the status of the backup service.
-   * Unlike #observer, this does not wait for an idle tick.
+   * Called when prefs or other conditions relevant to the status of the backup
+   * service change. Unlike #observer, this does not wait for an idle tick.
+   *
+   * This callback doesn't take any parameters. It's here so it can be removed
+   * by uninitStatusObservers, and also so its 'this' value remains accurate.
+   * If null, the conditions are not currently being monitored.
+   *
+   * @type {Function?}
    */
   #statusPrefObserver = null;
 
@@ -1025,8 +1031,10 @@ export class BackupService extends EventTarget {
    * Prefs that should be monitored. When one of these prefs changes, the
    * 'backup-service-status-changed' observers are notified and telemetry
    * updates.
+   *
+   * @type {string[]}
    */
-  static get #STATUS_OBSERVER_PREFS() {
+  static get STATUS_OBSERVER_PREFS() {
     return [
       BACKUP_ARCHIVE_ENABLED_PREF_NAME,
       BACKUP_RESTORE_ENABLED_PREF_NAME,
@@ -3907,6 +3915,17 @@ export class BackupService extends EventTarget {
     }
   }
 
+  /**
+   * Makes this instance responsible for monitoring the conditions that can
+   * cause backups or restores to be unavailable.
+   *
+   * When one arrives, observers of the 'backup-service-status-changed' topic
+   * will be notified and telemetry will be emitted.
+   *
+   * This is not done by default since that would cause N emissions of that
+   * topic per change for N instances, which can be a problem with testing. The
+   * global BackupService has status observers by default.
+   */
   initStatusObservers() {
     if (this.#statusPrefObserver != null) {
       return;
@@ -3919,19 +3938,25 @@ export class BackupService extends EventTarget {
       this.#notifyStatusObservers();
     };
 
-    for (let pref of BackupService.#STATUS_OBSERVER_PREFS) {
+    for (let pref of BackupService.STATUS_OBSERVER_PREFS) {
       Services.prefs.addObserver(pref, this.#statusPrefObserver);
     }
     lazy.NimbusFeatures.backupService.onUpdate(this.#statusPrefObserver);
     this.#notifyStatusObservers();
   }
 
+  /**
+   * Removes the observers configured by initStatusObservers.
+   *
+   * This is done automatically on shutdown, but you can do it earlier if you'd
+   * like that instance to stop emitting events.
+   */
   uninitStatusObservers() {
     if (this.#statusPrefObserver == null) {
       return;
     }
 
-    for (let pref of BackupService.#STATUS_OBSERVER_PREFS) {
+    for (let pref of BackupService.STATUS_OBSERVER_PREFS) {
       Services.prefs.removeObserver(pref, this.#statusPrefObserver);
     }
     lazy.NimbusFeatures.backupService.offUpdate(this.#statusPrefObserver);