Add module docs for writers

modules/flake-parts/writers.nix

@@ -1,5 +1,5 @@
-{
-  perSystem = {
+{ flake-parts-lib, ... }: {
+  options.perSystem = flake-parts-lib.mkPerSystemOption ({
     config,
     lib,
     pkgs,
@@ -9,10 +9,25 @@
   in {
     options.writers = {
       writePureShellScript = lib.mkOption {
-        type = lib.types.functionTo lib.types.anything;
+        type = lib.types.functionTo (lib.types.functionTo lib.types.package);
+        description = ''
+          Create a script that runs in a `pure` environment, in the sense that:
+            - `PATH` only contains exactly the packages passed via the `PATH` arg
+            - `NIX_PATH` is set to the path of the current `pkgs`
+            - `TMPDIR` is set up and cleaned up even if the script fails
+            - out, if set, is kept as-is
+            - all environment variables are unset, except:
+            - the ones listed in `keepVars` below
+            - ones listed via the `KEEP_VARS` variable
+            - the behavior is similar to `nix-shell --pure`
+        '';
       };
       writePureShellScriptBin = lib.mkOption {
-        type = lib.types.functionTo lib.types.anything;
+        type = lib.types.functionTo (lib.types.functionTo (lib.types.functionTo lib.types.package));
+        description = ''
+          Creates a script in a `bin/` directory in the output; suitable for use with `lib.makeBinPath`, etc.
+          See {option}`writers.writePureShellScript`
+        '';
       };
     };
 
@@ -23,5 +38,5 @@
         writePureShellScriptBin
         ;
     };
-  };
+  });
 }

pkgs/writers/default.nix

@@ -8,20 +8,11 @@
   writeScriptBin,
   ...
 }: let
-  /*
-  create a script that runs in a `pure` environment, in the sense that:
-  - PATH only contains exactly the packages passed via the PATH arg
-  - NIX_PATH is set to the path of the current `pkgs`
-  - TMPDIR is set up and cleaned up even if the script fails
-  - out, if set, is kept as-is
-  - all environment variables are unset, except:
-  - the ones listed in `keepVars` below
-  - ones listed via the KEEP_VARS variable
-  - the behavior is similar to `nix-shell --pure`
-  */
+  # Docs at modules/flake-parts/writers.nix
   writePureShellScript = PATH: script:
     writeScript "script.sh" (mkScript PATH script);
 
+  # Docs at modules/flake-parts/writers.nix
   writePureShellScriptBin = binName: PATH: script:
     writeScriptBin binName (mkScript PATH script);