From 65c84f5b39dad981f5b42cc1d0f23fc1be091094 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Wed, 7 Oct 2026 18:20:53 -0400
Subject: [PATCH] docs(nixos): clarify host module options

---
 configs/nixos/modules/host/cachyos.nix |  2 +-
 configs/nixos/modules/host/zfs.nix     | 19 +++++++------------
 2 files changed, 8 insertions(+), 13 deletions(-)

diff --git a/configs/nixos/modules/host/cachyos.nix b/configs/nixos/modules/host/cachyos.nix
index 705b186..e628c71 100644
--- a/configs/nixos/modules/host/cachyos.nix
+++ b/configs/nixos/modules/host/cachyos.nix
@@ -5,7 +5,7 @@
   ...
 }:
 {
-  options.modules.host.cachyos.enable = lib.mkEnableOption "CachyOS kernel";
+  options.modules.host.cachyos.enable = lib.mkEnableOption "the CachyOS kernel";
 
   config = lib.mkIf config.modules.host.cachyos.enable {
     boot.kernelPackages = pkgs.linuxPackages_cachyos;
diff --git a/configs/nixos/modules/host/zfs.nix b/configs/nixos/modules/host/zfs.nix
index 794e616..9883206 100644
--- a/configs/nixos/modules/host/zfs.nix
+++ b/configs/nixos/modules/host/zfs.nix
@@ -3,13 +3,13 @@
   lib,
   ...
 }:
-# The host-level ZFS pool import: durable service state a host mounts, never rebuilds.
+# Imports existing ZFS pools that hold durable service state.
 let
   cfg = config.modules.host.zfs; # NOLINT(let_order)
 in
 {
   options.modules.host.zfs = {
-    enable = lib.mkEnableOption "importing durable ZFS pools that hold service state";
+    enable = lib.mkEnableOption "ZFS pool imports for durable service state";
 
     pools = lib.mkOption {
       type = lib.types.attrsOf (lib.types.attrsOf lib.types.path);
@@ -23,29 +23,24 @@ in
         }
       '';
       description = ''
-        The ZFS pools to import at boot, keyed by pool name, each pool mapping a
-        dataset path relative to it to that dataset's mountpoint. A pool is
-        durable state imported as it stands, never created or destroyed by a
-        rebuild, so a service's data survives any rebuild or reimage. A pool
-        with an empty map is still imported, leaving each dataset to its own ZFS
-        `mountpoint` property.
+        Lists pools that NixOS imports at boot.
+        Maps each dataset name to its mount point.
+        NixOS does not create or destroy these pools during rebuilds.
+        An empty map imports the pool without declaring file systems.
       '';
     };
   };
 
   config = lib.mkIf cfg.enable {
-    # The ZFS stack in the kernel and boot, needed even where the root filesystem is another kind.
     boot.supportedFilesystems = [ "zfs" ];
 
-    # Derive a stable 32-bit host ID from the configured hostname.
+    # This module derives a stable host ID from the configured hostname.
     networking.hostId = builtins.substring 0 8 (
       builtins.hashString "sha256" config.networking.hostName
     );
 
-    # The declared pools are imported at boot, distinct from any pool backing the root filesystem.
     boot.zfs.extraPools = lib.attrNames cfg.pools;
 
-    # Each declared dataset is mounted at its host path as a native ZFS filesystem.
     fileSystems = lib.mkMerge (
       lib.mapAttrsToList (
         pool: mounts:
-- 
2.47.3