treewide: migrate doc comments

lib/default.nix

@@ -1,8 +1,9 @@
-/* Library of low-level helper functions for nix expressions.
- *
- * Please implement (mostly) exhaustive unit tests
- * for new functions in `./tests.nix`.
- */
+/**
+  Library of low-level helper functions for nix expressions.
+  *
+  * Please implement (mostly) exhaustive unit tests
+  * for new functions in `./tests.nix`.
+*/
 let
 
   inherit (import ./fixed-points.nix { inherit lib; }) makeExtensible;

lib/derivations.nix

@@ -17,7 +17,7 @@ let
     else "";
 in
 {
-  /*
+  /**
     Restrict a derivation to a predictable set of attribute names, so
     that the returned attrset is not strict in the actual derivation,
     saving a lot of computation when the derivation is non-trivial.
@@ -61,7 +61,6 @@ in
         (lazyDerivation { inherit derivation }).passthru
 
         (lazyDerivation { inherit derivation }).pythonPath
-
   */
   lazyDerivation =
     args@{
@@ -149,25 +148,48 @@ in
     // genAttrs outputs (outputName: checked.${outputName})
     // passthru;
 
-  /* Conditionally set a derivation attribute.
-
-     Because `mkDerivation` sets `__ignoreNulls = true`, a derivation
-     attribute set to `null` will not impact the derivation output hash.
-     Thus, this function passes through its `value` argument if the `cond`
-     is `true`, but returns `null` if not.
-
-     Type: optionalDrvAttr :: Bool -> a -> a | Null
-
-     Example:
-       (stdenv.mkDerivation {
-         name = "foo";
-         x = optionalDrvAttr true 1;
-         y = optionalDrvAttr false 1;
-       }).drvPath == (stdenv.mkDerivation {
-         name = "foo";
-         x = 1;
-       }).drvPath
-       => true
+  /**
+    Conditionally set a derivation attribute.
+
+    Because `mkDerivation` sets `__ignoreNulls = true`, a derivation
+    attribute set to `null` will not impact the derivation output hash.
+    Thus, this function passes through its `value` argument if the `cond`
+    is `true`, but returns `null` if not.
+
+
+    # Inputs
+
+    `cond`
+
+    : Condition
+
+    `value`
+
+    : Attribute value
+
+    # Type
+
+    ```
+    optionalDrvAttr :: Bool -> a -> a | Null
+    ```
+
+    # Examples
+    :::{.example}
+    ## `optionalDrvAttr` usage example
+
+    ```nix
+    (stdenv.mkDerivation {
+      name = "foo";
+      x = optionalDrvAttr true 1;
+      y = optionalDrvAttr false 1;
+    }).drvPath == (stdenv.mkDerivation {
+      name = "foo";
+      x = 1;
+    }).drvPath
+    => true
+    ```
+
+    :::
   */
   optionalDrvAttr =
     # Condition

lib/fileset/internal.nix

@@ -260,7 +260,7 @@ rec {
       mapAttrs (name: value: null) (readDir path)
       // value;
 
-  /*
+  /**
     A normalisation of a filesetTree suitable filtering with `builtins.path`:
     - Replace all directories that have no files with `null`.
       This removes directories that would be empty
@@ -269,7 +269,22 @@ rec {
 
     Note that this function is strict, it evaluates the entire tree
 
-    Type: Path -> filesetTree -> filesetTree
+
+    # Inputs
+
+    `path`
+
+    : 1\. Function argument
+
+    `tree`
+
+    : 2\. Function argument
+
+    # Type
+
+    ```
+    Path -> filesetTree -> filesetTree
+    ```
   */
   _normaliseTreeFilter = path: tree:
     if tree == "directory" || isAttrs tree then
@@ -290,7 +305,7 @@ rec {
     else
       tree;
 
-  /*
+  /**
     A minimal normalisation of a filesetTree, intended for pretty-printing:
     - If all children of a path are recursively included or empty directories, the path itself is also recursively included
     - If all children of a path are fully excluded or empty directories, the path itself is an empty directory
@@ -299,7 +314,22 @@ rec {
 
     Note that this function is partially lazy.
 
-    Type: Path -> filesetTree -> filesetTree (with "emptyDir"'s)
+
+    # Inputs
+
+    `path`
+
+    : 1\. Function argument
+
+    `tree`
+
+    : 2\. Function argument
+
+    # Type
+
+    ```
+    Path -> filesetTree -> filesetTree (with "emptyDir"'s)
+    ```
   */
   _normaliseTreeMinimal = path: tree:
     if tree == "directory" || isAttrs tree then