docs(lib): documment like rfc 0145

parts/lib/builders.nix

@@ -11,14 +11,35 @@ let
   inherit (lib.attrsets) recursiveUpdate optionalAttrs listToAttrs;
   inherit (lib.modules) mkDefault evalModules;
 
-  # mkSystem is a function that uses withSystem to give us inputs' and self'
-  # it also assumes the the system type either nixos or darwin and uses the appropriate
+  /**
+    mkSystem is a function that uses withSystem to give us inputs' and self'
+    it also assumes the the system type either nixos or darwin and uses the appropriate
+
+    # Type
+
+    ```
+    mkSystem :: AttrSet -> AttrSet
+    ```
+
+    # Example
+
+    ```nix
+      mkSystem {
+        host = "myhost";
+        arch = "x86_64";
+        target = "nixos";
+        modules = [ ./module.nix ];
+        specialArgs = { foo = "bar"; };
+      }
+    ```
+  */
   mkSystem =
     {
       host,
       arch ? "x86_64",
       target ? "nixos",
-      modules,
+      modules ? [ ],
+      specialArgs ? { },
       ...
     }@args:
     let
@@ -41,7 +62,7 @@ let
             inherit lib;
             inherit self self';
             inherit inputs inputs';
-          } (args.specialArgs or { });
+          } args.specialArgs;
 
           # A nominal type for modules. When set and non-null, this adds a check to
           # make sure that only compatible modules are imported.
@@ -105,7 +126,7 @@ let
               };
             }))
 
-            (args.modules or [ ])
+            args.modules
           ];
         };
       in
@@ -115,7 +136,29 @@ let
       eval // optionalAttrs (target == "darwin") { system = eval.config.system.build.toplevel; }
     );
 
