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