doc: migrate lib.debug to doc-comment format

lib/debug.nix

@@ -1,4 +1,5 @@
-/* Collection of functions useful for debugging
+/**
+  Collection of functions useful for debugging
   broken nix expressions.
 
   * `trace`-like functions take two values, print
@@ -32,78 +33,189 @@ rec {
 
   # -- TRACING --
 
-  /* Conditionally trace the supplied message, based on a predicate.
+  /**
+    Conditionally trace the supplied message, based on a predicate.
 
-     Type: traceIf :: bool -> string -> a -> a
 
-     Example:
+    # Inputs
+
+    `pred`
+
+    : Predicate to check
+
+    `msg`
+
+    : Message that should be traced
+
+    `x`
+
+    : Value to return
+
+    # Type
+
+    ```
+    traceIf :: bool -> string -> a -> a
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.debug.traceIf` usage example
+
+    ```nix
     traceIf true "hello" 3
     trace: hello
     => 3
+    ```
+
+    :::
   */
   traceIf =
-    # Predicate to check
     pred:
-    # Message that should be traced
     msg:
-    # Value to return
     x: if pred then trace msg x else x;
 
-  /* Trace the supplied value after applying a function to it, and
+  /**
+    Trace the supplied value after applying a function to it, and
     return the original value.
 
-     Type: traceValFn :: (a -> b) -> a -> a
 
-     Example:
+    # Inputs
+
+    `f`
+
+    : Function to apply
+
+    `x`
+
+    : Value to trace and return
+
+    # Type
+
+    ```
+    traceValFn :: (a -> b) -> a -> a
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.debug.traceValFn` usage example
+
+    ```nix
     traceValFn (v: "mystring ${v}") "foo"
     trace: mystring foo
     => "foo"
+    ```
+
+    :::
   */
   traceValFn =
-    # Function to apply
     f:
-    # Value to trace and return
     x: trace (f x) x;
 
-  /* Trace the supplied value and return it.
+  /**
+    Trace the supplied value and return it.
 
-     Type: traceVal :: a -> a
+    # Inputs
 
-     Example:
+    `x`
+
+    : Value to trace and return
+
+    # Type
+
+    ```
+    traceVal :: a -> a
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.debug.traceVal` usage example
+
+    ```nix
     traceVal 42
     # trace: 42
     => 42
+    ```
+
+    :::
   */
   traceVal = traceValFn id;
 
-  /* `builtins.trace`, but the value is `builtins.deepSeq`ed first.
+  /**
+    `builtins.trace`, but the value is `builtins.deepSeq`ed first.
 
-     Type: traceSeq :: a -> b -> b
 
-     Example:
+    # Inputs
+
+    `x`
+
+    : The value to trace
+
+    `y`
+
+    : The value to return
+
+    # Type
+
+    ```
+    traceSeq :: a -> b -> b
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.debug.traceSeq` usage example
+
+    ```nix
     trace { a.b.c = 3; } null
     trace: { a = <CODE>; }
     => null
     traceSeq { a.b.c = 3; } null
     trace: { a = { b = { c = 3; }; }; }
     => null
+    ```
+
+    :::
   */
   traceSeq =
-    # The value to trace
     x:
-    # The value to return
     y: trace (builtins.deepSeq x x) y;
 
-  /* Like `traceSeq`, but only evaluate down to depth n.
+  /**
+    Like `traceSeq`, but only evaluate down to depth n.
     This is very useful because lots of `traceSeq` usages
     lead to an infinite recursion.
 
-     Example:
+
+    # Inputs
+
+    `depth`
+
+    : 1\. Function argument
+
+    `x`
+
+    : 2\. Function argument
+
+    `y`
+
+    : 3\. Function argument
+
+    # Type
+
+    ```
+    traceSeqN :: Int -> a -> b -> b
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.debug.traceSeqN` usage example
+
+    ```nix
     traceSeqN 2 { a.b.c = 3; } null
     trace: { a = { b = {…}; }; }
     => null
+    ```
 
-     Type: traceSeqN :: Int -> a -> b -> b
+    :::
   */
   traceSeqN = depth: x: y:
     let snip = v: if      isList  v then noQuotes "[…]" v
