doc: lib.asserts migrate to doc-comments (#292310)

lib/asserts.nix

@@ -2,47 +2,87 @@
 
 rec {
 
-  /* Throw if pred is false, else return pred.
+  /**
-     Intended to be used to augment asserts with helpful error messages.
+    Throw if pred is false, else return pred.
+    Intended to be used to augment asserts with helpful error messages.
 
-     Example:
+    # Inputs
-       assertMsg false "nope"
-       stderr> error: nope
 
-       assert assertMsg ("foo" == "bar") "foo is not bar, silly"; ""
+    `pred`
-       stderr> error: foo is not bar, silly
 
-     Type:
+    : Predicate that needs to succeed, otherwise `msg` is thrown
-       assertMsg :: Bool -> String -> Bool
+
+    `msg`
+
+    : Message to throw in case `pred` fails
+
+    # Type
+
+    ```
+    assertMsg :: Bool -> String -> Bool
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.asserts.assertMsg` usage example
+
+    ```nix
+    assertMsg false "nope"
+    stderr> error: nope
+    assert assertMsg ("foo" == "bar") "foo is not bar, silly"; ""
+    stderr> error: foo is not bar, silly
+    ```
+
+    :::
   */
   # TODO(Profpatsch): add tests that check stderr
   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 the list `xs`. Useful for checking enums.
+    Specialized `assertMsg` for checking if `val` is one of the elements
+    of the list `xs`. Useful for checking enums.
 
-     Example:
+    # Inputs
-       let sslLibrary = "libressl";
-       in assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ]
-       stderr> error: sslLibrary must be one of [
-       stderr>   "openssl"
-       stderr>   "bearssl"
-       stderr> ], but is: "libressl"
 
-     Type:
+    `name`
-       assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool
+
+    : The name of the variable the user entered `val` into, for inclusion in the error message
+
+    `val`
+
+    : The value of what the user provided, to be compared against the values in `xs`
+
+    `xs`
+
+    : The list of valid values
+
+    # Type
+
+    ```
+    assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.asserts.assertOneOf` usage example
+
+    ```nix
+    let sslLibrary = "libressl";
+    in assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ]
+    stderr> error: sslLibrary must be one of [
+    stderr>   "openssl"
+    stderr>   "bearssl"
+    stderr> ], but is: "libressl"
+    ```
+
+    :::
   */
   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)
@@ -50,29 +90,51 @@ rec {
       lib.generators.toPretty {} xs}, but is: ${
         lib.generators.toPretty {} val}";
 
-  /* Specialized `assertMsg` for checking if every one of `vals` is one of the elements
+  /**
-     of the list `xs`. Useful for checking lists of supported attributes.
+    Specialized `assertMsg` for checking if every one of `vals` is one of the elements
+    of the list `xs`. Useful for checking lists of supported attributes.
 
-     Example:
+    # Inputs
-       let sslLibraries = [ "libressl" "bearssl" ];
-       in assertEachOneOf "sslLibraries" sslLibraries [ "openssl" "bearssl" ]
-       stderr> error: each element in sslLibraries must be one of [
-       stderr>   "openssl"
-       stderr>   "bearssl"
-       stderr> ], but is: [
-       stderr>   "libressl"
-       stderr>   "bearssl"
-       stderr> ]
 
-     Type:
+    `name`
-       assertEachOneOf :: String -> List ComparableVal -> List ComparableVal -> Bool
+
+    : The name of the variable the user entered `val` into, for inclusion in the error message
+
+    `vals`
+
+    : The list of values of what the user provided, to be compared against the values in `xs`
+
+    `xs`
+
+    : The list of valid values
+
+    # Type
+
+    ```
+    assertEachOneOf :: String -> List ComparableVal -> List ComparableVal -> Bool
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.asserts.assertEachOneOf` usage example
+
+    ```nix
+    let sslLibraries = [ "libressl" "bearssl" ];
+    in assertEachOneOf "sslLibraries" sslLibraries [ "openssl" "bearssl" ]
+    stderr> error: each element in sslLibraries must be one of [
+    stderr>   "openssl"
+    stderr>   "bearssl"
+    stderr> ], but is: [
+    stderr>   "libressl"
+    stderr>   "bearssl"
+    stderr> ]
+    ```
+
+    :::
   */
   assertEachOneOf =
-    # The name of the variable the user entered `val` into, for inclusion in the error message
     name:
-    # The list of values of what the user provided, to be compared against the values in `xs`
     vals:
-    # The list of valid values
     xs:
     assertMsg
     (lib.all (val: lib.elem val xs) vals)