doc: migrate lib.customisation to use doc-comments

lib/customisation.nix

@@ -15,7 +15,8 @@ in
 rec {
 
 
-  /* `overrideDerivation drv f` takes a derivation (i.e., the result
+  /**
+    `overrideDerivation drv f` takes a derivation (i.e., the result
     of a call to the builtin function `derivation`) and returns a new
     derivation in which the attributes of the original are overridden
     according to the function `f`.  The function `f` is called with
@@ -39,7 +40,28 @@ rec {
     You should in general prefer `drv.overrideAttrs` over this function;
     see the nixpkgs manual for more information on overriding.
 
-     Example:
+
+    # Inputs
+
+    `drv`
+
+    : 1\. Function argument
+
+    `f`
+
+    : 2\. Function argument
+
+    # Type
+
+    ```
+    overrideDerivation :: Derivation -> ( Derivation -> AttrSet ) -> Derivation
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.customisation.overrideDerivation` usage example
+
+    ```nix
     mySed = overrideDerivation pkgs.gnused (oldAttrs: {
       name = "sed-4.2.2-pre";
       src = fetchurl {
@@ -48,9 +70,9 @@ rec {
       };
       patches = [];
     });
+    ```
 
-     Type:
+    :::
-       overrideDerivation :: Derivation -> ( Derivation -> AttrSet ) -> Derivation
   */
   overrideDerivation = drv: f:
     let
@@ -67,14 +89,32 @@ rec {
       });
 
 
-  /* `makeOverridable` takes a function from attribute set to attribute set and
+  /**
+    `makeOverridable` takes a function from attribute set to attribute set and
     injects `override` attribute which can be used to override arguments of
     the function.
 
     Please refer to  documentation on [`<pkg>.overrideDerivation`](#sec-pkg-overrideDerivation) to learn about `overrideDerivation` and caveats
     related to its use.
 
-     Example:
+
+    # Inputs
+
+    `f`
+
+    : 1\. Function argument
+
+    # Type
+
+    ```
+    makeOverridable :: (AttrSet -> a) -> AttrSet -> a
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.customisation.makeOverridable` usage example
+
+    ```nix
     nix-repl> x = {a, b}: { result = a + b; }
 
     nix-repl> y = lib.makeOverridable x { a = 1; b = 2; }
@@ -84,9 +124,9 @@ rec {
 
     nix-repl> y.override { a = 10; }
     { override = «lambda»; overrideDerivation = «lambda»; result = 12; }
+    ```
 
-     Type:
+    :::
-       makeOverridable :: (AttrSet -> a) -> AttrSet -> a
   */
   makeOverridable = f:
     let
@@ -120,7 +160,8 @@ rec {
       else result);
 
 
-  /* Call the package function in the file `fn` with the required
+  /**
+    Call the package function in the file `fn` with the required
     arguments automatically.  The function is called with the
     arguments `args`, but any missing arguments are obtained from
     `autoArgs`.  This function is intended to be partially
@@ -147,8 +188,26 @@ rec {
 
     <!-- TODO: Apply "Example:" tag to the examples above -->
 
-    Type:
+
+    # Inputs
+
+    `autoArgs`
+
+    : 1\. Function argument
+
+    `fn`
+
+    : 2\. Function argument
+
+    `args`
+
+    : 3\. Function argument
+
+    # Type
+
+    ```
     callPackageWith :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a
+    ```
   */
   callPackageWith = autoArgs: fn: args:
     let
@@ -210,12 +269,31 @@ rec {
        else abort "lib.customisation.callPackageWith: ${error}";
 
 
-  /* Like callPackage, but for a function that returns an attribute
+  /**
+    Like callPackage, but for a function that returns an attribute
     set of derivations. The override function is added to the
     individual attributes.
 
-     Type:
+
+    # Inputs
+
+    `autoArgs`
+
+    : 1\. Function argument
+
+    `fn`
+
+    : 2\. Function argument
+
+    `args`
+
+    : 3\. Function argument
+
+    # Type
+
+    ```
     callPackagesWith :: AttrSet -> ((AttrSet -> AttrSet) | Path) -> AttrSet -> AttrSet
+    ```
   */
   callPackagesWith = autoArgs: fn: args:
     let
@@ -233,11 +311,30 @@ rec {
       else mapAttrs mkAttrOverridable pkgs;
 
 
-  /* Add attributes to each output of a derivation without changing
+  /**
+    Add attributes to each output of a derivation without changing
     the derivation itself and check a given condition when evaluating.
 
-     Type:
+
+    # Inputs
+
+    `condition`
+
+    : 1\. Function argument
+
+    `passthru`
+
+    : 2\. Function argument
+
+    `drv`
+
+    : 3\. Function argument
+
+    # Type
+
+    ```
     extendDerivation :: Bool -> Any -> Derivation -> Derivation
+    ```
   */
   extendDerivation = condition: passthru: drv:
     let
@@ -269,13 +366,24 @@ rec {
       outPath = assert condition; drv.outPath;
     };
 
-  /* Strip a derivation of all non-essential attributes, returning
+  /**
+    Strip a derivation of all non-essential attributes, returning
     only those needed by hydra-eval-jobs. Also strictly evaluate the
     result to ensure that there are no thunks kept alive to prevent
     garbage collection.
 
-     Type:
+
+    # Inputs
+
+    `drv`
+
+    : 1\. Function argument
+
+    # Type
+
+    ```
     hydraJob :: (Derivation | Null) -> (Derivation | Null)
+    ```
   */
   hydraJob = drv:
     let
@@ -443,17 +551,49 @@ rec {
         };
     in self;
 
-  /* backward compatibility with old uncurried form; deprecated */
+  /**
+    backward compatibility with old uncurried form; deprecated
+
+
+    # Inputs
+
+    `splicePackages`
+
+    : 1\. Function argument
+
+    `newScope`
+
+    : 2\. Function argument
+
+    `otherSplices`
+
+    : 3\. Function argument
+
+    `keep`
+
+    : 4\. Function argument
+
+    `extra`
+
+    : 5\. Function argument
+
+    `f`
+
+    : 6\. Function argument
+  */
   makeScopeWithSplicing =
     splicePackages: newScope: otherSplices: keep: extra: f:
     makeScopeWithSplicing'
     { inherit splicePackages newScope; }
     { inherit otherSplices keep extra f; };
 
-  /* Like makeScope, but aims to support cross compilation. It's still ugly, but
+  /**
+    Like makeScope, but aims to support cross compilation. It's still ugly, but
     hopefully it helps a little bit.
 
-     Type:
+    # Type
+
+    ```
     makeScopeWithSplicing' ::
       { splicePackages :: Splice -> AttrSet
       , newScope :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a
@@ -469,6 +609,7 @@ rec {
       , pkgsHostTarget :: AttrSet
       , pkgsTargetTarget :: AttrSet
       }
+    ```
   */
   makeScopeWithSplicing' =
     { splicePackages