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 "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
starting at zero.
But for consistency with the rest of the library we want an index
starting at zero.
*/
imap = imap1;

View file

@ -16,9 +16,8 @@ in
unset = { tristate = null; 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: {
whenAtLeast = ver: mkIf (versionAtLeast version ver);
whenOlder = ver: mkIf (versionOlder version ver);

View file

@ -27,7 +27,7 @@ let
examples = import ./examples.nix { inherit lib; };
architectures = import ./architectures.nix { inherit lib; };
/*
/**
Elaborated systems contain functions, which means that they don't satisfy
`==` for a lack of reflexivity.
@ -45,10 +45,13 @@ let
let removeFunctions = a: filterAttrs (_: v: !isFunction v) a;
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 { };

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.
If you need to test error messages or more complex evaluations, see ./modules.sh, ./sources.sh or ./filesystem.sh as examples.
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.
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.
Alternatively, to run all `lib` tests:
[nixpkgs]$ nix-instantiate --eval --strict lib/tests/misc.nix
[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
@ -199,10 +203,10 @@ runTests {
};
/*
testOr = {
expr = or true false;
expected = true;
};
testOr = {
expr = or true false;
expected = true;
};
*/
testAnd = {
@ -1297,7 +1301,7 @@ runTests {
'';
};
/* right now only invocation check */
# right now only invocation check
testToJSONSimple =
let val = {
foobar = [ "baz" 1 2 3 ];
@ -1308,7 +1312,7 @@ runTests {
expected = builtins.toJSON val;
};
/* right now only invocation check */
# right now only invocation check
testToYAMLSimple =
let val = {
list = [ { one = 1; } { two = 2; } ];

View file

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

View file

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