From 9bfc4bbd63433c44aba71b01c54fa3c5130fcb0f Mon Sep 17 00:00:00 2001
From: Silvan Mosberger <contact@infinisil.com>
Date: Wed, 26 Oct 2022 15:10:47 +0200
Subject: [PATCH] lib: Automatically generate lib.filesytem docs

---
 doc/doc-support/lib-function-docs.nix |  1 +
 doc/functions/library.xml             |  2 +
 lib/filesystem.nix                    | 58 ++++++++++++++++++---------
 3 files changed, 43 insertions(+), 18 deletions(-)

diff --git a/doc/doc-support/lib-function-docs.nix b/doc/doc-support/lib-function-docs.nix
index f6d613cac0b6..cbcbed4310af 100644
--- a/doc/doc-support/lib-function-docs.nix
+++ b/doc/doc-support/lib-function-docs.nix
@@ -22,6 +22,7 @@ with pkgs; stdenv.mkDerivation {
     docgen lists 'List manipulation functions'
     docgen debug 'Debugging functions'
     docgen options 'NixOS / nixpkgs option handling'
+    docgen filesystem 'Filesystem functions'
     docgen sources 'Source filtering functions'
   '';
 }
diff --git a/doc/functions/library.xml b/doc/functions/library.xml
index 21bcf5b88c9d..b291356c14b8 100644
--- a/doc/functions/library.xml
+++ b/doc/functions/library.xml
@@ -26,5 +26,7 @@
 
  <xi:include href="./library/generated/options.xml" />
 
+ <xi:include href="./library/generated/filesystem.xml" />
+
  <xi:include href="./library/generated/sources.xml" />
 </section>
diff --git a/lib/filesystem.nix b/lib/filesystem.nix
index 0a1275e547cf..948196055203 100644
--- a/lib/filesystem.nix
+++ b/lib/filesystem.nix
@@ -1,9 +1,23 @@
+# Functions for copying sources to the Nix store.
 { lib }:
-{ # haskellPathsInDir : Path -> Map String Path
-  # A map of all haskell packages defined in the given path,
-  # identified by having a cabal file with the same name as the
-  # directory itself.
-  haskellPathsInDir = root:
+
+let
+  inherit (lib.strings)
+    hasPrefix
+    ;
+in
+
+{
+  /*
+    A map of all haskell packages defined in the given path,
+    identified by having a cabal file with the same name as the
+    directory itself.
+
+    Type: Path -> Map String Path
+  */
+  haskellPathsInDir =
+    # The directory within to search
+    root:
     let # Files in the root
         root-files = builtins.attrNames (builtins.readDir root);
         # Files with their full paths
@@ -17,15 +31,18 @@
             builtins.pathExists (value + "/${name}.cabal")
           ) root-files-with-paths;
     in builtins.listToAttrs cabal-subdirs;
-  # locateDominatingFile :  RegExp
-  #                      -> Path
-  #                      -> Nullable { path : Path;
-  #                                    matches : [ MatchResults ];
-  #                                  }
-  # Find the first directory containing a file matching 'pattern'
-  # upward from a given 'file'.
-  # Returns 'null' if no directories contain a file matching 'pattern'.
-  locateDominatingFile = pattern: file:
+  /*
+    Find the first directory containing a file matching 'pattern'
+    upward from a given 'file'.
+    Returns 'null' if no directories contain a file matching 'pattern'.
+
+    Type: RegExp -> Path -> Nullable { path : Path; matches : [ MatchResults ]; }
+  */
+  locateDominatingFile =
+    # The pattern to search for
+    pattern:
+    # The file to start searching upward from
+    file:
     let go = path:
           let files = builtins.attrNames (builtins.readDir path);
               matches = builtins.filter (match: match != null)
@@ -44,10 +61,15 @@
     in go (if isDir then file else parent);
 
 
-  # listFilesRecursive: Path -> [ Path ]
-  #
-  # Given a directory, return a flattened list of all files within it recursively.
-  listFilesRecursive = dir: lib.flatten (lib.mapAttrsToList (name: type:
+  /*
+    Given a directory, return a flattened list of all files within it recursively.
+
+    Type: Path -> [ Path ]
+  */
+  listFilesRecursive =
+    # The path to recursively list
+    dir:
+    lib.flatten (lib.mapAttrsToList (name: type:
     if type == "directory" then
       lib.filesystem.listFilesRecursive (dir + "/${name}")
     else