doc: migrate lib.filesystem to doc-comment format (#312222)

* doc: migrate lib.filesystem to doc-comment format

* defintion list fixes lib/filesystem.nix

Co-authored-by: Daniel Sidhion <DanielSidhion@users.noreply.github.com>

---------

Co-authored-by: Daniel Sidhion <DanielSidhion@users.noreply.github.com>

lib/filesystem.nix

@@ -1,4 +1,4 @@
-/*
+/**
   Functions for querying information about the filesystem
   without copying any files to the Nix store.
 */
@@ -29,19 +29,35 @@ in
 
 {
 
-  /*
+  /**
     The type of a path. The path needs to exist and be accessible.
     The result is either "directory" for a directory, "regular" for a regular file, "symlink" for a symlink, or "unknown" for anything else.
 
-    Type:
+    # Inputs
-      pathType :: Path -> String
 
-    Example:
+    path
-      pathType /.
-      => "directory"
 
-      pathType /some/file.nix
+    : The path to query
-      => "regular"
+
+    # Type
+
+    ```
+    pathType :: Path -> String
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.filesystem.pathType` usage example
+
+    ```nix
+    pathType /.
+    => "directory"
+
+    pathType /some/file.nix
+    => "regular"
+    ```
+
+    :::
   */
   pathType =
     builtins.readFileType or
@@ -59,53 +75,97 @@ in
       else (readDir (dirOf path)).${baseNameOf path}
     );
 
-  /*
+  /**
     Whether a path exists and is a directory.
 
-    Type:
-      pathIsDirectory :: Path -> Bool
 
-    Example:
+    # Inputs
-      pathIsDirectory /.
-      => true
 
-      pathIsDirectory /this/does/not/exist
+    `path`
-      => false
 
-      pathIsDirectory /some/file.nix
+    : 1\. Function argument
-      => false
+
+    # Type
+
+    ```
+    pathIsDirectory :: Path -> Bool
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.filesystem.pathIsDirectory` usage example
+
+    ```nix
+    pathIsDirectory /.
+    => true
+
+    pathIsDirectory /this/does/not/exist
+    => false
+
+    pathIsDirectory /some/file.nix
+    => false
+    ```
+
+    :::
   */
   pathIsDirectory = path:
     pathExists path && pathType path == "directory";
 
-  /*
+  /**
     Whether a path exists and is a regular file, meaning not a symlink or any other special file type.
 
-    Type:
-      pathIsRegularFile :: Path -> Bool
 
-    Example:
+    # Inputs
-      pathIsRegularFile /.
-      => false
 
-      pathIsRegularFile /this/does/not/exist
+    `path`
-      => false
 
-      pathIsRegularFile /some/file.nix
+    : 1\. Function argument
-      => true
+
+    # Type
+
+    ```
+    pathIsRegularFile :: Path -> Bool
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.filesystem.pathIsRegularFile` usage example
+
+    ```nix
+    pathIsRegularFile /.
+    => false
+
+    pathIsRegularFile /this/does/not/exist
+    => false
+
+    pathIsRegularFile /some/file.nix
+    => true
+    ```
+
+    :::
   */
   pathIsRegularFile = path:
     pathExists path && pathType path == "regular";
 
-  /*
+  /**
     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
+
+    # Inputs
+
+    `root`
+
+    : The directory within to search
+
+    # Type
+
+    ```
+    Path -> Map String Path
+    ```
   */
   haskellPathsInDir =
-    # The directory within to search
     root:
     let # Files in the root
         root-files = builtins.attrNames (builtins.readDir root);
@@ -120,17 +180,30 @@ in
             builtins.pathExists (value + "/${name}.cabal")
           ) root-files-with-paths;
     in builtins.listToAttrs cabal-subdirs;
-  /*
+  /**
     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 ]; }
+
+    # Inputs
+
+    `pattern`
+
+    : The pattern to search for
+
+    `file`
+
+    : The file to start searching upward from
+
+    # 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);
@@ -150,13 +223,23 @@ in
     in go (if isDir then file else parent);
 
 
-  /*
+  /**
     Given a directory, return a flattened list of all files within it recursively.
 
-    Type: Path -> [ Path ]
+
+    # Inputs
+
+    `dir`
+
+    : The path to recursively list
+
+    # Type
+
+    ```
+    Path -> [ Path ]
+    ```
   */
   listFilesRecursive =
-    # The path to recursively list
     dir:
     lib.flatten (lib.mapAttrsToList (name: type:
     if type == "directory" then
@@ -165,7 +248,7 @@ in
       dir + "/${name}"
   ) (builtins.readDir dir));
 
-  /*
+  /**
     Transform a directory tree containing package files suitable for
     `callPackage` into a matching nested attribute set of derivations.
 
@@ -223,40 +306,57 @@ in
         As a result, directories with no `.nix` files (including empty
         directories) will be transformed into empty attribute sets.
 
-    Example:
+    # Inputs
-      packagesFromDirectoryRecursive {
+
-        inherit (pkgs) callPackage;
+    Structured function argument
+
+    : Attribute set containing the following attributes.
+      Additional attributes are ignored.
+
+      `callPackage`
+
+      : `pkgs.callPackage`
+
+        Type: `Path -> AttrSet -> a`
+
+      `directory`
+
+      : The directory to read package files from
+
+        Type: `Path`
+
+
+    # Type
+
+    ```
+    packagesFromDirectoryRecursive :: AttrSet -> AttrSet
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.filesystem.packagesFromDirectoryRecursive` usage example
+
+    ```nix
+    packagesFromDirectoryRecursive {
+      inherit (pkgs) callPackage;
+      directory = ./my-packages;
+    }
+    => { ... }
+
+    lib.makeScope pkgs.newScope (
+      self: packagesFromDirectoryRecursive {
+        callPackage = self.callPackage;
         directory = ./my-packages;
       }
-      => { ... }
+    )
+    => { ... }
+    ```
 
-      lib.makeScope pkgs.newScope (
+    :::
-        self: packagesFromDirectoryRecursive {
-          callPackage = self.callPackage;
-          directory = ./my-packages;
-        }
-      )
-      => { ... }
-
-    Type:
-      packagesFromDirectoryRecursive :: AttrSet -> AttrSet
   */
   packagesFromDirectoryRecursive =
-    # Options.
     {
-      /*
-        `pkgs.callPackage`
-
-        Type:
-          Path -> AttrSet -> a
-      */
       callPackage,
-      /*
-        The directory to read package files from
-
-        Type:
-          Path
-      */
       directory,
       ...
     }: