From 823e98a7cd14f43f2a856bc64d685f4b257e466f Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Fri, 29 Mar 2024 13:33:09 +0100 Subject: [PATCH 1/4] doc: migrate trivial files to doc-comment format --- lib/default.nix | 11 ++++---- lib/deprecated.nix | 9 ++++--- lib/kernel.nix | 11 ++++++-- lib/systems/default.nix | 11 +++++--- lib/tests/misc.nix | 34 +++++++++++++----------- lib/tests/modules/doRename-condition.nix | 4 +-- lib/tests/systems.nix | 9 ++++++- lib/types.nix | 26 +++++++++++------- 8 files changed, 73 insertions(+), 42 deletions(-) diff --git a/lib/default.nix b/lib/default.nix index 668c29640f9f1..f8eb5a71274b5 100644 --- a/lib/default.nix +++ b/lib/default.nix @@ -1,8 +1,9 @@ -/* Library of low-level helper functions for nix expressions. - * - * Please implement (mostly) exhaustive unit tests - * for new functions in `./tests.nix`. - */ +/** + Library of low-level helper functions for nix expressions. + + Please implement (mostly) exhaustive unit tests + for new functions in `./tests.nix`. +*/ let inherit (import ./fixed-points.nix { inherit lib; }) makeExtensible; diff --git a/lib/deprecated.nix b/lib/deprecated.nix index b76622b5d8421..d556bccbec0bc 100644 --- a/lib/deprecated.nix +++ b/lib/deprecated.nix @@ -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; diff --git a/lib/kernel.nix b/lib/kernel.nix index 7391f9e5d0798..94ed4fabbce2b 100644 --- a/lib/kernel.nix +++ b/lib/kernel.nix @@ -16,9 +16,16 @@ in unset = { tristate = null; optional = false; }; freeform = x: { freeform = x; optional = false; }; - /* + /** Common patterns/legacy used in common-config/hardened/config.nix - */ + + + # Inputs + + `version` + + : 1\. Function argument + */ whenHelpers = version: { whenAtLeast = ver: mkIf (versionAtLeast version ver); whenOlder = ver: mkIf (versionOlder version ver); diff --git a/lib/systems/default.nix b/lib/systems/default.nix index 83ed32ed3275b..7e9aadeef72e5 100644 --- a/lib/systems/default.nix +++ b/lib/systems/default.nix @@ -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 { }; diff --git a/lib/tests/misc.nix b/lib/tests/misc.nix index 6f1d9039db802..02eb86ab3ecc8 100644 --- a/lib/tests/misc.nix +++ b/lib/tests/misc.nix @@ -1,17 +1,17 @@ -/* -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. + If you need to test error messages or more complex evaluations, see ./modules.sh, ./sources.sh or ./filesystem.sh as examples. -To run these tests: + To run these tests: - [nixpkgs]$ nix-instantiate --eval --strict lib/tests/misc.nix + [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 + [nixpkgs]$ nix-build lib/tests/release.nix */ let @@ -198,10 +198,10 @@ runTests { }; /* - testOr = { - expr = or true false; - expected = true; - }; + testOr = { + expr = or true false; + expected = true; + }; */ testAnd = { @@ -1267,7 +1267,9 @@ runTests { ''; }; - /* right now only invocation check */ + /** + right now only invocation check + */ testToJSONSimple = let val = { foobar = [ "baz" 1 2 3 ]; @@ -1278,7 +1280,9 @@ runTests { expected = builtins.toJSON val; }; - /* right now only invocation check */ + /** + right now only invocation check + */ testToYAMLSimple = let val = { list = [ { one = 1; } { two = 2; } ]; diff --git a/lib/tests/modules/doRename-condition.nix b/lib/tests/modules/doRename-condition.nix index c08b3035be6f7..176c21a01a170 100644 --- a/lib/tests/modules/doRename-condition.nix +++ b/lib/tests/modules/doRename-condition.nix @@ -1,4 +1,4 @@ -/* +/** Simulate a migration from a single-instance `services.foo` to a multi instance `services.foos.` 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; diff --git a/lib/tests/systems.nix b/lib/tests/systems.nix index e142ff307fbd4..57777e7fb2448 100644 --- a/lib/tests/systems.nix +++ b/lib/tests/systems.nix @@ -10,7 +10,7 @@ let expected = lib.sort lib.lessThan y; }; - /* + /** Try to convert an elaborated system back to a simple string. If not possible, return null. So we have the property: @@ -19,6 +19,13 @@ let NOTE: This property is not guaranteed when `sys` was elaborated by a different version of Nixpkgs. + + + # Inputs + + `sys` + + : 1\. Function argument */ toLosslessStringMaybe = sys: if lib.isString sys then sys diff --git a/lib/types.nix b/lib/types.nix index 12bf18633e3a3..eb643c80cd69b 100644 --- a/lib/types.nix +++ b/lib/types.nix @@ -328,15 +328,23 @@ 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 + /** + 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; From b4730c14dfeec34f4caf51ac9ae1c4bbadfae577 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Wed, 3 Apr 2024 11:24:00 +0200 Subject: [PATCH 2/4] fix: revert some comments --- lib/default.nix | 11 +++++------ lib/kernel.nix | 10 +--------- lib/tests/misc.nix | 16 ++++++++-------- lib/tests/systems.nix | 2 +- 4 files changed, 15 insertions(+), 24 deletions(-) diff --git a/lib/default.nix b/lib/default.nix index f8eb5a71274b5..668c29640f9f1 100644 --- a/lib/default.nix +++ b/lib/default.nix @@ -1,9 +1,8 @@ -/** - Library of low-level helper functions for nix expressions. - - Please implement (mostly) exhaustive unit tests - for new functions in `./tests.nix`. -*/ +/* Library of low-level helper functions for nix expressions. + * + * Please implement (mostly) exhaustive unit tests + * for new functions in `./tests.nix`. + */ let inherit (import ./fixed-points.nix { inherit lib; }) makeExtensible; diff --git a/lib/kernel.nix b/lib/kernel.nix index 94ed4fabbce2b..d03d0103a678a 100644 --- a/lib/kernel.nix +++ b/lib/kernel.nix @@ -16,16 +16,8 @@ in unset = { tristate = null; optional = false; }; freeform = x: { freeform = x; optional = false; }; - /** - Common patterns/legacy used in common-config/hardened/config.nix - - # Inputs - - `version` - - : 1\. Function argument - */ + # Common patterns/legacy used in common-config/hardened/config.nix whenHelpers = version: { whenAtLeast = ver: mkIf (versionAtLeast version ver); whenOlder = ver: mkIf (versionOlder version ver); diff --git a/lib/tests/misc.nix b/lib/tests/misc.nix index 02eb86ab3ecc8..f19303fb06f6a 100644 --- a/lib/tests/misc.nix +++ b/lib/tests/misc.nix @@ -1,8 +1,12 @@ /** 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. + + If you need to test error messages or more complex evaluations, + `lib/tests/modules.sh`, `lib/tests/sources.sh` or `lib/tests/filesystem.sh` as examples. To run these tests: @@ -1267,9 +1271,7 @@ runTests { ''; }; - /** - right now only invocation check - */ + # right now only invocation check testToJSONSimple = let val = { foobar = [ "baz" 1 2 3 ]; @@ -1280,9 +1282,7 @@ runTests { expected = builtins.toJSON val; }; - /** - right now only invocation check - */ + # right now only invocation check testToYAMLSimple = let val = { list = [ { one = 1; } { two = 2; } ]; diff --git a/lib/tests/systems.nix b/lib/tests/systems.nix index 57777e7fb2448..ad0d67e55684f 100644 --- a/lib/tests/systems.nix +++ b/lib/tests/systems.nix @@ -10,7 +10,7 @@ let expected = lib.sort lib.lessThan y; }; - /** + /* Try to convert an elaborated system back to a simple string. If not possible, return null. So we have the property: From 4f2c6061549bda7a8863daacaf269f52207db2f0 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Thu, 4 Apr 2024 11:06:08 +0200 Subject: [PATCH 3/4] Apply suggestions from code review Thanks @danielSidhion Co-authored-by: Daniel Sidhion --- lib/tests/misc.nix | 2 +- lib/tests/systems.nix | 7 ------- 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/lib/tests/misc.nix b/lib/tests/misc.nix index f19303fb06f6a..039e0828550f3 100644 --- a/lib/tests/misc.nix +++ b/lib/tests/misc.nix @@ -5,7 +5,7 @@ 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, + 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: diff --git a/lib/tests/systems.nix b/lib/tests/systems.nix index ad0d67e55684f..e142ff307fbd4 100644 --- a/lib/tests/systems.nix +++ b/lib/tests/systems.nix @@ -19,13 +19,6 @@ let NOTE: This property is not guaranteed when `sys` was elaborated by a different version of Nixpkgs. - - - # Inputs - - `sys` - - : 1\. Function argument */ toLosslessStringMaybe = sys: if lib.isString sys then sys From 335a0a4e229114c2b30c1d9f01f74c030a2e90b9 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Thu, 4 Apr 2024 16:16:05 +0200 Subject: [PATCH 4/4] Update lib/types.nix --- lib/types.nix | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/types.nix b/lib/types.nix index eb643c80cd69b..e9bc939478c5f 100644 --- a/lib/types.nix +++ b/lib/types.nix @@ -328,6 +328,7 @@ rec { "signedInt${toString bit}" "${toString bit} bit signed integer"; in { + # TODO: Deduplicate with docs in nixos/doc/manual/development/option-types.section.md /** An int with a fixed range.