doc: auto-generate asserts and attrset library docs

If all the docs are auto-generated, it should be easier to convert
them to Commonmark.

Co-Authored-By: Valentin Gagarin <valentin.gagarin@tweag.io>
Co-Authored-By: Silvan Mosberger <contact@infinisil.com>

1 files changed, 15 insertions, 4 deletions

diff --git a/lib/asserts.nix b/lib/asserts.nix
index 9ae357cbc93..98e0b490acf 100644
--- a/lib/asserts.nix
+++ b/lib/asserts.nix
@@ -16,11 +16,15 @@ rec {
        assertMsg :: Bool -> String -> Bool
   */
   # TODO(Profpatsch): add tests that check stderr
-  assertMsg = pred: msg:
+  assertMsg =
+    # Predicate that needs to succeed, otherwise `msg` is thrown
+    pred:
+    # Message to throw in case `pred` fails
+    msg:
     pred || builtins.throw msg;
 
-  /* Specialized `assertMsg` for checking if val is one of the elements
-     of a list. Useful for checking enums.
+  /* Specialized `assertMsg` for checking if `val` is one of the elements
+     of the list `xs`. Useful for checking enums.
 
      Example:
        let sslLibrary = "libressl";
@@ -33,7 +37,14 @@ rec {
      Type:
        assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool
   */
-  assertOneOf = name: val: xs: assertMsg
+  assertOneOf =
+    # The name of the variable the user entered `val` into, for inclusion in the error message
+    name:
+    # The value of what the user provided, to be compared against the values in `xs`
+    val:
+    # The list of valid values
+    xs:
+    assertMsg
     (lib.elem val xs)
     "${name} must be one of ${
       lib.generators.toPretty {} xs}, but is: ${