docs: Update inline code docs for LSP help

sw/builders/default.nix

@@ -17,87 +17,99 @@ let
   cfg = config.athenix.sw.builders;
 in
 {
-  options.athenix.sw.builders = {
+  options.athenix.sw.builders = mkOption {
-    enable = mkOption {
+    type = lib.types.submodule {
-      type = types.bool;
+      options = {
-      default = false;
+        enable = mkOption {
-      description = ''
+          type = lib.types.bool;
-        Enable build server configuration.
+          default = false;
+          description = ''
+            Enable build server configuration.
 
-        Includes:
+            Includes:
-        - SSH host keys for common Git servers (factory.uga.edu, github.com)
+            - SSH host keys for common Git servers (factory.uga.edu, github.com)
-        - Gitea Actions runner support (optional)
+            - Gitea Actions runner support (optional)
-        - Build tools and dependencies
+            - Build tools and dependencies
 
-        Recommended for: CI/CD servers, build containers, development infrastructure
+            Recommended for: CI/CD servers, build containers, development infrastructure
-      '';
+          '';
-      example = true;
+          example = true;
-    };
+        };
 
-    giteaRunner = {
+        giteaRunner = mkOption {
-      enable = mkOption {
+          type = lib.types.submodule {
-        type = types.bool;
+            options = {
-        default = false;
+              enable = mkOption {
-        description = ''
+                type = lib.types.bool;
-          Enable Gitea Actions self-hosted runner.
+                default = false;
+                description = ''
+                  Enable Gitea Actions self-hosted runner.
 
-          This runner will connect to a Gitea instance and execute CI/CD workflows.
+                  This runner will connect to a Gitea instance and execute CI/CD workflows.
-          Requires manual setup of the token file before the service will start.
+                  Requires manual setup of the token file before the service will start.
-        '';
+                '';
-        example = true;
+                example = true;
-      };
+              };
 
-      url = mkOption {
+              url = mkOption {
-        type = types.str;
+                type = lib.types.str;
-        description = ''
+                description = ''
-          URL of the Gitea instance to connect to.
+                  URL of the Gitea instance to connect to.
-          This should be the base URL without any path components.
+                  This should be the base URL without any path components.
-        '';
+                '';
-        example = "https://git.factory.uga.edu";
+                example = "https://git.factory.uga.edu";
-      };
+              };
 
-      tokenFile = mkOption {
+              tokenFile = mkOption {
-        type = types.path;
+                type = lib.types.path;
-        default = "/var/lib/gitea-runner-token";
+                default = "/var/lib/gitea-runner-token";
-        description = ''
+                description = ''
-          Path to file containing Gitea runner registration token.
+                  Path to file containing Gitea runner registration token.
 
-          To generate:
+                  To generate:
-          1. Go to your Gitea repository settings
+                  1. Go to your Gitea repository settings
-          2. Navigate to Actions > Runners
+                  2. Navigate to Actions > Runners
-          3. Click "Create new Runner"
+                  3. Click "Create new Runner"
-          4. Save the token to this file:
+                  4. Save the token to this file:
-             echo "TOKEN=your-token-here" | sudo tee /var/lib/gitea-runner-token > /dev/null
+                     echo "TOKEN=your-token-here" | sudo tee /var/lib/gitea-runner-token > /dev/null
 
-          The service will not start until this file exists.
+                  The service will not start until this file exists.
-        '';
+                '';
-        example = "/var/secrets/gitea-runner-token";
+                example = "/var/secrets/gitea-runner-token";
-      };
+              };
 
-      extraLabels = mkOption {
+              extraLabels = mkOption {
-        type = types.listOf types.str;
+                type = lib.types.listOf lib.types.str;
-        default = [ ];
+                default = [ ];
-        description = ''
+                description = ''
-          Additional labels to identify this runner in workflow files.
+                  Additional labels to identify this runner in workflow files.
-          Use labels to target specific runners for different job types.
+                  Use labels to target specific runners for different job types.
-        '';
+                '';
-        example = [
+                example = [
-          "self-hosted"
+                  "self-hosted"
-          "nix"
+                  "nix"
-          "x86_64-linux"
+                  "x86_64-linux"
-        ];
+                ];
-      };
+              };
 
-      name = mkOption {
+              name = mkOption {
-        type = types.str;
+                type = lib.types.str;
-        default = "athenix";
+                default = "athenix";
-        description = ''
+                description = ''
-          Unique name for this runner instance.
+                  Unique name for this runner instance.
-          Shown in Gitea's runner list and logs.
+                  Shown in Gitea's runner list and logs.
-        '';
+                '';
-        example = "nix-builder-1";
+                example = "nix-builder-1";
+              };
+            };
+          };
+          default = { };
+          description = "Gitea Actions runner configuration.";
+        };
       };
     };
+    default = { };
+    description = "Build server configuration (CI/CD, Gitea Actions).";
   };
 
   config = mkIf cfg.enable (mkMerge [

sw/default.nix

@@ -37,8 +37,11 @@ in
   ];
 
   options.athenix.sw = {
+    # Software submodule for the Athenix system suite. sw.enable enables
+    # base packages and common configuration. Each sw.<type>.enable enables
+    # additional packages and services for that system type.
     enable = mkOption {
-      type = types.bool;
+      type = lib.types.bool;
       default = false;
       description = ''
         Enable standard workstation configuration with base packages.
@@ -53,17 +56,18 @@ in
       '';
     };
 
-    # DEPRECATED: Backwards compatibility for external modules
-    # Use athenix.sw.<type>.enable instead
     type = mkOption {
-      type = types.nullOr (types.either types.str (types.listOf types.str));
+      # DEPRECATED: Backwards compatibility for external modules
+      # Use athenix.sw.<type>.enable instead
+      type = lib.types.nullOr (lib.types.either lib.types.str (lib.types.listOf lib.types.str));
       default = null;
       description = "DEPRECATED: Use athenix.sw.<type>.enable instead. Legacy type selection.";
       visible = false;
     };
 
     extraPackages = mkOption {
-      type = types.listOf types.package;
+      # Additional packages to install beyond the defaults
+      type = lib.types.listOf lib.types.package;
       default = [ ];
       description = ''
         Additional system packages to install beyond the defaults.
@@ -73,7 +77,8 @@ in
     };
 
     excludePackages = mkOption {
-      type = types.listOf types.package;
+      # Packages to exclude from the default package list
+      type = lib.types.listOf lib.types.package;
       default = [ ];
       description = ''
         Packages to exclude from the default package list.

sw/desktop/default.nix

@@ -17,25 +17,31 @@ let
   cfg = config.athenix.sw.desktop;
 in
 {
-  options.athenix.sw.desktop = {
+  options.athenix.sw.desktop = mkOption {
-    enable = mkOption {
+    type = lib.types.submodule {
-      type = types.bool;
+      options = {
-      default = false;
+        enable = mkOption {
-      description = ''
+          type = lib.types.bool;
-        Enable full desktop environment with KDE Plasma 6.
+          default = false;
+          description = ''
+            Enable full desktop environment with KDE Plasma 6.
 
-        Includes:
+            Includes:
-        - KDE Plasma 6 desktop with SDDM display manager
+            - KDE Plasma 6 desktop with SDDM display manager
-        - Full graphical software suite (Firefox, Chromium, LibreOffice)
+            - Full graphical software suite (Firefox, Chromium, LibreOffice)
-        - Printing and scanning support (CUPS)
+            - Printing and scanning support (CUPS)
-        - Virtualization (libvirt, virt-manager)
+            - Virtualization (libvirt, virt-manager)
-        - Bluetooth and audio (PipeWire)
+            - Bluetooth and audio (PipeWire)
-        - Video conferencing (Zoom, Teams)
+            - Video conferencing (Zoom, Teams)
 
-        Recommended for: Workstations, development machines, user desktops
+            Recommended for: Workstations, development machines, user desktops
-      '';
+          '';
-      example = true;
+          example = true;
+        };
+      };
     };
+    default = { };
+    description = "Desktop environment configuration (KDE Plasma 6).";
   };
 
   config = mkIf cfg.enable (mkMerge [

sw/headless/default.nix

@@ -17,23 +17,29 @@ let
   cfg = config.athenix.sw.headless;
 in
 {
-  options.athenix.sw.headless = {
+  options.athenix.sw.headless = mkOption {
-    enable = mkOption {
+    type = lib.types.submodule {
-      type = types.bool;
+      options = {
-      default = false;
+        enable = mkOption {
-      description = ''
+          type = lib.types.bool;
-        Enable minimal headless server configuration.
+          default = false;
+          description = ''
+            Enable minimal headless server configuration.
 
-        Includes:
+            Includes:
-        - SSH server with password authentication
+            - SSH server with password authentication
-        - Minimal CLI tools (tmux, man)
+            - Minimal CLI tools (tmux, man)
-        - Systemd-networkd for networking
+            - Systemd-networkd for networking
-        - No graphical environment
+            - No graphical environment
 
-        Recommended for: Servers, containers (LXC), WSL, remote systems
+            Recommended for: Servers, containers (LXC), WSL, remote systems
-      '';
+          '';
-      example = true;
+          example = true;
+        };
+      };
     };
+    default = { };
+    description = "Headless server configuration (SSH, minimal CLI tools).";
   };
 
   config = mkIf cfg.enable (mkMerge [

sw/stateless-kiosk/default.nix

@@ -14,36 +14,42 @@ let
   cfg = config.athenix.sw.stateless-kiosk;
 in
 {
-  options.athenix.sw.stateless-kiosk = {
+  options.athenix.sw.stateless-kiosk = mkOption {
-    enable = mkOption {
+    type = lib.types.submodule {
-      type = types.bool;
+      options = {
-      default = false;
+        enable = mkOption {
-      description = ''
+          type = lib.types.bool;
-        Enable stateless kiosk mode for diskless PXE boot systems.
+          default = false;
+          description = ''
+            Enable stateless kiosk mode for diskless PXE boot systems.
 
-        Includes:
+            Includes:
-        - Sway (Wayland compositor)
+            - Sway (Wayland compositor)
-        - Chromium in fullscreen kiosk mode
+            - Chromium in fullscreen kiosk mode
-        - MAC address-based URL routing
+            - MAC address-based URL routing
-        - Network-only boot (no local storage)
+            - Network-only boot (no local storage)
-        - Auto-start browser on boot
+            - Auto-start browser on boot
 
-        Recommended for: Assembly line stations, diskless kiosks, PXE boot displays
+            Recommended for: Assembly line stations, diskless kiosks, PXE boot displays
-      '';
+          '';
-      example = true;
+          example = true;
-    };
+        };
-
+
-    kioskUrl = mkOption {
+        kioskUrl = mkOption {
-      type = types.str;
+          type = lib.types.str;
-      default = "https://ha.factory.uga.edu";
+          default = "https://ha.factory.uga.edu";
-      description = ''
+          description = ''
-        Default URL to display in the kiosk browser.
+            Default URL to display in the kiosk browser.
-
+
-        Note: For stateless-kiosk, MAC address-based routing may override this.
+            Note: For stateless-kiosk, MAC address-based routing may override this.
-        See sw/stateless-kiosk/mac-hostmap.nix for MAC-to-URL mappings.
+            See sw/stateless-kiosk/mac-hostmap.nix for MAC-to-URL mappings.
-      '';
+          '';
-      example = "https://homeassistant.lan:8123/lovelace/dashboard";
+          example = "https://homeassistant.lan:8123/lovelace/dashboard";
+        };
+      };
     };
+    default = { };
+    description = "Stateless kiosk configuration (PXE boot, Sway, MAC-based routing).";
   };
 
   config = mkIf cfg.enable (mkMerge [

sw/tablet-kiosk/default.nix

@@ -12,35 +12,41 @@ let
   cfg = config.athenix.sw.tablet-kiosk;
 in
 {
-  options.athenix.sw.tablet-kiosk = {
+  options.athenix.sw.tablet-kiosk = mkOption {
-    enable = mkOption {
+    type = lib.types.submodule {
-      type = types.bool;
+      options = {
-      default = false;
+        enable = mkOption {
-      description = ''
+          type = lib.types.bool;
-        Enable tablet kiosk mode with touch-optimized interface.
+          default = false;
+          description = ''
+            Enable tablet kiosk mode with touch-optimized interface.
 
-        Includes:
+            Includes:
-        - Phosh mobile desktop environment
+            - Phosh mobile desktop environment
-        - Chromium in fullscreen kiosk mode
+            - Chromium in fullscreen kiosk mode
-        - On-screen keyboard (Squeekboard)
+            - On-screen keyboard (Squeekboard)
-        - Auto-login and auto-start browser
+            - Auto-login and auto-start browser
-        - Touch gesture support
+            - Touch gesture support
-        - Optimized for Surface Pro tablets
+            - Optimized for Surface Pro tablets
 
-        Recommended for: Surface tablets, touchscreen kiosks, interactive displays
+            Recommended for: Surface tablets, touchscreen kiosks, interactive displays
-      '';
+          '';
-      example = true;
+          example = true;
-    };
+        };
-
+
-    kioskUrl = mkOption {
+        kioskUrl = mkOption {
-      type = types.str;
+          type = lib.types.str;
-      default = "https://ha.factory.uga.edu";
+          default = "https://ha.factory.uga.edu";
-      description = ''
+          description = ''
-        URL to display in the kiosk browser on startup.
+            URL to display in the kiosk browser on startup.
-        The browser will automatically navigate to this URL in fullscreen mode.
+            The browser will automatically navigate to this URL in fullscreen mode.
-      '';
+          '';
-      example = "https://dashboard.example.com";
+          example = "https://dashboard.example.com";
+        };
+      };
     };
+    default = { };
+    description = "Tablet kiosk configuration (Phosh, touch interface).";
   };
 
   config = mkIf cfg.enable (mkMerge [

sw/updater.nix

@@ -9,10 +9,10 @@ with lib;
 
 {
   options.athenix.sw.remoteBuild = lib.mkOption {
-    type = types.submodule {
+    type = lib.types.submodule {
       options = {
         hosts = mkOption {
-          type = types.listOf types.str;
+          type = lib.types.listOf lib.types.str;
           default = [ "engr-ugaif@192.168.11.133 x86_64-linux" ];
           description = ''
             List of remote build hosts for system rebuilding.
@@ -31,7 +31,7 @@ with lib;
         };
 
         enable = mkOption {
-          type = types.bool;
+          type = lib.types.bool;
           default = false;
           description = ''
             Whether to enable remote builds for the 'update-system' command.