nixos/programs/gnome-session: update comments

modules/nixos/programs/gnome-session/default.nix

@@ -1,3 +1,8 @@
+# This module supports both the built-in and systemd-managed desktop sessions
+# for simplicity's sake and it is up to the user to configure one or the other
+# (or both but in practice, the user will make use only one of them at a time
+# so it's pointless). It also requires a lot of boilerplate which explains its
+# size.
 { config, lib, pkgs, utils, ... }:
 
 let
@@ -69,8 +74,8 @@ let
               let
                 scriptName = "${sessionName}-${name}-script";
 
-                # There's already a lot of bad bad things in this world, we don't to add
+                # There's already a lot of bad bad things in this world, we
-                # more of it here (only a fraction of it, though).
+                # don't to add more of it here (only a fraction of it, though).
                 scriptPackage = pkgs.writeShellApplication {
                   name = scriptName;
                   text = component.script;
@@ -302,6 +307,11 @@ in
 
     # Import those systemd units from gnome-session as well.
     systemd.packages = [ cfg.package ];
+
+    # We could include the systemd units in the desktop session package (which
+    # is more elegant and surprisingly trivial) but this requires
+    # reimplementing parts of nixpkgs systemd-lib and we're lazy bastards so
+    # no.
     systemd.user.units = lib.mkMerge sessionSystemdUnits;
   };
 }

modules/nixos/programs/gnome-session/submodules/component-type.nix

@@ -62,10 +62,12 @@
         but without certain options from stage 2 counterparts such as
         `reloadTriggers` and `restartTriggers`.
 
+        By default, this module sets the service unit as part of the respective
+        target unit (i.e., `PartOf=$COMPONENTID.target`).
+
         On a typical case, you shouldn't mess with much of the dependency
-        ordering of the service unit. By default, this module sets the
+        ordering of the service unit. You should configure `targetUnit` for
-        service unit as part of the respective target unit (i.e.,
+        that instead.
-        `PartOf=$COMPONENTID.target`).
         :::
       '';
       default = { };
@@ -216,9 +218,9 @@
 
       TODO: Is `Type=notify` a good default?
       * `Service.Type=` is obviously not included since not all desktop
-      components are the same either. Some of them could a D-Bus service,
+      components are the same either. Some of them could be a D-Bus service,
       some of them are oneshots, etc. Not to mention, this is already implied
-      to be `Type=simple` by systemd anyways.
+      to be `Type=simple` by systemd anyways which is enough for most cases.
 
       TODO: A good balance for this value, probably?
       * `Service.OOMScoreAdjust=` have different values for different

modules/nixos/programs/gnome-session/submodules/session-type.nix

@@ -141,9 +141,9 @@ in
         you set {option}`<session>.components` as this module already sets
         them for you.
 
-        The only time you manually set this if you want to require components
+        The only time you manually set this if you want to require other
-        from other desktop such as when creating a customized version of
+        gnome-session components from other desktop such as when creating a
-        GNOME.
+        customized version of GNOME.
         :::
       '';
       example = [