modules: better document most things

22 files changed, 48 insertions, 16 deletions

diff --git a/modules/darwin/traits/users/seth.nix b/modules/darwin/traits/users/seth.nix
index d60ff4e..4431506 100644
--- a/modules/darwin/traits/users/seth.nix
+++ b/modules/darwin/traits/users/seth.nix
@@ -6,6 +6,7 @@ in
   config = lib.mkMerge [
     (lib.mkIf cfg.enable {
       home-manager.users.seth = {
+        # NOTE: this module is for linux, not mac
         seth.desktop.enable = false;
       };
     })
diff --git a/modules/nixos/base/networking.nix b/modules/nixos/base/networking.nix
index 35e8558..c4514df 100644
--- a/modules/nixos/base/networking.nix
+++ b/modules/nixos/base/networking.nix
@@ -6,6 +6,7 @@ in
   options.base.networking = {
     enable = lib.mkEnableOption "base network settings" // {
       default = config.base.enable;
+      defaultText = lib.literalExpression "config.base.enable";
     };
   };
 
diff --git a/modules/nixos/base/nix.nix b/modules/nixos/base/nix.nix
index 29b0264..e49eb17 100644
--- a/modules/nixos/base/nix.nix
+++ b/modules/nixos/base/nix.nix
@@ -1,10 +1,9 @@
 { config, lib, ... }:
 let
   cfg = config.base.nixSettings;
-  enable = config.base.enable && cfg.enable;
 in
 {
-  config = lib.mkIf enable {
+  config = lib.mkIf cfg.enable {
     nix = {
       channel.enable = lib.mkDefault false;
       settings.trusted-users = [
diff --git a/modules/nixos/base/programs.nix b/modules/nixos/base/programs.nix
index def710c..55424dc 100644
--- a/modules/nixos/base/programs.nix
+++ b/modules/nixos/base/programs.nix
@@ -1,10 +1,9 @@
 { config, lib, ... }:
 let
   cfg = config.base.defaultPrograms;
-  enable = config.base.enable && cfg.enable;
 in
 {
-  config = lib.mkIf enable {
+  config = lib.mkIf cfg.enable {
     programs = {
       git.enable = true;
       vim.defaultEditor = true;
diff --git a/modules/nixos/base/security.nix b/modules/nixos/base/security.nix
index 12d6f7e..5c015c7 100644
--- a/modules/nixos/base/security.nix
+++ b/modules/nixos/base/security.nix
@@ -6,15 +6,17 @@ in
   options.base.security = {
     enable = lib.mkEnableOption "basic security settings" // {
       default = config.base.enable;
+      defaultText = lib.literalExpression "config.base.enable";
     };
   };
 
+  # much here is sourced from https://xeiaso.net/blog/paranoid-nixos-2021-07-18/
   config = lib.mkIf cfg.enable {
     security = {
       apparmor.enable = lib.mkDefault true;
-      audit.enable = lib.mkDefault true;
-      auditd.enable = lib.mkDefault true;
-      polkit.enable = lib.mkDefault true;
+      audit.enable = lib.mkDefault true; # TODO: do i really need to set this manually?
+      auditd.enable = lib.mkDefault true; # ditto
+      polkit.enable = lib.mkDefault true; # ditto
       sudo.execWheelOnly = true;
     };
 
diff --git a/modules/nixos/base/users.nix b/modules/nixos/base/users.nix
index ddef714..b757fc5 100644
--- a/modules/nixos/base/users.nix
+++ b/modules/nixos/base/users.nix
@@ -11,7 +11,8 @@ in
 {
   options.base.users = {
     enable = lib.mkEnableOption "basic user configurations" // {
-      default = true;
+      default = config.base.enable;
+      defaultText = lib.literalExpression "config.base.enable";
     };
 
     defaultRoot = {
diff --git a/modules/nixos/desktop/audio.nix b/modules/nixos/desktop/audio.nix
index 06ce693..6361687 100644
--- a/modules/nixos/desktop/audio.nix
+++ b/modules/nixos/desktop/audio.nix
@@ -6,11 +6,15 @@ in
   options.desktop.audio = {
     enable = lib.mkEnableOption "desktop audio configuration" // {
       default = config.desktop.enable;
+      defaultText = lib.literalExpression "config.desktop.enable";
     };
   };
 
   config = lib.mkIf cfg.enable {
+    # we only want pipewire
     hardware.pulseaudio.enable = false;
+
+    # this is recommended for both, though
     security.rtkit.enable = true;
 
     services = {
diff --git a/modules/nixos/desktop/budgie/default.nix b/modules/nixos/desktop/budgie/default.nix
index fb97877..e8bfbb9 100644
--- a/modules/nixos/desktop/budgie/default.nix
+++ b/modules/nixos/desktop/budgie/default.nix
@@ -10,6 +10,7 @@ in
 {
   options.desktop.budgie.enable = lib.mkEnableOption "Budgie desktop";
 
+  # TODO: improve this module
   config = lib.mkIf cfg.enable {
     environment = {
       budgie.excludePackages = with pkgs; [
@@ -42,6 +43,7 @@ in
     };
 
     services.xserver = {
+      # fedora uses these by default
       displayManager.lightdm.greeters.slick = {
         theme = {
           name = "Materia-dark";
@@ -55,6 +57,7 @@ in
 
       desktopManager.budgie = {
         enable = true;
+        # make sure we actually use the above themes
         extraGSettingsOverrides = ''
           [org.gnome.desktop.interface:Budgie]
           color-scheme='prefer-dark'
diff --git a/modules/nixos/desktop/fonts.nix b/modules/nixos/desktop/fonts.nix
index d85af17..ebaeca1 100644
--- a/modules/nixos/desktop/fonts.nix
+++ b/modules/nixos/desktop/fonts.nix
@@ -11,6 +11,7 @@ in
   options.desktop.fonts = {
     enable = lib.mkEnableOption "desktop fonts" // {
       default = config.desktop.enable;
+      defaultText = lib.literalExpression "config.desktop.enable";
     };
   };
 
diff --git a/modules/nixos/desktop/gnome/default.nix b/modules/nixos/desktop/gnome/default.nix
index 1763e6b..080320f 100644
--- a/modules/nixos/desktop/gnome/default.nix
+++ b/modules/nixos/desktop/gnome/default.nix
@@ -22,7 +22,7 @@ in
       };
 
       systemPackages = with pkgs; [
-        adw-gtk3
+        adw-gtk3 # make gtk3 apps look good
         blackbox-terminal
         celluloid
       ];
diff --git a/modules/nixos/desktop/plasma/default.nix b/modules/nixos/desktop/plasma/default.nix
index 7c43907..c869b6e 100644
--- a/modules/nixos/desktop/plasma/default.nix
+++ b/modules/nixos/desktop/plasma/default.nix
@@ -24,8 +24,8 @@ in
       };
 
       systemPackages = [
-        pkgs.haruna
-        inputs.krunner-nix.packages.${pkgs.system}.default
+        pkgs.haruna # mpv frontend
+        inputs.krunner-nix.packages.${pkgs.system}.default # thank you leah
       ];
     };
 
diff --git a/modules/nixos/desktop/programs.nix b/modules/nixos/desktop/programs.nix
index 4b5f8e1..60d4735 100644
--- a/modules/nixos/desktop/programs.nix
+++ b/modules/nixos/desktop/programs.nix
@@ -11,6 +11,7 @@ in
   options.desktop.defaultPrograms = {
     enable = lib.mkEnableOption "default desktop programs" // {
       default = config.desktop.enable;
+      defaultText = lib.literalExpression "config.desktop.enable";
     };
   };
 
diff --git a/modules/nixos/server/default.nix b/modules/nixos/server/default.nix
index 567f46b..2ff257a 100644
--- a/modules/nixos/server/default.nix
+++ b/modules/nixos/server/default.nix
@@ -19,20 +19,25 @@ in
   ];
 
   config = lib.mkIf cfg.enable {
+    # all servers are most likely on stable, so we may want to pull some newer packages from time to time
     _module.args.unstable = inputs.nixpkgs.legacyPackages.${pkgs.stdenv.hostPlatform.system};
 
     boot.tmp.cleanOnBoot = lib.mkDefault true;
 
+    # we don't need it here
     documentation.enable = false;
 
     environment.defaultPackages = lib.mkForce [ ];
 
     nix = {
       gc = {
+        # ~every 2 days
         dates = "Mon,Wed,Fri *-*-* 00:00:00";
         options = "-d --delete-older-than 2d";
       };
 
+      # hardening access to `nix` on servers as no other users
+      # *should* ever really touch it
       settings.allowed-users = [ config.networking.hostName ];
     };
   };
diff --git a/modules/nixos/server/host-user.nix b/modules/nixos/server/host-user.nix
index 0764cb0..c60bfe3 100644
--- a/modules/nixos/server/host-user.nix
+++ b/modules/nixos/server/host-user.nix
@@ -10,8 +10,9 @@ let
 in
 {
   options.server.hostUser = {
-    enable = lib.mkEnableOption "${hostName} user configuration" // {
+    enable = lib.mkEnableOption "a default interactive user" // {
       default = config.server.enable;
+      defaultText = lib.literalExpression "config.server.enable";
     };
 
     manageSecrets = lib.mkEnableOption "automatic management of secrets" // {
diff --git a/modules/nixos/server/mixins/cloudflared.nix b/modules/nixos/server/mixins/cloudflared.nix
index 43da9de..9a56aaa 100644
--- a/modules/nixos/server/mixins/cloudflared.nix
+++ b/modules/nixos/server/mixins/cloudflared.nix
@@ -12,13 +12,13 @@ in
   options.server.mixins.cloudflared = {
     enable = lib.mkEnableOption "cloudflared mixin";
     tunnelName = lib.mkOption {
+      description = ''
+        Name of the default tunnel being created
+      '';
       type = lib.types.str;
       default = "${config.networking.hostName}-nginx";
       defaultText = lib.literalExpression "\${config.networking.hostName}-nginx";
       example = "my-tunnel";
-      description = ''
-        Name of the default tunnel being created
-      '';
     };
 
     manageSecrets = lib.mkEnableOption "automatic management of secrets" // {
@@ -35,6 +35,7 @@ in
           tunnels.${cfg.tunnelName} = {
             default = "http_status:404";
 
+            # map our virtualHosts from nginx to ingress rules
             ingress = lib.mapAttrs (_: _: {
               service = "http://localhost:${toString nginx.defaultHTTPListenPort}";
             }) nginx.virtualHosts;
diff --git a/modules/nixos/server/mixins/hercules.nix b/modules/nixos/server/mixins/hercules.nix
index 7d0b1fb..a04f9b1 100644
--- a/modules/nixos/server/mixins/hercules.nix
+++ b/modules/nixos/server/mixins/hercules.nix
@@ -22,6 +22,7 @@ in
       {
         services.hercules-ci-agent = {
           enable = true;
+          # we want newer features
           package = unstable.hercules-ci-agent;
         };
       }
diff --git a/modules/nixos/server/mixins/promtail.nix b/modules/nixos/server/mixins/promtail.nix
index 6b4cf32..173a85b 100644
--- a/modules/nixos/server/mixins/promtail.nix
+++ b/modules/nixos/server/mixins/promtail.nix
@@ -10,6 +10,7 @@ in
     clients = lib.mkOption {
       type = types.listOf types.attrs;
       default = [ { } ];
+      defaultText = lib.literalExpression "[ { } ]";
       description = "Clients for promtail";
     };
   };
diff --git a/modules/nixos/traits/24.05-compat.nix b/modules/nixos/traits/24.05-compat.nix
index b6422d1..d275f9c 100644
--- a/modules/nixos/traits/24.05-compat.nix
+++ b/modules/nixos/traits/24.05-compat.nix
@@ -1,6 +1,8 @@
+# collection of fun workarounds for the stable branch of nixos
 { lib, ... }:
 {
   imports = lib.optionals (lib.versionOlder lib.version "24.11pre") [
+    # https://github.com/NixOS/nixpkgs/pull/320228
     (lib.mkAliasOptionModule
       [
         "hardware"
diff --git a/modules/nixos/traits/nvidia.nix b/modules/nixos/traits/nvidia.nix
index 5fec7db..1b37086 100644
--- a/modules/nixos/traits/nvidia.nix
+++ b/modules/nixos/traits/nvidia.nix
@@ -17,12 +17,13 @@ in
   config = lib.mkIf cfg.enable (
     lib.mkMerge [
       {
+        # NOTE: this is experiemental
         boot.kernelParams = lib.optional usingNvidia "nvidia_drm.fbdev=1";
 
         services.xserver.videoDrivers = [ "nvidia" ];
 
         hardware = {
-          graphics.extraPackages = [ pkgs.vaapiVdpau ];
+          graphics.extraPackages = [ pkgs.vaapiVdpau ]; # TODO: does this work...?
           nvidia = {
             package = lib.mkDefault config.boot.kernelPackages.nvidiaPackages.latest;
             modesetting.enable = true;
@@ -34,10 +35,14 @@ in
         specialisation = {
           nvk.configuration = {
             boot = {
+              # required for GSP firmware
               kernelParams = [ "nouveau.config=NvGspRm=1" ];
+              # we want early KMS 
+              # https://wiki.archlinux.org/title/Kernel_mode_setting#Early_KMS_start
               initrd.kernelModules = [ "nouveau" ];
             };
 
+            # TODO: make sure we don't need this anymore
             environment.sessionVariables = {
               MESA_VK_VERSION_OVERRIDE = "1.3";
             };
diff --git a/modules/nixos/traits/tailscale.nix b/modules/nixos/traits/tailscale.nix
index 7e76f58..ea38e5c 100644
--- a/modules/nixos/traits/tailscale.nix
+++ b/modules/nixos/traits/tailscale.nix
@@ -18,6 +18,7 @@ in
     lib.mkMerge [
       {
         networking.firewall = {
+          # all connections from tailscale are safe...or should be
           trustedInterfaces = [ config.services.tailscale.interfaceName ];
         };
 
diff --git a/modules/shared/base/nix.nix b/modules/shared/base/nix.nix
index 1085e28..dd94939 100644
--- a/modules/shared/base/nix.nix
+++ b/modules/shared/base/nix.nix
@@ -11,6 +11,7 @@ in
   options.base.nixSettings = {
     enable = lib.mkEnableOption "basic Nix settings" // {
       default = config.base.enable;
+      defaultText = lib.literalExpression "config.base.enable";
     };
 
     lix.enable = lib.mkEnableOption "the use of Lix over Nix" // {
@@ -30,6 +31,7 @@ in
             "flakes"
             "auto-allocate-uids"
           ]
+          # TODO: remove this nonsense when all implementations remove repl-flake
           ++ lib.optional (
             lib.versionOlder config.nix.package.version "2.22.0" # repl-flake was removed in nix 2.22.0
             || lib.versionAtLeast config.nix.package.version "2.90.0-rc1" # but not in lix yet
diff --git a/modules/shared/base/programs.nix b/modules/shared/base/programs.nix
index bba27b3..fc853f8 100644
--- a/modules/shared/base/programs.nix
+++ b/modules/shared/base/programs.nix
@@ -3,6 +3,7 @@
   options.base.defaultPrograms = {
     enable = lib.mkEnableOption "default programs" // {
       default = config.base.enable;
+      defaultText = lib.literalExpression "config.base.enable";
     };
   };
 }