`emptyValue` for `types.submodule` was `{ value = { }; }`, i.e. none
of the type-declared options or their defaults.
Previously submodules without defs would simply fail for lack of a default,
but since PR #500104 repurposed `emptyValue` as the fallback when no
definitions exist, submodule options without an explicit `default = { }`
(new additions) silently lost their sub-option defaults
(e.g. `requiredFeatures.devnet` in the nixos-test-driver, #511413).
Main change: `emptyValue`: `{ }` -> `{ value = base.config; }`
Additionally, skip `emptyValue`-based default rendering in docs for
types with submodules, because their sub-options are already documented
individually, and forcing evaluation here can break on modules with
invalid or incomplete definitions.
- concrete types start with uppercase: Int, String, Bool, Derivation,
etc.
- type variables start with lowercase: a, b, etc.
- list:
- use `[x]` for homogeneous lists instead of `List x` or `[ x ]`
- use `List` for heterogeneous lists (not that common in `lib`)
- attr:
- use `AttrSet` for a generic attribute set type
- use `{ key1 :: Type1; key2 :: Type2; ... }` for adding signatures
for known attribute names and types
- use `{ key1 = value1; key2 = value2; ... }` for adding attributes
with known literals
- end with an ellipsis (`...`) if the set can contain unknown
attributes
- use `{ [String] :: x }` if all the attributes has the same type `x`
- prefer `Any` over `a` if the latter is not reused
Allows marking an option as invisible, without excluding its sub-options.
In practice, this is similar to `visible = true; internal = true;`,
however it is more explicit and less reliant on implementation details.
Format all Nix files using the officially approved formatter,
making the CI check introduced in the previous commit succeed:
nix-build ci -A fmt.check
This is the next step of the of the [implementation](https://github.com/NixOS/nixfmt/issues/153)
of the accepted [RFC 166](https://github.com/NixOS/rfcs/pull/166).
This commit will lead to merge conflicts for a number of PRs,
up to an estimated ~1100 (~33%) among the PRs with activity in the past 2
months, but that should be lower than what it would be without the previous
[partial treewide format](https://github.com/NixOS/nixpkgs/pull/322537).
Merge conflicts caused by this commit can now automatically be resolved while rebasing using the
[auto-rebase script](8616af08d9/maintainers/scripts/auto-rebase).
If you run into any problems regarding any of this, please reach out to the
[formatting team](https://nixos.org/community/teams/formatting/) by
pinging @NixOS/nix-formatting.
The previous code was optimized for the old uniq behavior, which did not
call merge. That's changed, so the legacy path is not a hot path anymore,
and is not worth any tech debt.
The deprecation warnings in lib were wildly inconsistent. Different
formulations were used in different places for the same meaning. Some warnings
used builtins.trace instead of lib.warn, which prevents silencing; one even
only had a comment instead. Make everything more uniform.
This doesn't change uniq. Why not?
- In NixOS it seems that uniq is only used with
simple types that are fully checked by t.check.
- It exists for much longer and is used more widely.
- I believe we should deprecate it, because unique was
already better.
- unique can be a proving ground.
with docbook gone and MD the default these aren't needed any more. we
can't remove them yet because there's thousands of uses, but maybe some
day we can.
no longer supported. warning when used would not be appropriate, and
docbook has been on the way out for long enough that throwing an error
should not be necessary either.
Some options have their default value set in the `config` instead of
`default`, for example to push `mkDefault`s down an attribute set.
In those cases, it's useful to provide a `defaultText` for informational
purposes.
nixdoc takes everything from Type: to Example: as the type, which
misrendered a large part of the docs. it also drops sorely needed spaces
where the type had line breaks, so all has to be on one line (or use
non-standard literal spaces, which is probably worse).
also clarify what the `?` for arguments mean while we're here.
There are a number of different syntaxes used for attrset type
signatures in our doc strings, this change standardises upon one that
uses :: for specifying attribute type, and ; terminators to be
consistent with nix syntax. There are no bugs in the functions
themselves, just that different syntaxes may confuse new users.
