+ docs and description

flake-module.nix

@@ -22,11 +22,19 @@ in
             cache = mkOption {
               type = types.addCheck types.str (s: (builtins.substring 0 1 s) == ".");
               default = "./secrets/cache";
+              defaultText = lib.literalExpression "./secrets/cache";
+              description = ''
+                `path str` that relative to flake root, used for storing host public key
+                re-encrypted secrets.
+              '';
             };
             nodes = mkOption {
               type = types.lazyAttrsOf types.unspecified;
               default = self.nixosConfigurations;
               defaultText = lib.literalExpression "self.nixosConfigurations";
+              description = ''
+                nixos systems that vaultix to manage.
+              '';
             };
             identity = mkOption {
               type =
@@ -37,13 +45,22 @@ in
                 nullOr identityPathType;
               default = null;
               example = ./password-encrypted-identity.pub;
+              description = ''
+                `Age identity file`.
+                Able to use yubikey, see <https://github.com/str4d/age-plugin-yubikey>.
+                Supports age native secrets (recommend protected with passphrase)
+              '';
             };
             extraRecipients = mkOption {
               type = with types; listOf (coercedTo path toString str);
               default = [ ];
               example = [
                 "age1qyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqs3290gq"
               ];
+              description = ''
+                Recipients used for backup. Any of identity of them will able
+                to decrypt all secrets.
+              '';
             };
             app = mkOption {
               type = types.lazyAttrsOf (types.lazyAttrsOf types.package);
@@ -71,10 +88,19 @@ in
                   )
               ) config.allSystems;
               readOnly = true;
+              defaultText = "Auto generate by flake module";
+              description = ''
+                vaultix apps that auto generate by its flake module.
+                Run manually with `nix run .#vaultix.app.$system.<app-name>`
+              '';
             };
           };
         });
         default = { };
+        description = ''
+          A single-admin secret manage scheme for nixos, with support of templates and
+          agenix-like secret configuration layout.
+        '';
       };
     };
 
@@ -90,6 +116,9 @@ in
             type = types.unspecified;
             default = pkgs;
             defaultText = lib.literalExpression "pkgs";
+            description = ''
+              pkgs that passed into vaultix apps.
+            '';
           };
         };
       }

module/default.nix

@@ -35,13 +35,18 @@ let
         default = builtins.path {
           path = "/" + self + "/" + self.vaultix.cache + "/" + config.networking.hostName;
         };
+        defaultText = literalExpression "path in store";
+        description = ''
+          Secrets re-encrypted by each host public key. In nix store.
+        '';
       };
 
       decryptedDir = mkOption {
         type = types.path;
         default = "/run/vaultix";
+        defaultText = literalExpression "/run/vaultix";
         description = ''
-          Folder where secrets are symlinked to
+          Folder where secrets are symlinked to.
         '';
       };
 
@@ -59,15 +64,28 @@ let
           }
         );
         default = config.services.openssh.hostKeys;
+        defaultText = literalExpression "config.services.openssh.hostKeys";
         readOnly = true;
         description = ''
-          `config.services.openssh.hostKeys`
+          Ed25519 host private ssh key (identity) path that used for decrypting secrets while deploying.
+          Default is `config.services.openssh.hostKeys`.
+
+          Default format:
+          ```nix
+          [
+            {
+              path = "/path/to/ssh_host_ed25519_key";
+              type = "ed25519";
+            }
+          ]
+          ```
         '';
       };
 
       hostIdentifier = mkOption {
         type = types.str;
         default = config.networking.hostName;
+        defaultText = literalExpression "config.networking.hostName";
         readOnly = true;
         description = ''
           Host identifier
@@ -85,21 +103,24 @@ let
             description = "${types.str.description} (with check: non-empty without trailing slash)";
           };
         default = "/run/vaultix.d";
+        defaultText = literalExpression "/run/vaultix.d";
         description = ''
           Where secrets are created before they are symlinked to {option}`vaultix.settings.decryptedDir`
         '';
       };
 
       hostPubkey = mkOption {
         type = with types; coercedTo path (x: if isPath x then readFile x else x) str;
-        #example = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI.....";
-        #example = "age1qyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqs3290gq";
         example = literalExpression "./secrets/host1.pub";
-        #example = "/etc/ssh/ssh_host_ed25519_key.pub";
+        description = ''
+          str or path that contains host public key.
+          example:
+          "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI....."
+          "age1qyqszqgpqyqszqgpqyqszqgpqyqszqgpq....."
+          "/etc/ssh/ssh_host_ed25519_key.pub"
+        '';
       };
-
     };
-
   });
 
   secretType = types.submodule (submod: {