doc: migrate lib.customisation to use doc-comments

lib/customisation.nix

@@ -15,42 +15,64 @@ in
 rec {
 
 
-  /* `overrideDerivation drv f` takes a derivation (i.e., the result
+  /**
-     of a call to the builtin function `derivation`) and returns a new
+    `overrideDerivation drv f` takes a derivation (i.e., the result
-     derivation in which the attributes of the original are overridden
+    of a call to the builtin function `derivation`) and returns a new
-     according to the function `f`.  The function `f` is called with
+    derivation in which the attributes of the original are overridden
-     the original derivation attributes.
+    according to the function `f`.  The function `f` is called with
+    the original derivation attributes.
 
-     `overrideDerivation` allows certain "ad-hoc" customisation
+    `overrideDerivation` allows certain "ad-hoc" customisation
-     scenarios (e.g. in ~/.config/nixpkgs/config.nix).  For instance,
+    scenarios (e.g. in ~/.config/nixpkgs/config.nix).  For instance,
-     if you want to "patch" the derivation returned by a package
+    if you want to "patch" the derivation returned by a package
-     function in Nixpkgs to build another version than what the
+    function in Nixpkgs to build another version than what the
-     function itself provides.
+    function itself provides.
 
-     For another application, see build-support/vm, where this
+    For another application, see build-support/vm, where this
-     function is used to build arbitrary derivations inside a QEMU
+    function is used to build arbitrary derivations inside a QEMU
-     virtual machine.
+    virtual machine.
 
-     Note that in order to preserve evaluation errors, the new derivation's
+    Note that in order to preserve evaluation errors, the new derivation's
-     outPath depends on the old one's, which means that this function cannot
+    outPath depends on the old one's, which means that this function cannot
-     be used in circular situations when the old derivation also depends on the
+    be used in circular situations when the old derivation also depends on the
-     new one.
+    new one.
 
-     You should in general prefer `drv.overrideAttrs` over this function;
+    You should in general prefer `drv.overrideAttrs` over this function;
-     see the nixpkgs manual for more information on overriding.
+    see the nixpkgs manual for more information on overriding.
 
-     Example:
-       mySed = overrideDerivation pkgs.gnused (oldAttrs: {
-         name = "sed-4.2.2-pre";
-         src = fetchurl {
-           url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2;
-           hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY=";
-         };
-         patches = [];
-       });
 
-     Type:
+    # Inputs
-       overrideDerivation :: Derivation -> ( Derivation -> AttrSet ) -> Derivation
+
+    `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 {
+        url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2;
+        hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY=";
+      };
+      patches = [];
+    });
+    ```
+
+    :::
   */
   overrideDerivation = drv: f:
     let
@@ -67,26 +89,44 @@ rec {
       });
 
 
-  /* `makeOverridable` takes a function from attribute set to attribute set and
+  /**
-     injects `override` attribute which can be used to override arguments of
+    `makeOverridable` takes a function from attribute set to attribute set and
-     the function.
+    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
+    Please refer to  documentation on [`<pkg>.overrideDerivation`](#sec-pkg-overrideDerivation) to learn about `overrideDerivation` and caveats
-     related to its use.
+    related to its use.
 
-     Example:
-       nix-repl> x = {a, b}: { result = a + b; }
 
-       nix-repl> y = lib.makeOverridable x { a = 1; b = 2; }
+    # Inputs
 
-       nix-repl> y
+    `f`
-       { override = «lambda»; overrideDerivation = «lambda»; result = 3; }
 
-       nix-repl> y.override { a = 10; }
+    : 1\. Function argument
-       { override = «lambda»; overrideDerivation = «lambda»; result = 12; }
 
-     Type:
+    # Type
-       makeOverridable :: (AttrSet -> a) -> AttrSet -> a
+
+    ```
+    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; }
+
+    nix-repl> y
+    { override = «lambda»; overrideDerivation = «lambda»; result = 3; }
+
+    nix-repl> y.override { a = 10; }
+    { override = «lambda»; overrideDerivation = «lambda»; result = 12; }
+    ```
+
+    :::
   */
   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:
+
-      callPackageWith :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a
+    # 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
+  /**
-     set of derivations. The override function is added to the
+    Like callPackage, but for a function that returns an attribute
-     individual attributes.
+    set of derivations. The override function is added to the
+    individual attributes.
 
-     Type:
+
-       callPackagesWith :: AttrSet -> ((AttrSet -> AttrSet) | Path) -> AttrSet -> AttrSet
+    # 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
+  /**
-     the derivation itself and check a given condition when evaluating.
+    Add attributes to each output of a derivation without changing
+    the derivation itself and check a given condition when evaluating.
 
-     Type:
+
-       extendDerivation :: Bool -> Any -> Derivation -> Derivation
+    # 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
+  /**
-     only those needed by hydra-eval-jobs. Also strictly evaluate the
+    Strip a derivation of all non-essential attributes, returning
-     result to ensure that there are no thunks kept alive to prevent
+    only those needed by hydra-eval-jobs. Also strictly evaluate the
-     garbage collection.
+    result to ensure that there are no thunks kept alive to prevent
+    garbage collection.
 
-     Type:
+
-       hydraJob :: (Derivation | Null) -> (Derivation | Null)
+    # Inputs
+
+    `drv`
+
+    : 1\. Function argument
+
+    # Type
+
+    ```
+    hydraJob :: (Derivation | Null) -> (Derivation | Null)
+    ```
   */
   hydraJob = drv:
     let
@@ -443,32 +551,65 @@ 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
+  /**
-     hopefully it helps a little bit.
+    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
-         }
-         -> { otherSplices :: Splice, keep :: AttrSet -> AttrSet, extra :: AttrSet -> AttrSet }
-         -> AttrSet
 
-       Splice ::
+    ```
-         { pkgsBuildBuild :: AttrSet
+    makeScopeWithSplicing' ::
-         , pkgsBuildHost :: AttrSet
+      { splicePackages :: Splice -> AttrSet
-         , pkgsBuildTarget :: AttrSet
+      , newScope :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a
-         , pkgsHostHost :: AttrSet
+      }
-         , pkgsHostTarget :: AttrSet
+      -> { otherSplices :: Splice, keep :: AttrSet -> AttrSet, extra :: AttrSet -> AttrSet }
-         , pkgsTargetTarget :: AttrSet
+      -> AttrSet
-         }
+
+    Splice ::
+      { pkgsBuildBuild :: AttrSet
+      , pkgsBuildHost :: AttrSet
+      , pkgsBuildTarget :: AttrSet
+      , pkgsHostHost :: AttrSet
+      , pkgsHostTarget :: AttrSet
+      , pkgsTargetTarget :: AttrSet
+      }
+    ```
   */
   makeScopeWithSplicing' =
     { splicePackages