@@ -118,41 +230,115 @@ rec {
     in trace (generators.toPretty { allowPrettyValues = true; }
                (modify depth snip x)) y;
 
-  /* A combination of `traceVal` and `traceSeq` that applies a
+  /**
+    A combination of `traceVal` and `traceSeq` that applies a
     provided function to the value to be traced after `deepSeq`ing
     it.
+
+
+    # Inputs
+
+    `f`
+
+    : Function to apply
+
+    `v`
+
+    : Value to trace
   */
   traceValSeqFn =
-    # Function to apply
     f:
-    # Value to trace
     v: traceValFn f (builtins.deepSeq v v);
 
-  /* A combination of `traceVal` and `traceSeq`. */
+  /**
+    A combination of `traceVal` and `traceSeq`.
+
+    # Inputs
+
+    `v`
+
+    : Value to trace
+
+  */
   traceValSeq = traceValSeqFn id;
 
-  /* A combination of `traceVal` and `traceSeqN` that applies a
-  provided function to the value to be traced. */
+  /**
+    A combination of `traceVal` and `traceSeqN` that applies a
+    provided function to the value to be traced.
+
+
+    # Inputs
+
+    `f`
+
+    : Function to apply
+
+    `depth`
+
+    : 2\. Function argument
+
+    `v`
+
+    : Value to trace
+  */
   traceValSeqNFn =
-    # Function to apply
     f:
     depth:
-    # Value to trace
     v: traceSeqN depth (f v) v;
 
-  /* A combination of `traceVal` and `traceSeqN`. */
+  /**
+    A combination of `traceVal` and `traceSeqN`.
+
+    # Inputs
+
+    `depth`
+
+    : 1\. Function argument
+
+    `v`
+
+    : Value to trace
+  */
   traceValSeqN = traceValSeqNFn id;
 
-  /* Trace the input and output of a function `f` named `name`,
+  /**
+    Trace the input and output of a function `f` named `name`,
     both down to `depth`.
 
     This is useful for adding around a function call,
     to see the before/after of values as they are transformed.
 
-     Example:
+
+    # Inputs
+
+    `depth`
+
+    : 1\. Function argument
+
+    `name`
+
+    : 2\. Function argument
+
+    `f`
+
+    : 3\. Function argument
+
+    `v`
+
+    : 4\. Function argument
+
+
+    # Examples
+    :::{.example}
+    ## `lib.debug.traceFnSeqN` usage example
+
+    ```nix
     traceFnSeqN 2 "id" (x: x) { a.b.c = 3; }
     trace: { fn = "id"; from = { a.b = {…}; }; to = { a.b = {…}; }; }
     => { a.b.c = 3; }
+    ```
+
+    :::
   */
   traceFnSeqN = depth: name: f: v:
     let res = f v;
@@ -168,7 +354,8 @@ rec {
 
   # -- TESTING --
 
-  /* Evaluates a set of tests.
+  /**
+    Evaluates a set of tests.
 
     A test is an attribute set `{expr, expected}`,
     denoting an expression and its expected result.
@@ -188,8 +375,38 @@ rec {
 
     - If you want to run only a subset of the tests add the attribute `tests = ["testName"];`
 
-    Example:
 
+    # Inputs
+
+    `tests`
+
+    : Tests to run
+
+    # Type
+
+    ```
+    runTests :: {
+      tests = [ String ];
+      ${testName} :: {
+        expr :: a;
+        expected :: a;
+      };
+    }
+    ->
+    [
+      {
+        name :: String;
+        expected :: a;
+        result :: a;
+      }
+    ]
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.debug.runTests` usage example
+
+    ```nix
     runTests {
       testAndOk = {
         expr = lib.and true false;
@@ -208,26 +425,11 @@ rec {
         result = false;
       }
     ]
+    ```
 
-    Type:
-      runTests :: {
-        tests = [ String ];
-        ${testName} :: {
-          expr :: a;
-          expected :: a;
-        };
-      }
-      ->
-      [
-        {
-          name :: String;
-          expected :: a;
-          result :: a;
-        }
-      ]
+    :::
   */
   runTests =
-    # Tests to run
     tests: concatLists (attrValues (mapAttrs (name: test:
     let testsToRun = if tests ? tests then tests.tests else [];
     in if (substring 0 4 name == "test" ||  elem name testsToRun)
@@ -237,10 +439,26 @@ rec {
       then [ { inherit name; expected = test.expected; result = test.expr; } ]
       else [] ) tests));
 
-  /* Create a test assuming that list elements are `true`.
+  /**
+    Create a test assuming that list elements are `true`.
 
-     Example:
+
+    # Inputs
+
+    `expr`
+
+    : 1\. Function argument
+
+
+    # Examples
+    :::{.example}
+    ## `lib.debug.testAllTrue` usage example
+
+    ```nix
     { testX = allTrue [ true ]; }
+    ```
+
+    :::
   */
   testAllTrue = expr: { inherit expr; expected = map (x: true) expr; };
 }