-  # mkSystems is a wrapper for mkNixSystem to create a list of systems
+  /**
+    mkSystems is a wrapper for mkNixSystem to create a list of systems
+
+    # Type
+
+    ```
+    mkSystems :: List -> AttrSet
+    ```
+
+    # Example
+
+    ```nix
+      mkSystems [
+        {
+          host = "myhost";
+          arch = "x86_64";
+          target = "nixos";
+          modules = [ ./module.nix ];
+          specialArgs = { foo = "bar"; };
+        }
+      ]
+    ```
+  */
   mkSystems =
     systems:
     listToAttrs (

parts/lib/default.nix

@@ -17,7 +17,7 @@ let
       helpers = import ./helpers.nix { inherit lib; };
       secrets = import ./secrets.nix { inherit inputs; };
       services = import ./services.nix { inherit lib; };
-      validators = import ./validators.nix { inherit lib; };
+      validators = import ./validators.nix;
 
       # we have to rexport the functions we want to use, but don't want to refer to the whole lib
       # "path". e.g. lib.hardware.isx86Linux can be shortened to lib.isx86Linux
@@ -38,7 +38,6 @@ let
       inherit (self.services) mkGraphicalService mkHyprlandService mkServiceOption;
       inherit (self.validators)
         ifTheyExist
-        ifGroupsExist
         isAcceptedDevice
         isWayland
         ifOneEnabled

parts/lib/hardware.nix

@@ -1,11 +1,48 @@
 let
-  # check if the host platform is linux and x86
-  # (isx86Linux pkgs) -> true
+  /**
+    check if the host platform is linux and x86
+
+    # Arguments
+
+    - [pkgs] the package set
+
+    # Type
+
+    ```
+    isx86Linux :: AttrSet -> Bool
+    ```
+
+    # Example
+
+    ```nix
+    isx86Linux pkgs
+    => true
+    ```
+  */
   isx86Linux = pkgs: pkgs.stdenv.hostPlatform.isLinux && pkgs.stdenv.hostPlatform.isx86;
 
-  # ldTernary, short for linux darwin ternary, is a ternary operator that takes 3 arguments
-  # the pkgs used to determine the standard environment, l: the linux result, d: the darwin result
-  # https://github.com/nekowinston/dotfiles/blob/36f7f4a86af4d1ecd3d2da483585e4d2503a978a/machines/lib.nix#L32
+  /**
+    ldTernary, short for linux darwin ternary
+
+    # Inputs
+
+    - [pkgs] is the package set
+    - [l] the value to return if the host platform is linux
+    - [d] the value to return if the host platform is darwin
+
+    # Type
+
+    ```
+    ldTernary :: AttrSet -> Any -> Any -> Any
+    ```
+
+    # Example
+
+    ```nix
+    ldTernary pkgs "linux" "darwin"
+    => "linux"
+    ```
+  */
   ldTernary =
     pkgs: l: d:
     if pkgs.stdenv.hostPlatform.isLinux then
@@ -15,9 +52,27 @@ let
     else
       throw "Unsupported system: ${pkgs.stdenv.system}";
 
-  # assume the first monitor in the list of monitors is primary
-  # get its name from the list of monitors
-  # `primaryMonitor osConfig` -> "DP-1"
+  /**
+    assume the first monitor in the list of monitors is primary
+    get its name from the list of monitors
+
+    # Arguments
+
+    - [config] the configuration that nixosConfigurations provides
+
+    # Type
+
+    ```
+    primaryMonitor :: AttrSet -> String
+    ```
+
+    # Example
+
+    ```nix
+    primaryMonitor osConfig
+    => "DP-1"
+    ```
+  */
   primaryMonitor = config: builtins.elemAt config.garden.device.monitors 0;
 in
 {

parts/lib/helpers.nix

@@ -5,26 +5,143 @@ let
   inherit (lib.filesystem) listFilesRecursive;
   inherit (lib.strings) hasSuffix;
 
-  # filter files for the .nix suffix
+  /**
+    filter files for the .nix suffix
+
+    # Arguments
+
+    - [k] they key, which is the file name
+    - [v] the value, which is the type of the file
+
+    # Type
+
+    ```
+    filterNixFiles :: String -> String -> Bool
+    ```
+
+    # Example
+
+    ```nix
+    filterNixFiles "default.nix" "regular"
+    => true
+    ```
+  */
   filterNixFiles = k: v: v == "regular" && hasSuffix ".nix" k;
 
-  # import files that are selected by filterNixFiles
+  /**
+    Import all file that filterNixFiles allows for
+
+    # Arguments
+
+    - [path] the path to the directory
+
+    # Type
+
+    ```
+    importNixFiles :: String -> List
+    ```
+
+    # Example
+
+    ```nix
+    importNixFiles ./.
+    => [ {...} ]
+    ```
+  */
   importNixFiles =
     path:
     (forEach (
       mapAttrsToList (name: _: path + ("/" + name)) (filterAttrs filterNixFiles (builtins.readDir path))
     ))
       import;
 
-  # import all nix files and directories
+  /**
+    import all nix files and directories
+
+    # Arguments
+
+    - [dir] the directory to search for nix files
+
+    # Type
+
+    ```
+    importNixFilesAndDirs :: String -> List
+    ```
+
+    # Example
+
+    ```nix
+    importNixFilesAndDirs ./.
+    => [ "flake.nix" ]
+    ```
+  */
   importNixFilesAndDirs = dir: filter (f: f != "default.nix") (listFilesRecursive dir);
 
-  # return an int based on boolean value
+  /**
+    return an int based on boolean value
+
+    # Arguments
+
+    - [bool] the boolean value
+
+    # Type
+
+    ```
+    boolToNum :: Bool -> Int
+    ```
+
+    # Example
+
+    ```nix
+    boolToNum true
+    => 1
+    ```
+  */
   boolToNum = bool: if bool then 1 else 0;
 
-  # convert a list of integers to a list of string
-  # `intListToStringList [1 2 3]` -> ["1" "2" "3"]
+  /**
+    convert a list of integers to a list of string
+
+    # Arguments
+
+    - [list] the list of integers
+
+    # Type
+
+    ```
+    intListToStringList :: List -> List
+    ```
+
+    # Example
+
+    ```nix
+    intListToStringList [1 2 3]
+    => ["1" "2" "3"]
+    ```
+  */
   intListToStringList = list: map (toString list);
+
+  /**
+    a function that returns the index of an element in a list
+
+    # Arguments
+
+    - [list] the list to search in
+    - [elem] the element to search for
+
+    # Type
+
+    ```
+    indexOf :: List -> Any -> Int
+    ```
+
+    # Example
+
+    ```nix
+    indexOf [1 2 3] 2
+    => 1
+    ```
+  */
   indexOf =
     list: elem:
     let
@@ -39,10 +156,56 @@ let
     in
     f f 0;
 
-  # a function that checks if a list contains a list of given strings
+  /**
+    a function that checks if a list contains a list of given strings
+
+    # Arguments
+
+    - [list] the list to search in
+    - [targetStrings] the list of strings to search for
+
+    # Type
+
+    ```
+    containsStrings :: List -> List -> Bool
+    ```
+
+    # Example
+
+    ```nix
+    containsStrings ["a" "b" "c"] ["a" "b"]
+    => true
+    ```
+  */
   containsStrings =
-    { list, targetStrings }: builtins.all (s: builtins.any (x: x == s) list) targetStrings;
+    list: targetStrings: builtins.all (s: builtins.any (x: x == s) list) targetStrings;
+
+  /**
+    Create git url aliases for a given domain
+
+    # Arguments
+
+    - [domain] the domain to create the alias for
+    - [alias] the alias to use
+    - [user] the user to use, this defaults to "git"
+    - [port] the port to use, this is optional
+
+    # Type
+
+    ```
+    giturl :: (String -> String -> String -> Int) -> AttrSet
+    ```
+
+    # Example
 
+    ```nix
+    giturl { domain = "github.com", alias = "gh"; }
+    => {
+      "https://github.com/".insteadOf = "gh:";
+      "ssh://[email protected]/".pushInsteadOf = "gh:";
+    }
+    ```
+  */
   giturl =
     {
       domain,