From 1a3afdf8526d7c30a64900d2041ebc5d1276488c Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Thu, 16 May 2024 16:08:57 +0200
Subject: [PATCH] doc: migrate lib.derivations to doc-comment format

---
 lib/derivations.nix | 102 +++++++++++++++++++++++++++++---------------
 1 file changed, 67 insertions(+), 35 deletions(-)

diff --git a/lib/derivations.nix b/lib/derivations.nix
index 6867458f9e87..79e896e012c3 100644
--- a/lib/derivations.nix
+++ b/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,26 +61,37 @@ in
         (lazyDerivation { inherit derivation }).passthru
 
         (lazyDerivation { inherit derivation }).pythonPath
+    # Inputs
 
+    structured function argument
+
+    : derivation
+      : The derivation to be wrapped.
+
+    : meta
+      : Optional meta attribute.
+
+        While this function is primarily about derivations, it can improve
+        the `meta` package attribute, which is usually specified through
+        `mkDerivation`.
+
+    : passthru
+      : Optional list of assumed outputs. Default: ["out"]
+
+        This must match the set of outputs that the returned derivation has.
+        You must use this when the derivation has multiple outputs.
+
+    : outputs
+      : Optional list of assumed outputs. Default: ["out"]
+
+        This must match the set of outputs that the returned derivation has.
+        You must use this when the derivation has multiple outputs.
   */
   lazyDerivation =
     args@{
-      # The derivation to be wrapped.
-      derivation
-    , # Optional meta attribute.
-      #
-      # While this function is primarily about derivations, it can improve
-      # the `meta` package attribute, which is usually specified through
-      # `mkDerivation`.
-      meta ? null
-    , # Optional extra values to add to the returned attrset.
-      #
-      # This can be used for adding package attributes, such as `tests`.
-      passthru ? { }
-    , # Optional list of assumed outputs. Default: ["out"]
-      #
-      # This must match the set of outputs that the returned derivation has.
-      # You must use this when the derivation has multiple outputs.
+      derivation,
+      meta ? null,
+      passthru ? { },
       outputs ? [ "out" ]
     }:
     let
@@ -149,29 +160,50 @@ in
     // genAttrs outputs (outputName: checked.${outputName})
     // passthru;
 
-  /* Conditionally set a derivation attribute.
+  /**
+    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.
+    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
+    # Inputs
+
+    `cond`
+
+    : Condition
+
+    `value`
+
+    : Attribute value
+
+    # Type
+
+    ```
+    optionalDrvAttr :: Bool -> a -> a | Null
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.derivations.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
     cond:
-    # Attribute value
     value: if cond then value else null;
 }