From c0f5f271d1cbc469d47306ef58f67241f8654e12 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Thu, 4 Apr 2024 16:36:07 +0200 Subject: [PATCH] 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 * Update lib/types.nix --------- Co-authored-by: Daniel Sidhion Co-authored-by: Silvan Mosberger --- lib/deprecated.nix | 9 ++++--- lib/kernel.nix | 5 ++-- lib/systems/default.nix | 11 +++++--- lib/tests/misc.nix | 34 +++++++++++++----------- lib/tests/modules/doRename-condition.nix | 4 +-- lib/types.nix | 27 ++++++++++++------- 6 files changed, 53 insertions(+), 37 deletions(-) diff --git a/lib/deprecated.nix b/lib/deprecated.nix index b76622b5d842..d556bccbec0b 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 7391f9e5d079..d03d0103a678 100644 --- a/lib/kernel.nix +++ b/lib/kernel.nix @@ -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); diff --git a/lib/systems/default.nix b/lib/systems/default.nix index 83ed32ed3275..7e9aadeef72e 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 3cb96c1b68bc..da5e32297509 100644 --- a/lib/tests/misc.nix +++ b/lib/tests/misc.nix @@ -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; } ]; diff --git a/lib/tests/modules/doRename-condition.nix b/lib/tests/modules/doRename-condition.nix index c08b3035be6f..176c21a01a17 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/types.nix b/lib/types.nix index 12bf18633e3a..e9bc939478c5 100644 --- a/lib/types.nix +++ b/lib/types.nix @@ -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;