doc: migrate trivial files to doc-comment format

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;

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;
 

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

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,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
@@ -197,11 +197,11 @@ 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; } ];

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/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

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;