From 8a8fe93e6b9395e0dacc61021b475fb3e2c0bce2 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Mon, 3 Jun 2024 16:04:11 +0200
Subject: [PATCH] doc: minor fixes

---
 lib/options.nix | 68 ++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 62 insertions(+), 6 deletions(-)

diff --git a/lib/options.nix b/lib/options.nix
index 36f8f8c9b5300..437e1c4b85176 100644
--- a/lib/options.nix
+++ b/lib/options.nix
@@ -48,11 +48,11 @@ in
 rec {
 
   /**
-    Returns true when the given argument is an option
+    Returns true when the given argument `a` is an option
 
     # Inputs
 
-    `value`
+    `a`
     : Any value to check whether it is an option
 
     # Examples
@@ -375,20 +375,35 @@ rec {
 
   /**
     A merge function that merges multiple definitions of an option into a single value
-    by checking that they are all equal.
-    Merge functions are typically used for constructing option types.
+
+    :::{.caution}
+    This function is used as the default merge operation in `lib.types.mkOptionType`. In most cases, explicit usage of this function is unnecessary.
+    :::
 
     # Inputs
 
     `loc`
     : location of the option in the configuration as a list of strings.
 
-      e.g. ["boot" "loader "grub" "enable"]
+      e.g. `["boot" "loader "grub" "enable"]`
 
     `defs`
     : list of definition values and locations.
 
-      e.g. [ { file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 } ]
+      e.g. `[ { file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 } ]`
+
+    # Example
+    :::{.example}
+    ## `lib.options.mergeDefaultOption` usage example
+
+    ```nix
+    myType = mkOptionType {
+      name = "myType";
+      merge = mergeDefaultOption; # <- This line is redundant. It is the default aready.
+    };
+    ```
+
+    :::
 
     # Merge behavior
 
@@ -623,6 +638,47 @@ rec {
     in "\n- In `${def.file}'${result}"
   ) defs;
 
+  /**
+    Pretty prints all option definition locations
+
+    # Inputs
+
+    `option`
+    : The option to pretty print
+
+    # Examples
+    :::{.example}
+    ## `lib.options.showOptionWithDefLocs` usage example
+
+
+    ```nix
+    showOptionWithDefLocs { loc = ["x" "y" ]; files = [ "foo.nix" "bar.nix" ];  }
+    "x.y, with values defined in:\n  - foo.nix\n  - bar.nix\n"
+    ```
+
+    ```nix
+    nix-repl> eval = lib.evalModules {
+        modules = [
+          {
+            options = {
+              foo = lib.mkEnableOption "foo";
+            };
+          }
+        ];
+      }
+
+    nix-repl> lib.options.showOptionWithDefLocs eval.options.foo
+    "foo, with values defined in:\n  - <unknown-file>\n"
+    ```
+
+    :::
+
+    # Type
+
+    ```
+    showDefsSep :: { files :: [ String ]; loc :: [ String ]; ... } -> string
+    ```
+  */
   showOptionWithDefLocs = opt: ''
       ${showOption opt.loc}, with values defined in:
       ${concatMapStringsSep "\n" (defFile: "  - ${defFile}") opt.files}