PATCH] lib: copy documentation from manual to types.submodulesWith

Development Patches
1
Patch from git format-patch HEAD^ 
From 9d01e329611f04cc213e0345625ac658e2de5ced Mon Sep 17 00:00:00 2001
From: Do Nix <um2iai+9g233t397b57k@sharklasers.com>
Date: Fri, 14 Feb 2025 18:42:12 +0100
Subject: [PATCH] lib: copy documentation from manual to types.submodulesWith

To have https://noogle.dev/f/lib/types/submoduleWith present something.
A better documentation should be added later:

 - explaining what a "module" is
 - giving an example
 - a better explanation of shorthandOnlyDefinesConfig
   probably more understandable once a "module" is explained
---
 lib/types.nix | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/lib/types.nix b/lib/types.nix
index 5226609822f1..a0a16ed82c38 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -911,6 +911,41 @@ rec {
         in mergedOption.type;
     };
 
+    /**
+
+    Like `types.submodule`, but more flexible and with better defaults.
+    It has parameters
+
+    -   *`modules`* A list of modules to use by default for this
+        submodule type. This gets combined with all option definitions
+        to build the final list of modules that will be included.
+
+    -   *`specialArgs`* An attribute set of extra arguments to be passed
+        to the module functions. The option `_module.args` should be
+        used instead for most arguments since it allows overriding.
+        *`specialArgs`* should only be used for arguments that can't go
+        through the module fixed-point, because of infinite recursion or
+        other problems. An example is overriding the `lib` argument,
+        because `lib` itself is used to define `_module.args`, which
+        makes using `_module.args` to define it impossible.
+
+    -   *`shorthandOnlyDefinesConfig`* Whether definitions of this type
+        should default to the `config` section of a module (see
+        [Example: Structure of NixOS Modules](#ex-module-syntax))
+        if it is an attribute set. Enabling this only has a benefit
+        when the submodule defines an option named `config` or `options`.
+        In such a case it would allow the option to be set with
+        `the-submodule.config = "value"` instead of requiring
+        `the-submodule.config.config = "value"`. This is because
+        only when modules *don't* set the `config` or `options`
+        keys, all keys are interpreted as option definitions in the
+        `config` section. Enabling this option implicitly puts all
+        attributes in the `config` section.
+
+        With this option enabled, defining a non-`config` section
+        requires using a function:
+        `the-submodule = { ... }: { options = { ... }; }`.
+    */
     submoduleWith =
       { modules
       , specialArgs ? {}
-- 
2.47.2

If another format is desired, please say so. Iā€™m going through https://noogle.dev and trying to document whatever I can (within reason).

1 Like