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>

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

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);

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 { };
 

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.
+  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
@@ -199,10 +203,10 @@ runTests {
   };
 
   /*
-  testOr = {
+    testOr = {
-    expr = or true false;
+      expr = or true false;
-    expected = true;
+      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; } ];

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.<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;

lib/types.nix

@@ -328,15 +328,24 @@ rec {
           "signedInt${toString bit}" "${toString bit} bit signed integer";
 
       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;