lib/debug: Update documentation comments for docs generation

Documents functions in `lib.debug` for docs generation with nixdoc.

Note that type signatures and clearer descriptions are still missing
on some of these functions, but this is good enough for a first run.

lib/debug.nix

@@ -23,27 +23,54 @@ rec {
 
   # -- TRACING --
 
-  /* Trace msg, but only if pred is true.
+  /* Conditionally trace the supplied message, based on a predicate.
+
+     Type: traceIf :: bool -> string -> a -> a
 
      Example:
        traceIf true "hello" 3
        trace: hello
        => 3
   */
-  traceIf = pred: msg: x: if pred then trace msg x else x;
+  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 value and also return it.
+  /* Trace the supplied value after applying a function to it, and
+     return the original value.
+
+     Type: traceValFn :: (a -> b) -> a -> a
 
      Example:
        traceValFn (v: "mystring ${v}") "foo"
        trace: mystring foo
        => "foo"
   */
-  traceValFn = f: x: trace (f x) x;
+  traceValFn =
+    # Function to apply
+    f:
+    # Value to trace and return
+    x: trace (f x) x;
+
+  /* Trace the supplied value and return it.
+
+     Type: traceVal :: a -> a
+
+     Example:
+       traceVal 42
+       # trace: 42
+       => 42
+  */
   traceVal = traceValFn id;
 
   /* `builtins.trace`, but the value is `builtins.deepSeq`ed first.
 
+     Type: traceSeq :: a -> b -> b
+
      Example:
        trace { a.b.c = 3; } null
        trace: { a = <CODE>; }
@@ -52,7 +79,11 @@ rec {
        trace: { a = { b = { c = 3; }; }; }
        => null
   */
-  traceSeq = x: y: trace (builtins.deepSeq x x) y;
+  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.
      This is very useful because lots of `traceSeq` usages
@@ -76,27 +107,49 @@ rec {
     in trace (generators.toPretty { allowPrettyValues = true; }
                (modify depth snip x)) y;
 
-  /* A combination of `traceVal` and `traceSeq` */
+  /* A combination of `traceVal` and `traceSeq` that applies a
-  traceValSeqFn = f: v: traceValFn f (builtins.deepSeq v v);
+     provided function to the value to be traced after `deepSeq`ing
+     it.
+  */
+  traceValSeqFn =
+    # Function to apply
+    f:
+    # Value to trace
+    v: traceValFn f (builtins.deepSeq v v);
+
+  /* A combination of `traceVal` and `traceSeq`. */
   traceValSeq = traceValSeqFn id;
 
+  /* A combination of `traceVal` and `traceSeqN` that applies a
+  provided function to the value to be traced. */
+  traceValSeqNFn =
+    # Function to apply
+    f:
+    depth:
+    # Value to trace
+    v: traceSeqN depth (f v) v;
+
   /* A combination of `traceVal` and `traceSeqN`. */
-  traceValSeqNFn = f: depth: v: traceSeqN depth (f v) v;
   traceValSeqN = traceValSeqNFn id;
 
 
   # -- TESTING --
 
-  /* Evaluate a set of tests.  A test is an attribute set {expr,
+  /* Evaluate a set of tests.  A test is an attribute set `{expr,
-     expected}, denoting an expression and its expected result.  The
+     expected}`, denoting an expression and its expected result.  The
-     result is a list of failed tests, each represented as {name,
+     result is a list of failed tests, each represented as `{name,
-     expected, actual}, denoting the attribute name of the failing
+     expected, actual}`, denoting the attribute name of the failing
-     test and its expected and actual results.  Used for regression
+     test and its expected and actual results.
-     testing of the functions in lib; see tests.nix for an example.
+
-     Only tests having names starting with "test" are run.
+     Used for regression testing of the functions in lib; see
-     Add attr { tests = ["testName"]; } to run these test only
+     tests.nix for an example. Only tests having names starting with
+     "test" are run.
+
+     Add attr { tests = ["testName"]; } to run these tests only.
   */
-  runTests = tests: lib.concatLists (lib.attrValues (lib.mapAttrs (name: test:
+  runTests =
+    # Tests to run
+    tests: lib.concatLists (lib.attrValues (lib.mapAttrs (name: test:
     let testsToRun = if tests ? tests then tests.tests else [];
     in if (substring 0 4 name == "test" ||  elem name testsToRun)
        && ((testsToRun == []) || elem name tests.tests)
@@ -105,8 +158,11 @@ 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`.
-  # usage: { testX = allTrue [ true ]; }
+
+     Example:
+       { testX = allTrue [ true ]; }
+  */
   testAllTrue = expr: { inherit expr; expected = map (x: true) expr; };