Add missing descriptions and improve existing ones

Closes #81

home-manager.nix

@@ -93,6 +93,40 @@ in
             };
         })
       );
+      description = ''
+        A set of persistent storage location submodules listing the
+        files and directories to link to their respective persistent
+        storage location.
+
+        Each attribute name should be the path relative to the user's
+        home directory.
+
+        For detailed usage, check the <link
+        xlink:href="https://github.com/nix-community/impermanence">documentation</link>.
+      '';
+      example = literalExpression ''
+        {
+          "/persistent/home/talyz" = {
+            directories = [
+              "Downloads"
+              "Music"
+              "Pictures"
+              "Documents"
+              "Videos"
+              "VirtualBox VMs"
+              ".gnupg"
+              ".ssh"
+              ".nixops"
+              ".local/share/keyrings"
+              ".local/share/direnv"
+            ];
+            files = [
+              ".screenrc"
+            ];
+            allowOther = true;
+          };
+        }
+      '';
     };
 
   };

nixos.nix

@@ -5,7 +5,7 @@ let
     types foldl' unique noDepEntry concatMapStrings listToAttrs
     escapeShellArg escapeShellArgs replaceStrings recursiveUpdate all
     filter filterAttrs concatStringsSep concatMapStringsSep isString
-    catAttrs optional;
+    catAttrs optional literalExpression;
 
   inherit (pkgs.callPackage ./lib.nix { }) splitPath dirListToPath
     concatPaths sanitizeName duplicates;
@@ -219,6 +219,39 @@ in
                       )
                     );
                     default = { };
+                    description = ''
+                      A set of user submodules listing the files and
+                      directories to link to their respective user's
+                      home directories.
+
+                      Each attribute name should be the name of the
+                      user.
+
+                      For detailed usage, check the <link
+                      xlink:href="https://github.com/nix-community/impermanence">documentation</link>.
+                    '';
+                    example = literalExpression ''
+                      {
+                        talyz = {
+                          directories = [
+                            "Downloads"
+                            "Music"
+                            "Pictures"
+                            "Documents"
+                            "Videos"
+                            "VirtualBox VMs"
+                            { directory = ".gnupg"; mode = "0700"; }
+                            { directory = ".ssh"; mode = "0700"; }
+                            { directory = ".nixops"; mode = "0700"; }
+                            { directory = ".local/share/keyrings"; mode = "0700"; }
+                            ".local/share/direnv"
+                          ];
+                          files = [
+                            ".screenrc"
+                          ];
+                        };
+                      }
+                    '';
                   };
 
                   files = mkOption {
@@ -285,13 +318,34 @@ in
           )
         );
       description = ''
-        Persistent storage locations and the files and directories to
+        A set of persistent storage location submodules listing the
-        link to them. Each attribute name should be the full path to a
+        files and directories to link to their respective persistent
-        persistent storage location.
+        storage location.
+
+        Each attribute name should be the full path to a persistent
+        storage location.
 
         For detailed usage, check the <link
         xlink:href="https://github.com/nix-community/impermanence">documentation</link>.
       '';
+      example = literalExpression ''
+        {
+          "/persistent" = {
+            directories = [
+              "/var/log"
+              "/var/lib/bluetooth"
+              "/var/lib/systemd/coredump"
+              "/etc/NetworkManager/system-connections"
+              { directory = "/var/lib/colord"; user = "colord"; group = "colord"; mode = "u=rwx,g=rx,o="; }
+            ];
+            files = [
+              "/etc/machine-id"
+              { file = "/etc/nix/id_rsa"; parentDirectory = { mode = "u=rwx,g=,o="; }; }
+            ];
+          };
+          users.talyz = { ... }; # See the dedicated example
+        }
+      '';
     };
 
   };