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