now there's docs

7 files changed, 112 insertions, 77 deletions

diff --git a/modules/boot/options.nix b/modules/boot/options.nix
index 2f670f9..9e85570 100644
--- a/modules/boot/options.nix
+++ b/modules/boot/options.nix
@@ -1,9 +1,11 @@
 {
+  my-lib,
   config,
   lib,
   ...
 }: let
-  inherit (lib) mkOption mkEnableOption types;
+  inherit (lib) mkOption mkEnableOption;
+  inherit (my-lib.options {inherit lib config;}) mkThemeOption;
 in {
   options = {
     collinux.boot = {
@@ -15,10 +17,7 @@ in {
       };
       plymouth = {
         enable = mkEnableOption "plymouth bootsplash";
-        theme = mkOption {
-          type = types.enum ["catppuccin" "adwaita"];
-          default = config.collinux.theme;
-        };
+        theme = mkThemeOption "plymouth";
       };
       secureBoot.enable = mkEnableOption "lanzaboote";
     };
diff --git a/modules/desktop/options.nix b/modules/desktop/options.nix
index 1067d0b..e59ed68 100644
--- a/modules/desktop/options.nix
+++ b/modules/desktop/options.nix
@@ -6,7 +6,7 @@
   ...
 }: let
   inherit (lib) mkOption mkEnableOption types;
-  inherit (my-lib.options {inherit lib config;}) mkProgramOption;
+  inherit (my-lib.options {inherit lib config;}) mkProgramOption mkThemeOption;
 in {
   options = {
     collinux.desktop = {
@@ -17,12 +17,14 @@ in {
       wallpaper_cmd = mkOption {
         type = types.str;
         default = "${lib.getExe pkgs.wbg} -s ${config.collinux.desktop.wallpaper}";
+        internal = true;
       };
 
       greetd = {
         enable = mkEnableOption "greetd greeter";
         command = mkOption {
           type = lib.types.str;
+          internal = true;
           default = let
             cfg = config.collinux.desktop;
           in
@@ -40,7 +42,6 @@ in {
         niri.enable = mkEnableOption "niri";
 
         components = {
-          # waybar = mkProgramOption "waybar";
           dunst = mkProgramOption "dunst";
           fuzzel = mkProgramOption "fuzzel";
         };
@@ -49,54 +50,63 @@ in {
 
       gtk = {
         enable = mkEnableOption "gtk theming";
-        theme = mkOption {
-          type = types.enum ["catppuccin" "adwaita" "kanagawa"];
-          default = config.collinux.theme;
-        };
-        cursor_data = {
-          package = mkOption {
-            type = lib.types.package;
-            default =
-              if (config.collinux.desktop.gtk.theme == "catppuccin")
-              then pkgs.catppuccin-cursors.mochaDark
-              else if (config.collinux.desktop.gtk.theme == "adwaita")
-              then pkgs.vanilla-dmz
-              else null;
-          };
-          name = mkOption {
-            type = lib.types.str;
-            default =
-              if (config.collinux.desktop.gtk.theme == "catppuccin")
-              then "catppuccin-mocha-dark-cursors"
-              else if (config.collinux.desktop.gtk.theme == "adwaita")
-              then "Vanilla-DMZ"
-              else null;
+        theme = mkThemeOption "gtk";
+
+        cursor_data = mkOption {
+          internal = true;
+          type = lib.types.submodule {
+            package = mkOption {
+              internal = true;
+              type = lib.types.package;
+            };
+            name = mkOption {
+              internal = true;
+              type = lib.types.str;
+            };
           };
+          default =
+            if config.collinux.desktop.gtk.theme == "catppuccin"
+            then {
+              name = "catppuccin-mocha-dark-cursors";
+              package = pkgs.catppuccin-cursors.mochaDark;
+            }
+            else if config.collinux.gtk.theme == "adwaita"
+            then {
+              name = "Vanilla-DMZ";
+              package = pkgs.vanilla-dmz;
+            }
+            else null;
         };
-        theme_data = {
-          package = mkOption {
-            type = lib.types.package;
-            default =
-              if (config.collinux.desktop.gtk.theme == "catppuccin")
-              then
-                (pkgs.catppuccin-gtk.override {
-                  variant = "mocha";
-                  accents = ["blue"];
-                  size = "standard";
-                })
-              else if (config.collinux.desktop.gtk.theme == "adwaita")
-              then pkgs.adw-gtk3
-              else "";
-          };
-          name = mkOption {
-            type = lib.types.str;
-            default =
-              if (config.collinux.desktop.gtk.theme == "catppuccin")
-              then "catppuccin-mocha-blue-standard"
-              else if (config.collinux.desktop.gtk.theme == "adwaita")
-              then "adw-gtk3"
-              else "";
+
+        theme_data = mkOption {
+          internal = true;
+          type = lib.types.submodule {
+            package = mkOption {
+              internal = true;
+              type = lib.types.package;
+            };
+            name = mkOption {
+              internal = true;
+              type = lib.types.str;
+            };
           };
+
+          default =
+            if config.collinux.desktop.gtk.theme == "catppuccin"
+            then {
+              package = pkgs.catppuccin-gtk.override {
+                variant = "mocha";
+                accents = ["blue"];
+                size = "standard";
+              };
+              name = "catppuccin-mocha-blue-standard";
+            }
+            else if config.collinux.desktop.gtk.theme == "adwaita"
+            then {
+              package = pkgs.adw-gtk3;
+              name = "adw-gtk3";
+            }
+            else null;
         };
       };
 
@@ -106,11 +116,9 @@ in {
           profileName = mkOption {
             type = types.str;
             default = config.collinux.user.name;
+            internal = true;
           };
-          theme = mkOption {
-            type = types.enum ["none" "catppuccin" "adwaita" "kanagawa"];
-            default = config.collinux.theme;
-          };
+          theme = mkThemeOption "firefox";
           extensions.zotero.enable = mkOption {
             description = "install Zotero Connector for Firefox";
             default = config.collinux.desktop.programs.research.enable;
@@ -122,7 +130,7 @@ in {
         ghostty.enable = mkEnableOption "ghostty";
         alacritty.enable = mkEnableOption "alacritty";
 
-        research.enable = mkEnableOption "zathura, Xournal++, Zotero, Zotero Connector";
+        research.enable = mkEnableOption "zathura, Xournal++, Zotero";
       };
     };
   };
diff --git a/modules/options.nix b/modules/options.nix
index 65de32e..8ecf1d7 100644
--- a/modules/options.nix
+++ b/modules/options.nix
@@ -7,15 +7,18 @@
 in {
   options = {
     collinux.theme = mkOption {
+      description = "System-wide theme";
       type = types.enum ["catppuccin" "adwaita" "kanagawa"];
     };
 
     collinux.palette = let
       colorOption = lib.mkOption {
         type = lib.types.strMatching "^([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$";
+        internal = true;
       };
     in
       lib.mkOption {
+        internal = true;
         type = lib.types.submodule {
           options = {
             base00 = colorOption;
diff --git a/modules/secrets/options.nix b/modules/secrets/options.nix
index de15f50..fa53d6f 100644
--- a/modules/secrets/options.nix
+++ b/modules/secrets/options.nix
@@ -3,25 +3,33 @@
 in {
   options = {
     collinux.secrets = lib.mkOption {
+      description = "Atribute set of secrets";
       type = lib.types.attrsOf (
         lib.types.submodule ({config, ...}: {
           options = {
             name = mkOption {
               type = lib.types.str;
               default = config._module.args.name;
+              internal = true;
+            };
+            file = mkOption {
+              description = "Name of the file in the /run/secrets.d";
+              type = lib.types.path;
             };
-            file = mkOption {type = lib.types.path;};
             mode = mkOption {
+              description = "Permissions mode of the decrypted secret in a format understood by chmod";
               type = lib.types.str;
               default = "0400";
             };
             owner = mkOption {
+              description = "Owner of the decrypted secret file";
               type = lib.types.str;
               default = "0";
             };
             path = mkOption {
               type = lib.types.str;
               default = "/run/secrets.d/${config.name}";
+              description = "Path where the decrypted secret is installed";
             };
           };
         })
diff --git a/modules/services/options.nix b/modules/services/options.nix
index 16bf5ac..231c949 100644
--- a/modules/services/options.nix
+++ b/modules/services/options.nix
@@ -18,36 +18,47 @@ in {
 
         networkd = {
           enable = mkEnableOption "use systemd-networkd";
-          ssid = mkOption {type = lib.types.str;};
-          pskFile = mkOption {type = lib.types.str;};
+          ssid = mkOption {
+            description = "SSID for this network";
+            type = lib.types.str;
+          };
+          pskFile = mkOption {
+            description = "Absolute path to a file containing the pre-shared key for this network";
+            type = lib.types.str;
+            example = "/run/secrets.d/wifi-psk";
+          };
 
           static = lib.mkOption {
+            description = "Set a static IP address for this device on this network. Set to null to use DHCP";
             type = lib.types.nullOr (lib.types.submodule {
               options = {
-                ip = mkOption {type = ip_addr_cidr;};
-                gateway = mkOption {type = ip_addr;};
+                ip = mkOption {
+                  description = "IP address";
+                  type = ip_addr_cidr;
+                };
+                gateway = mkOption {
+                  description = "default gateway";
+                  type = ip_addr;
+                };
               };
             });
             default = null;
           };
         };
-        tailscale = {
-          enable = mkEnableOption "tailscale";
-          tailnet = mkOption {
-            type = lib.types.str;
-            default = "tail7cca06.ts.net";
-          };
-        };
+
+        tailscale.enable = mkEnableOption "tailscale";
+
         sshd = {
           enable = mkEnableOption "OpenSSH server";
           bind_host = mkOption {
+            description = "The IP address on which OpenSSH will listen for incomming connections. The default, `0.0.0.0`, means 'all interfaces'";
             type = ip_addr;
             default = "0.0.0.0";
           };
         };
       };
 
-      audio.enable = mkEnableOption "pipewire + wireplumber";
+      audio.enable = mkEnableOption "pipewire and wireplumber";
 
       bluetooth = {
         enable = mkEnableOption "bluetooth";
@@ -64,24 +75,28 @@ in {
 
           service_name = mkOption {
             type = lib.types.str;
+            internal = true;
           };
 
           bind_host = mkOption {
+            description = "The IP address on which ${service_name} will listen for incoming connections. The default, `0.0.0.0`, means 'all interfaces'";
             type = ip_addr;
             default = "0.0.0.0";
           };
           port = mkOption {
+            description = "The port on which ${service_name} will listen for incomming connections";
             type = lib.types.port;
             default = default_port;
           };
 
           root_url = mkOption {
+            description = "The final url that this service will be hosted on. Required for caddy, otherwise optional";
             type = lib.types.nullOr lib.types.str;
           };
 
           caddy = {
             enable = mkEnableOption "Automatically create caddy configurations for this service";
-            bind_tailscale = mkEnableOption "Bind the service to {service_name}.{tailnet}";
+            bind_tailscale = mkEnableOption "Bind the service to ${service_name}.{tailnet}";
           };
         };
       in {
@@ -103,7 +118,9 @@ in {
         caddy = {
           enable = mkEnableOption "caddy https server";
           envFile = mkOption {
+            description = "Absolute path to file that contains environment variables for caddy operations";
             type = lib.types.str;
+            example = "/run/secrets.d/caddy-env";
           };
         };
       };
diff --git a/modules/terminal/options.nix b/modules/terminal/options.nix
index 25e0eb4..8207be3 100644
--- a/modules/terminal/options.nix
+++ b/modules/terminal/options.nix
@@ -6,7 +6,7 @@
   ...
 }: let
   inherit (lib) mkOption mkEnableOption types;
-  inherit (my-lib.options {inherit lib config;}) mkProgramOption;
+  inherit (my-lib.options {inherit lib config;}) mkProgramOption mkThemeOption;
 in {
   options = {
     collinux.terminal = {
@@ -37,10 +37,11 @@ in {
         git = {
           enable = mkEnableOption "git";
           userName = mkOption {
+            description = "Public name uses for git";
             type = types.str;
-            default = config.collinux.user.name;
           };
           userEmail = mkOption {
+            description = "Public email used for git";
             type = types.str;
           };
           installKey = mkEnableOption "automatically install github authentication key";
@@ -48,10 +49,7 @@ in {
 
         helix = {
           enable = mkEnableOption "helix text editor";
-          theme = mkOption {
-            type = lib.types.enum ["catppuccin" "adwaita" "kanagawa"];
-            default = config.collinux.theme;
-          };
+          theme = mkThemeOption "helix";
           hardMode = mkOption {
             type = types.bool;
             description = "Disable arrow keys and mouse";
diff --git a/modules/user/options.nix b/modules/user/options.nix
index 1024494..d805bf9 100644
--- a/modules/user/options.nix
+++ b/modules/user/options.nix
@@ -4,9 +4,11 @@ in {
   options = {
     collinux.user = {
       name = mkOption {
+        description = "Name for the sole user of this system";
         type = types.str;
       };
       isAdmin = mkOption {
+        description = "Whether this user is an admin";
         type = types.bool;
         default = true;
       };