From 023e9300bbd09201741ac4a5924d533d41f74473 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Fri, 12 Dec 2025 15:14:38 +0100
Subject: [PATCH] lib/modules: document limitations of 'mkRenamedOptionModule'

---
 lib/modules.nix | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/lib/modules.nix b/lib/modules.nix
index e545f9c9707d..e0814d5e2061 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -1630,11 +1630,21 @@ let
 
     `from`
 
-    : 1\. Function argument
+    : The "from" option path as list of strings.
+      Option must not exist in the current module set.
 
     `to`
 
-    : 2\. Function argument
+    : The "to" option path as list of strings.
+      Option must already exist in the current module set.
+
+    # Limitations
+
+    - The "to" option must already be declared.
+    - The "from" option should not be declared, as this function will declare it.
+    - "to" Options whose types don't support merging at any level of their structure (like `types.raw`,
+      or `types.attrsOf types.raw` where the attribute values can't merge) are not well-supported
+      because this function wraps aliased definitions in `mkMerge`.
   */
   mkRenamedOptionModule =
     from: to: