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,7 +314,8 @@ let
else if isInt x then "int"
else "string";
/* deprecated:
/**
# Deprecated
For historical reasons, imap has an index starting at 1.

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
/**
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,15 +1,19 @@
/*
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.
To run these tests:
[nixpkgs]$ nix-instantiate --eval --strict lib/tests/misc.nix
If the resulting list is empty, all tests passed.
Alternatively, to run all `lib` tests:
If the resulting list is empty, all tests passed.
Alternatively, to run all `lib` tests:
[nixpkgs]$ nix-build lib/tests/release.nix
*/
@ -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;