lib.packagesFromDirectoryRecursive: Improved documentation (#359898)

lib/filesystem.nix

@@ -306,53 +306,78 @@ in
         As a result, directories with no `.nix` files (including empty
         directories) will be transformed into empty attribute sets.
 
-    # Inputs
-
-    Structured function argument
-
-    : Attribute set containing the following attributes.
-      Additional attributes are ignored.
-
-      `callPackage`
-
-      : `pkgs.callPackage`
-
-        Type: `Path -> AttrSet -> a`
+    # Type
 
-      `directory`
+    ```
+    packagesFromDirectoryRecursive :: {
+      callPackage :: Path -> {} -> a,
+      directory :: Path,
+      ...
+    } -> AttrSet
+    ```
 
-      : The directory to read package files from
+    # Inputs
 
-        Type: `Path`
+    `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`.
 
+    `directory`
+    : The directory to read package files from.
 
-    # Type
-
-    ```
-    packagesFromDirectoryRecursive :: AttrSet -> AttrSet
-    ```
 
     # Examples
     :::{.example}
-    ## `lib.filesystem.packagesFromDirectoryRecursive` usage example
+    ## Basic use of `lib.packagesFromDirectoryRecursive`
 
     ```nix
     packagesFromDirectoryRecursive {
       inherit (pkgs) callPackage;
       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 =
     {