Merge pull request #312217 from hsjobeki/doc/lib-derivations

doc: migrate lib.derivations to doc-comment format

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.
@@ -62,25 +62,36 @@ in
 
         (lazyDerivation { inherit derivation }).pythonPath
 
+    # Inputs
+
+    Takes an attribute set with the following attributes
+
+    `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 extra values to add to the returned attrset.
+
+      This can be used for adding package attributes, such as `tests`.
+
+    `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,
-      derivation
+      meta ? null,
-    , # Optional meta attribute.
+      passthru ? { },
-      #
-      # 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.
       outputs ? [ "out" ]
     }:
     let
@@ -149,16 +160,36 @@ 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.
 
-     Type: optionalDrvAttr :: Bool -> a -> a | Null
 
-     Example:
+    # 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;
@@ -168,10 +199,11 @@ in
       x = 1;
     }).drvPath
     => true
+    ```
+
+    :::
   */
   optionalDrvAttr =
-    # Condition
     cond:
-    # Attribute value
     value: if cond then value else null;
 }