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

This commit is contained in:
Johannes Kirschbauer 2024-03-07 14:04:50 +01:00 committed by GitHub
parent a35b03f5ed
commit 00f00e0663
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -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:
assertMsg false "nope"
stderr> error: nope
# Inputs
assert assertMsg ("foo" == "bar") "foo is not bar, silly"; ""
stderr> error: foo is not bar, silly
`pred`
Type:
assertMsg :: Bool -> String -> Bool
: Predicate that needs to succeed, otherwise `msg` is thrown
`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:
let sslLibrary = "libressl";
in assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ]
stderr> error: sslLibrary must be one of [
stderr> "openssl"
stderr> "bearssl"
stderr> ], but is: "libressl"
# Inputs
Type:
assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool
`name`
: 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:
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> ]
# Inputs
Type:
assertEachOneOf :: String -> List ComparableVal -> List ComparableVal -> Bool
`name`
: 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)