📝 Add plenty of comments

src/ProfileManager.js

@@ -22,31 +22,31 @@ const ExtensionUtils = imports.misc.extensionUtils;
 const Me             = imports.misc.extensionUtils.getCurrentExtension();
 const utils          = Me.imports.src.utils;
 
-// extension.js:
+//////////////////////////////////////////////////////////////////////////////////////////
-//  - get a list of profile settings objects
+// Burn-My-Windows allows applying different sets of effect settings under specific     //
-
+// circumstances. These settings are called "effect profiles". The ProfileManager       //
-// prefs.js:
+// provides access to all currently configured effect profiles. It can be used in both  //
-//  - get a (sorted) list of profile settings objects
+// the settings dialog and the in the actual extension.                                 //
-//  - add a new profile
+// The profiles are stored in ~/.config/burn-my-windows/profiles and can be accessed    //
-//  - delete a profile
+// via Gio.Settings objects.                                                            //
-//  - create a name for a given profile
+//////////////////////////////////////////////////////////////////////////////////////////
 
 var ProfileManager = class {
   // ------------------------------------------------------------ constructor / destructor
 
   constructor() {
     this._makeProfilesDir();
-    this._loadProfiles();
+    this.reloadProfiles();
   }
 
   // -------------------------------------------------------------------- public interface
 
   // Returns an array of effect profiles. Each effect profile is an object with two
   // properties: The 'path' points to the file which contains the effect profile
-  // settings. The 'settings' property contains a Gio.Settings object for the profile.
+  // settings (located in ~/.config/burn-my-windows/profiles). The 'settings' property
-  // The former can be used to uniquely identify the profile, the latter can be used to
+  // contains a Gio.Settings object for the profile. The former can be used to uniquely
-  // access the profile's settings.
+  // identify the profile, the latter can be used to access the profile's settings. This
-  // This method will always return at least one profile. If none is configured, a default
+  // method will always return at least one profile. If none is configured, a default
   // profile will be created.
   getProfiles() {
     if (this._profiles.length == 0) {
@@ -57,8 +57,9 @@ var ProfileManager = class {
   }
 
   // This will create a new profile with all values initialized to their defaults. The
-  // method will return a effect profile object (as described above). It will also
+  // method will return an effect profile object (as described above). We will use the
-  // trigger an emission of the 'profiles-updated' signal.
+  // current system time in microseconds as profile name. This ensures that they are
+  // always sorted according to their creation date.
   createProfile() {
     const path = `${GLib.get_user_config_dir()}/burn-my-windows/profiles/${
       GLib.get_real_time()}.conf`;
@@ -67,11 +68,14 @@ var ProfileManager = class {
 
     const profile = {'path': path, 'settings': this._getProfileSettings(path)};
 
+    // Add the profile to our internal list of profiles.
     this._profiles.push(profile);
 
     return profile;
   }
 
+  // Removes a profile defined by its file path. This will actually remove the file from
+  // the disk, so there's no going back.
   deleteProfile(profilePath) {
     const profileDir = `${GLib.get_user_config_dir()}/burn-my-windows/profiles`;
     const file       = Gio.File.new_for_path(profilePath);
@@ -79,9 +83,49 @@ var ProfileManager = class {
       file.delete(null);
     }
 
+    // Remove the profile from our internal list of profiles.
     this._profiles = this._profiles.filter(p => p.path != profilePath);
   }
 
+  // Reloads all profiles from ~/.config/burn-my-windows/profiles. If you called the
+  // createProfile() and deleteProfile() methods above, there is no need to reload the
+  // profiles.
+  reloadProfiles() {
+    const dir =
+      Gio.File.new_for_path(GLib.get_user_config_dir() + '/burn-my-windows/profiles');
+
+    const files =
+      dir.enumerate_children('standard::*', Gio.FileQueryInfoFlags.NONE, null);
+
+    let profilePaths = [];
+
+    while (true) {
+      const presetInfo = files.next_file(null);
+
+      if (presetInfo == null) {
+        break;
+      }
+
+      if (presetInfo.get_file_type() == Gio.FileType.REGULAR) {
+        const suffixPos = presetInfo.get_display_name().indexOf('.conf');
+        if (suffixPos > 0) {
+          profilePaths.push(dir.get_child(presetInfo.get_name()).get_path());
+        }
+      }
+    }
+
+    // Sort profiles alphabetically, that is by their creation time.
+    profilePaths.sort();
+
+    this._profiles = [];
+
+    profilePaths.forEach(path => {
+      this._profiles.push({'path': path, 'settings': this._getProfileSettings(path)});
+    });
+  }
+
+  // Profiles are named according to their configuration. This method returns a localized
+  // string describing the settings of the profile.
   getProfileName(settings) {
     let items = [];
 
@@ -108,19 +152,20 @@ var ProfileManager = class {
                                             _('Balanced or Performance')]);
     // clang-format on
 
-    let label = '';
+    let name = '';
 
     if (items.length == 0) {
-      label = _('Default Profile');
+      name = _('Default Profile');
     } else {
-      label = items.join(' · ');
+      name = items.join(' · ');
     }
 
-    return label;
+    return name;
   }
 
   // ----------------------------------------------------------------------- private stuff
 
+  // Creates the directory ~/.config/burn-my-windows/profiles if it does not yet exist.
   _makeProfilesDir() {
     const path = `${GLib.get_user_config_dir()}/burn-my-windows/profiles`;
     const dir  = Gio.File.new_for_path(path);
@@ -130,41 +175,7 @@ var ProfileManager = class {
     }
   }
 
-  _loadProfiles() {
+  // Creates a Gio.Settings object for the given effect profile path. Based on
-    const dir =
-      Gio.File.new_for_path(GLib.get_user_config_dir() + '/burn-my-windows/profiles');
-
-    const files =
-      dir.enumerate_children('standard::*', Gio.FileQueryInfoFlags.NONE, null);
-
-    let profilePaths = [];
-
-    while (true) {
-      const presetInfo = files.next_file(null);
-
-      if (presetInfo == null) {
-        break;
-      }
-
-      if (presetInfo.get_file_type() == Gio.FileType.REGULAR) {
-        const suffixPos = presetInfo.get_display_name().indexOf('.conf');
-        if (suffixPos > 0) {
-          profilePaths.push(dir.get_child(presetInfo.get_name()).get_path());
-        }
-      }
-    }
-
-
-    profilePaths.sort();
-
-    this._profiles = [];
-
-    profilePaths.forEach(path => {
-      this._profiles.push({'path': path, 'settings': this._getProfileSettings(path)});
-    });
-  }
-
-  // Based on
   // https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/main/js/misc/extensionUtils.js#L213
   _getProfileSettings(profilePath) {