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:
-      pathType :: Path -> String
+    # Inputs
 
-    Example:
+    path
+
+    : The path to query
+
+    # Type
+
+    ```
+    pathType :: Path -> String
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.filesystem.pathType` usage example
+
+    ```nix
     pathType /.
     => "directory"
 
     pathType /some/file.nix
     => "regular"
+    ```
+
+    :::
   */
   pathType =
     builtins.readFileType or
@@ -59,13 +75,27 @@ in
       else (readDir (dirOf path)).${baseNameOf path}
     );
 
-  /*
+  /**
     Whether a path exists and is a directory.
 
-    Type:
-      pathIsDirectory :: Path -> Bool
 
-    Example:
+    # Inputs
+
+    `path`
+
+    : 1\. Function argument
+
+    # Type
+
+    ```
+    pathIsDirectory :: Path -> Bool
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.filesystem.pathIsDirectory` usage example
+
+    ```nix
     pathIsDirectory /.
     => true
 
@@ -74,17 +104,34 @@ in
 
     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
+
+    `path`
+
+    : 1\. Function argument
+
+    # Type
+
+    ```
+    pathIsRegularFile :: Path -> Bool
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.filesystem.pathIsRegularFile` usage example
+
+    ```nix
     pathIsRegularFile /.
     => false
 
@@ -93,19 +140,32 @@ in
 
     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,7 +306,37 @@ in
         As a result, directories with no `.nix` files (including empty
         directories) will be transformed into empty attribute sets.
 
-    Example:
+    # Inputs
+
+    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;
@@ -237,26 +350,13 @@ in
       }
     )
     => { ... }
+    ```
 
-    Type:
-      packagesFromDirectoryRecursive :: AttrSet -> AttrSet
+    :::
   */
   packagesFromDirectoryRecursive =
-    # Options.
     {
-      /*
-        `pkgs.callPackage`
-
-        Type:
-          Path -> AttrSet -> a
-      */
       callPackage,
-      /*
-        The directory to read package files from
-
-        Type:
-          Path
-      */
       directory,
       ...
     }: