lib.options: automatically generate example for booleans #18816
Conversation
This reduces the boilerplate that is written for boolean options.
We have to check if !default is valid, otherwise
mkOption {
type = types.enum [ false "x" ];
default = false;
}
would yield
example = true;
|
👍 but please also add documentation for these defaults! |
|
ping @nbp @shlevy do you have an opinion on this? we could remove all explicit |
| docOptionExample = | ||
| if opt ? example then { example = scrubOptionValue opt.example; } | ||
| else if opt.type == lib.types.bool then | ||
| { example = !docOptionDefault.default or false; } |
There was a problem hiding this comment.
nit: !(docOptionDefault.default or false)
There was a problem hiding this comment.
I'll change that to improve readability.
| if opt ? example then { example = scrubOptionValue opt.example; } | ||
| else if opt.type == lib.types.bool then | ||
| { example = !docOptionDefault.default or false; } | ||
| else if opt ? type && isBool (docOptionDefault.default or null) && opt.type.check (!docOptionDefault.default) then |
There was a problem hiding this comment.
In opt.type.check (!docOptionDefault.default), the attribute default might not exists, and raise an error.
There was a problem hiding this comment.
That should never happen since it's only evaluated if isBool (docOptionDefault.default or null)
| else if opt.type == lib.types.bool then | ||
| { example = !docOptionDefault.default or false; } | ||
| else if opt ? type && isBool (docOptionDefault.default or null) && opt.type.check (!docOptionDefault.default) then | ||
| { example = !docOptionDefault.default or false; } |
There was a problem hiding this comment.
nit: !(… or …)
nit: factor this expression in a let … in ….
There was a problem hiding this comment.
I'll check if I can factor that out, but I'd rather not add a let.
Reading it again it's strange I check for opt.type == bool and in the else case check opt ? type. This looks wrong 😕
|
IMO, examples for bools contain no useful information. I vote to remove all examples for bools instead. |
|
I agree with @joachifm, and every example adds 2 lines to |
|
I think there is no sufficient interest in this and we should rather remove the boolean examples. Closing this for now. RFC sounds useful if people want this. |
They contain no useful information and increase the length of the autogenerated options documentation. See discussion in #18816.
Motivation for this change
Remove the need to provide an example for boolean options. Since there are only two possibilities, setting
example = !defaultis reasonable. This should remove the amount of boilerplate in nixpkgs by a few hundred lines.Also catches cases where
type == boolbutdefaultis not defined and providesexample = true.The second commit catches cases where
type != boolbutisBool defaultholds (type may be undefined or something likenullOr bool) and!defaultis a valid value.If this is too expensive we can also drop it, but since this is only executed for the manual generation, it should be ok.
The first commit adds 853 example values to options-db.xml, the second one another 3.
ref #18803 could use this 😉
Things done
(nix.useSandbox on NixOS,
or option
build-use-sandboxinnix.confon non-NixOS)
nix-shell -p nox --run "nox-review wip"