From 13b953c8644e7457bf2b429ca14d7367f6eebf85 Mon Sep 17 00:00:00 2001
From: nicoo <nicoo@mur.at>
Date: Thu, 28 Nov 2024 16:27:36 +0000
Subject: [PATCH 1/3] lib.packagesFromDirectoryRecursive: More precise type
 signature

Pulled above the inputs section to avoid duplicating information.
---
 lib/filesystem.nix | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/lib/filesystem.nix b/lib/filesystem.nix
index 5a78bcca4ebd6..2f43792017f92 100644
--- a/lib/filesystem.nix
+++ b/lib/filesystem.nix
@@ -306,6 +306,16 @@ in
         As a result, directories with no `.nix` files (including empty
         directories) will be transformed into empty attribute sets.
 
+    # Type
+
+    ```
+    packagesFromDirectoryRecursive :: {
+      callPackage :: Path -> {} -> a,
+      directory :: Path,
+      ...
+    } -> AttrSet
+    ```
+
     # Inputs
 
     Structured function argument
@@ -317,20 +327,10 @@ in
 
       : `pkgs.callPackage`
 
-        Type: `Path -> AttrSet -> a`
-
       `directory`
 
       : The directory to read package files from
 
-        Type: `Path`
-
-
-    # Type
-
-    ```
-    packagesFromDirectoryRecursive :: AttrSet -> AttrSet
-    ```
 
     # Examples
     :::{.example}

From 781b44b39d1738e544ca0acfe391beda22408c22 Mon Sep 17 00:00:00 2001
From: nicoo <nicoo@mur.at>
Date: Thu, 28 Nov 2024 16:36:29 +0000
Subject: [PATCH 2/3] lib.packagesFromDirectoryRecursive: document inputs
 better

Cut out redundant boilerplate, explain what the `callPackage` parameter is.

Co-authored-by: Valentin Gagarin <valentin@gagarin.work>
---
 lib/filesystem.nix | 16 +++++-----------
 1 file changed, 5 insertions(+), 11 deletions(-)

diff --git a/lib/filesystem.nix b/lib/filesystem.nix
index 2f43792017f92..17ca23606f8be 100644
--- a/lib/filesystem.nix
+++ b/lib/filesystem.nix
@@ -318,18 +318,12 @@ in
 
     # Inputs
 
-    Structured function argument
+    `callPackage`
+    : The function used to convert a Nix file's path into a leaf of the attribute set.
+      It is typically the `callPackage` function, taken from either `pkgs` or a new scope corresponding to the `directory`.
 
-    : Attribute set containing the following attributes.
-      Additional attributes are ignored.
-
-      `callPackage`
-
-      : `pkgs.callPackage`
-
-      `directory`
-
-      : The directory to read package files from
+    `directory`
+    : The directory to read package files from.
 
 
     # Examples

From 25bdcd51e86eaee6d5e2a0d908cdd0caa82b2ccd Mon Sep 17 00:00:00 2001
From: nicoo <nicoo@mur.at>
Date: Thu, 28 Nov 2024 16:55:04 +0000
Subject: [PATCH 3/3] lib.packagesFromDirectoryRecursive: Split and explain
 examples, warn about scope limitation

---
 lib/filesystem.nix | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/lib/filesystem.nix b/lib/filesystem.nix
index 17ca23606f8be..b8ce722dac557 100644
--- a/lib/filesystem.nix
+++ b/lib/filesystem.nix
@@ -328,7 +328,7 @@ in
 
     # Examples
     :::{.example}
-    ## `lib.filesystem.packagesFromDirectoryRecursive` usage example
+    ## Basic use of `lib.packagesFromDirectoryRecursive`
 
     ```nix
     packagesFromDirectoryRecursive {
@@ -336,17 +336,48 @@ in
       directory = ./my-packages;
     }
     => { ... }
+    ```
+
+    In this case, `callPackage` will only search `pkgs` for a file's input parameters.
+    In other words, a file cannot refer to another file in the directory in its input parameters.
+    :::
 
+    ::::{.example}
+    ## Create a scope for the nix files found in a directory
+    ```nix
     lib.makeScope pkgs.newScope (
       self: packagesFromDirectoryRecursive {
-        callPackage = self.callPackage;
+        inherit (self) callPackage;
         directory = ./my-packages;
       }
     )
     => { ... }
     ```
 
+    For example, take the following directory structure:
+    ```
+    my-packages
+    ├── a.nix    → { b }: assert b ? b1; ...
+    └── b
+       ├── b1.nix  → { a }: ...
+       └── b2.nix
+    ```
+
+    Here, `b1.nix` can specify `{ a }` as a parameter, which `callPackage` will resolve as expected.
+    Likewise, `a.nix` receive an attrset corresponding to the contents of the `b` directory.
+
+    :::{.note}
+    `a.nix` cannot directly take as inputs packages defined in a child directory, such as `b1`.
+    :::
+
+    :::{.warning}
+    As of now, `lib.packagesFromDirectoryRecursive` cannot create nested scopes for sub-directories.
+
+    In particular, files under `b/` can only require (as inputs) other files under `my-packages`,
+    but not to those in the same directory, nor those in a parent directory; e.g, `b2.nix` cannot directly
+    require `b1`.
     :::
+    ::::
   */
   packagesFromDirectoryRecursive =
     {