doc: migrate trivial files to doc-comment format (#299986)

* doc: migrate trivial files to doc-comment format

* fix: revert some comments

* Apply suggestions from code review

Thanks @danielSidhion

Co-authored-by: Daniel Sidhion <DanielSidhion@users.noreply.github.com>

* Update lib/types.nix

---------

Co-authored-by: Daniel Sidhion <DanielSidhion@users.noreply.github.com>
Co-authored-by: Silvan Mosberger <github@infinisil.com>
This commit is contained in:
Johannes Kirschbauer 2024-04-04 16:36:07 +02:00 committed by GitHub
parent 52257144db
commit c0f5f271d1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 53 additions and 37 deletions

View file

@ -314,12 +314,13 @@ let
else if isInt x then "int" else if isInt x then "int"
else "string"; else "string";
/* deprecated: /**
# Deprecated
For historical reasons, imap has an index starting at 1. For historical reasons, imap has an index starting at 1.
But for consistency with the rest of the library we want an index But for consistency with the rest of the library we want an index
starting at zero. starting at zero.
*/ */
imap = imap1; imap = imap1;

View file

@ -16,9 +16,8 @@ in
unset = { tristate = null; optional = false; }; unset = { tristate = null; optional = false; };
freeform = x: { freeform = x; optional = false; }; freeform = x: { freeform = x; optional = false; };
/*
Common patterns/legacy used in common-config/hardened/config.nix # Common patterns/legacy used in common-config/hardened/config.nix
*/
whenHelpers = version: { whenHelpers = version: {
whenAtLeast = ver: mkIf (versionAtLeast version ver); whenAtLeast = ver: mkIf (versionAtLeast version ver);
whenOlder = ver: mkIf (versionOlder version ver); whenOlder = ver: mkIf (versionOlder version ver);

View file

@ -27,7 +27,7 @@ let
examples = import ./examples.nix { inherit lib; }; examples = import ./examples.nix { inherit lib; };
architectures = import ./architectures.nix { inherit lib; }; architectures = import ./architectures.nix { inherit lib; };
/* /**
Elaborated systems contain functions, which means that they don't satisfy Elaborated systems contain functions, which means that they don't satisfy
`==` for a lack of reflexivity. `==` for a lack of reflexivity.
@ -45,10 +45,13 @@ let
let removeFunctions = a: filterAttrs (_: v: !isFunction v) a; let removeFunctions = a: filterAttrs (_: v: !isFunction v) a;
in a: b: removeFunctions a == removeFunctions b; in a: b: removeFunctions a == removeFunctions b;
/* List of all Nix system doubles the nixpkgs flake will expose the package set /**
for. All systems listed here must be supported by nixpkgs as `localSystem`. List of all Nix system doubles the nixpkgs flake will expose the package set
for. All systems listed here must be supported by nixpkgs as `localSystem`.
**Warning**: This attribute is considered experimental and is subject to change. :::{.warning}
This attribute is considered experimental and is subject to change.
:::
*/ */
flakeExposed = import ./flake-systems.nix { }; flakeExposed = import ./flake-systems.nix { };

View file

@ -1,17 +1,21 @@
/* /**
Nix evaluation tests for various lib functions. Nix evaluation tests for various lib functions.
Since these tests are implemented with Nix evaluation, error checking is limited to what `builtins.tryEval` can detect, which is `throw`'s and `abort`'s, without error messages. Since these tests are implemented with Nix evaluation,
If you need to test error messages or more complex evaluations, see ./modules.sh, ./sources.sh or ./filesystem.sh as examples. error checking is limited to what `builtins.tryEval` can detect,
which is `throw`'s and `abort`'s, without error messages.
To run these tests: If you need to test error messages or more complex evaluations, see
`lib/tests/modules.sh`, `lib/tests/sources.sh` or `lib/tests/filesystem.sh` as examples.
[nixpkgs]$ nix-instantiate --eval --strict lib/tests/misc.nix To run these tests:
If the resulting list is empty, all tests passed. [nixpkgs]$ nix-instantiate --eval --strict lib/tests/misc.nix
Alternatively, to run all `lib` tests:
[nixpkgs]$ nix-build lib/tests/release.nix If the resulting list is empty, all tests passed.
Alternatively, to run all `lib` tests:
[nixpkgs]$ nix-build lib/tests/release.nix
*/ */
let let
@ -199,10 +203,10 @@ runTests {
}; };
/* /*
testOr = { testOr = {
expr = or true false; expr = or true false;
expected = true; expected = true;
}; };
*/ */
testAnd = { testAnd = {
@ -1297,7 +1301,7 @@ runTests {
''; '';
}; };
/* right now only invocation check */ # right now only invocation check
testToJSONSimple = testToJSONSimple =
let val = { let val = {
foobar = [ "baz" 1 2 3 ]; foobar = [ "baz" 1 2 3 ];
@ -1308,7 +1312,7 @@ runTests {
expected = builtins.toJSON val; expected = builtins.toJSON val;
}; };
/* right now only invocation check */ # right now only invocation check
testToYAMLSimple = testToYAMLSimple =
let val = { let val = {
list = [ { one = 1; } { two = 2; } ]; list = [ { one = 1; } { two = 2; } ];

View file

@ -1,4 +1,4 @@
/* /**
Simulate a migration from a single-instance `services.foo` to a multi instance Simulate a migration from a single-instance `services.foo` to a multi instance
`services.foos.<name>` module, where `name = ""` serves as the legacy / `services.foos.<name>` module, where `name = ""` serves as the legacy /
compatibility instance. compatibility instance.
@ -10,7 +10,7 @@
The relevant scenarios are tested in separate files: The relevant scenarios are tested in separate files:
- ./doRename-condition-enable.nix - ./doRename-condition-enable.nix
- ./doRename-condition-no-enable.nix - ./doRename-condition-no-enable.nix
*/ */
{ config, lib, ... }: { config, lib, ... }:
let let
inherit (lib) mkOption mkEnableOption types doRename; inherit (lib) mkOption mkEnableOption types doRename;

View file

@ -328,15 +328,24 @@ rec {
"signedInt${toString bit}" "${toString bit} bit signed integer"; "signedInt${toString bit}" "${toString bit} bit signed integer";
in { in {
/* An int with a fixed range. # TODO: Deduplicate with docs in nixos/doc/manual/development/option-types.section.md
* /**
* Example: An int with a fixed range.
* (ints.between 0 100).check (-1)
* => false # Example
* (ints.between 0 100).check (101) :::{.example}
* => false ## `lib.types.ints.between` usage example
* (ints.between 0 0).check 0
* => true ```nix
(ints.between 0 100).check (-1)
=> false
(ints.between 0 100).check (101)
=> false
(ints.between 0 0).check 0
=> true
```
:::
*/ */
inherit between; inherit between;