From ca81a89839176c2e0d0b0fb01a931a4a65404fa6 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 28 Jan 2024 00:30:36 +0100
Subject: [PATCH 01/23] lib.types.attrTag: init

---
 lib/tests/modules.sh                          | 11 ++++
 lib/tests/modules/types-attrTag.nix           | 64 +++++++++++++++++++
 lib/types.nix                                 | 37 +++++++++++
 .../development/option-types.section.md       | 10 +++
 4 files changed, 122 insertions(+)
 create mode 100644 lib/tests/modules/types-attrTag.nix

diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh
index b3bbdf9485ac..318efc4c3d05 100755
--- a/lib/tests/modules.sh
+++ b/lib/tests/modules.sh
@@ -103,6 +103,17 @@ checkConfigError 'The option .sub.wrong2. does not exist. Definition values:' co
 checkConfigError '.*This can happen if you e.g. declared your options in .types.submodule.' config.sub ./error-mkOption-in-submodule-config.nix
 checkConfigError '.*A definition for option .bad. is not of type .non-empty .list of .submodule...\.' config.bad ./error-nonEmptyListOf-submodule.nix
 
+# types.attrTag
+checkConfigOutput '^true$' config.okChecks ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.syntaxError. is not of type .attribute-tagged union of left, right' config.intStrings.syntaxError ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.syntaxError2. is not of type .attribute-tagged union of left, right' config.intStrings.syntaxError2 ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.syntaxError3. is not of type .attribute-tagged union of left, right' config.intStrings.syntaxError3 ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.syntaxError4. is not of type .attribute-tagged union of left, right' config.intStrings.syntaxError4 ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.mergeError. is not of type .attribute-tagged union of left, right' config.intStrings.mergeError ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.badTagError. is not of type .attribute-tagged union of left, right' config.intStrings.badTagError ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.badTagTypeError\.left. is not of type .signed integer.' config.intStrings.badTagTypeError.left ./types-attrTag.nix
+checkConfigError 'A definition for option .nested\.right\.left. is not of type .signed integer.' config.nested.right.left ./types-attrTag.nix
+
 # types.pathInStore
 checkConfigOutput '".*/store/0lz9p8xhf89kb1c1kk6jxrzskaiygnlh-bash-5.2-p15.drv"' config.pathInStore.ok1 ./types.nix
 checkConfigOutput '".*/store/0fb3ykw9r5hpayd05sr0cizwadzq1d8q-bash-5.2-p15"' config.pathInStore.ok2 ./types.nix
diff --git a/lib/tests/modules/types-attrTag.nix b/lib/tests/modules/types-attrTag.nix
new file mode 100644
index 000000000000..08854ca73f56
--- /dev/null
+++ b/lib/tests/modules/types-attrTag.nix
@@ -0,0 +1,64 @@
+{ lib, config, ... }:
+let
+  inherit (lib) mkOption types;
+  forceDeep = x: builtins.deepSeq x x;
+in
+{
+  options = {
+    intStrings = mkOption {
+      type = types.attrsOf
+        (types.attrTag {
+          left = types.int;
+          right = types.str;
+        });
+    };
+    nested = mkOption {
+      type = types.attrTag {
+        left = types.int;
+        right = types.attrTag {
+          left = types.int;
+          right = types.str;
+        };
+      };
+    };
+    merged = mkOption {
+      type = types.attrsOf (
+        types.attrTag {
+          yay = types.int;
+        }
+      );
+    };
+    okChecks = mkOption {};
+  };
+  imports = [
+    {
+      options.merged = mkOption {
+        type = types.attrsOf (
+          types.attrTag {
+            nay = types.bool;
+          }
+        );
+      };
+    }
+  ];
+  config = {
+    intStrings.syntaxError = 1;
+    intStrings.syntaxError2 = {};
+    intStrings.syntaxError3 = { a = true; b = true; };
+    intStrings.syntaxError4 = lib.mkMerge [ { a = true; } { b = true; } ];
+    intStrings.mergeError = lib.mkMerge [ { int = throw "do not eval"; } { string = throw "do not eval"; } ];
+    intStrings.badTagError.rite = throw "do not eval";
+    intStrings.badTagTypeError.left = "bad";
+    intStrings.numberOne.left = 1;
+    intStrings.hello.right = "hello world";
+    nested.right.left = "not a number";
+    merged.negative.nay = false;
+    merged.positive.yay = 100;
+    okChecks =
+      assert config.intStrings.hello.right == "hello world";
+      assert config.intStrings.numberOne.left == 1;
+      assert config.merged.negative.nay == false;
+      assert config.merged.positive.yay == 100;
+      true;
+  };
+}
diff --git a/lib/types.nix b/lib/types.nix
index 12bf18633e3a..59577856f4e1 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -614,6 +614,43 @@ rec {
       nestedTypes.elemType = elemType;
     };
 
+    attrTag = tags: attrTagWith { inherit tags; };
+
+    attrTagWith = { tags }:
+      let
+        choicesStr = concatMapStringsSep ", " lib.strings.escapeNixIdentifier (attrNames tags);
+      in
+      mkOptionType {
+        name = "attrTag";
+        description = "attribute-tagged union of ${choicesStr}";
+        getSubModules = null;
+        substSubModules = m: attrTagWith { tags = mapAttrs (n: v: v.substSubModules m) tags; };
+        check = v: isAttrs v && length (attrNames v) == 1 && tags?${head (attrNames v)};
+        merge = loc: defs:
+          let
+            choice = head (attrNames (head defs).value);
+            checkedValueDefs = map
+              (def:
+                assert (length (attrNames def.value)) == 1;
+                if (head (attrNames def.value)) != choice
+                then throw "The option `${showOption loc}` is defined both as `${choice}` and `${head (attrNames def.value)}`, in ${showFiles (getFiles defs)}."
+                else { inherit (def) file; value = def.value.${choice}; })
+              defs;
+          in
+            if tags?${choice}
+            then
+              { ${choice} =
+                  (mergeDefinitions
+                    (loc ++ [choice])
+                    tags.${choice}
+                    checkedValueDefs
+                  ).mergedValue;
+              }
+            else throw "The option `${showOption loc}` is defined as ${lib.strings.escapeNixIdentifier choice}, but ${lib.strings.escapeNixIdentifier choice} is not among the valid choices (${choicesStr}). Value ${choice} was defined in ${showFiles (getFiles defs)}.";
+        nestedTypes = tags;
+        functor = (defaultFunctor "attrTagWith") // { payload = { inherit tags; }; binOp = a: b: { tags = a.tags // b.tags; }; };
+      };
+
     uniq = unique { message = ""; };
 
     unique = { message }: type: mkOptionType rec {
diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md
index 04edf99e70b0..1dfb4354f887 100644
--- a/nixos/doc/manual/development/option-types.section.md
+++ b/nixos/doc/manual/development/option-types.section.md
@@ -334,6 +334,16 @@ Composed types are types that take a type as parameter. `listOf
     the line `The option <option path> is defined multiple times.` and before
     a list of definition locations.
 
+`types.attrTag` *`{ attr1 = t1; attr2 = t2; ... }`*
+
+:   An attribute set containing one attribute, whose name must be picked from
+    the attribute set (`attr1`, etc) and whose value must be of the accompanying
+    type.
+
+    This is one possible representation of what may be called a _tagged union_ or _sum type_.
+    `attrTag` can be thought of as an extension of *`enum`* where the permissible items
+    are attribute names, and each item is paired with a value of a specific type.
+
 `types.either` *`t1 t2`*
 
 :   Type *`t1`* or type *`t2`*, e.g. `with types; either int str`.

From 0feea2dbd2eb76ffa1ba1db7d291bcb1a274d529 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 28 Jan 2024 16:23:21 +0100
Subject: [PATCH 02/23] doc/option-types: Write about sum and union types

---
 .../development/option-types.section.md       | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md
index 1dfb4354f887..e656a1002f5a 100644
--- a/nixos/doc/manual/development/option-types.section.md
+++ b/nixos/doc/manual/development/option-types.section.md
@@ -42,6 +42,9 @@ merging is handled.
 :   One element of the list *`l`*, e.g. `types.enum [ "left" "right" ]`.
     Multiple definitions cannot be merged.
 
+    If you want to pair these values with more information, possibly of
+    distinct types, consider using a [sum type](#sec-option-types-sums).
+
 `types.anything`
 
 :   A type that accepts any value and recursively merges attribute sets
@@ -279,6 +282,24 @@ Submodules are detailed in [Submodule](#section-option-types-submodule).
     more convenient and discoverable than expecting the module user to
     type-merge with the `attrsOf submodule` option.
 
+## Union types {#sec-option-types-unions}
+
+A union of types is a type such that a value is valid when it is valid for at least one of those types.
+
+If some values are instances of more than one of the types, it is not possible to distinguish which type they are meant to be instances of. If that's needed, consider using a [sum type](#sec-option-types-sums).
+
+
+
+## Sum types {#sec-option-types-sums}
+
+A sum type can be thought of, conceptually, as a *`types.enum`* where each valid item is paired with a type, through some value syntax.
+Nix does not have a built-in syntax for this pairing of a label and a type or value, so sum types may be represented in multiple ways.
+
+If the built-in Nix value types provide enough distinction, you simplify your syntax with a [union type](#sec-option-types-unions) instead.
+
+
+
+
 ## Composed types {#sec-option-types-composed}
 
 Composed types are types that take a type as parameter. `listOf

From 2ceb5558f95f978f1df70a2873b0fdf6ee87ff9f Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 28 Jan 2024 16:24:27 +0100
Subject: [PATCH 03/23] doc/option-types: Move either and oneOf to Union types

---
 .../development/option-types.section.md       | 21 +++++++++----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md
index e656a1002f5a..8dde0aba4b2b 100644
--- a/nixos/doc/manual/development/option-types.section.md
+++ b/nixos/doc/manual/development/option-types.section.md
@@ -288,6 +288,16 @@ A union of types is a type such that a value is valid when it is valid for at le
 
 If some values are instances of more than one of the types, it is not possible to distinguish which type they are meant to be instances of. If that's needed, consider using a [sum type](#sec-option-types-sums).
 
+`types.either` *`t1 t2`*
+
+:   Type *`t1`* or type *`t2`*, e.g. `with types; either int str`.
+    Multiple definitions cannot be merged.
+
+`types.oneOf` \[ *`t1 t2`* ... \]
+
+:   Type *`t1`* or type *`t2`* and so forth, e.g.
+    `with types; oneOf [ int str bool ]`. Multiple definitions cannot be
+    merged.
 
 
 ## Sum types {#sec-option-types-sums}
@@ -365,17 +375,6 @@ Composed types are types that take a type as parameter. `listOf
     `attrTag` can be thought of as an extension of *`enum`* where the permissible items
     are attribute names, and each item is paired with a value of a specific type.
 
-`types.either` *`t1 t2`*
-
-:   Type *`t1`* or type *`t2`*, e.g. `with types; either int str`.
-    Multiple definitions cannot be merged.
-
-`types.oneOf` \[ *`t1 t2`* ... \]
-
-:   Type *`t1`* or type *`t2`* and so forth, e.g.
-    `with types; oneOf [ int str bool ]`. Multiple definitions cannot be
-    merged.
-
 `types.coercedTo` *`from f to`*
 
 :   Type *`to`* or type *`from`* which will be coerced to type *`to`* using

From 1ad30772ea4feca0b597446e102fb323c89c41a0 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 28 Jan 2024 16:24:59 +0100
Subject: [PATCH 04/23] doc/option-types: Move attrTag to Sum types, remove
 redundant paragraph

---
 .../doc/manual/development/option-types.section.md | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md
index 8dde0aba4b2b..f8b25d90088d 100644
--- a/nixos/doc/manual/development/option-types.section.md
+++ b/nixos/doc/manual/development/option-types.section.md
@@ -307,7 +307,11 @@ Nix does not have a built-in syntax for this pairing of a label and a type or va
 
 If the built-in Nix value types provide enough distinction, you simplify your syntax with a [union type](#sec-option-types-unions) instead.
 
+`types.attrTag` *`{ attr1 = t1; attr2 = t2; ... }`*
 
+:   An attribute set containing one attribute, whose name must be picked from
+    the attribute set (`attr1`, etc) and whose value must be of the accompanying
+    type.
 
 
 ## Composed types {#sec-option-types-composed}
@@ -365,16 +369,6 @@ Composed types are types that take a type as parameter. `listOf
     the line `The option <option path> is defined multiple times.` and before
     a list of definition locations.
 
-`types.attrTag` *`{ attr1 = t1; attr2 = t2; ... }`*
-
-:   An attribute set containing one attribute, whose name must be picked from
-    the attribute set (`attr1`, etc) and whose value must be of the accompanying
-    type.
-
-    This is one possible representation of what may be called a _tagged union_ or _sum type_.
-    `attrTag` can be thought of as an extension of *`enum`* where the permissible items
-    are attribute names, and each item is paired with a value of a specific type.
-
 `types.coercedTo` *`from f to`*
 
 :   Type *`to`* or type *`from`* which will be coerced to type *`to`* using

From 6949bc21ce1de068bc1b21e273d15620c0e5770e Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 28 Jan 2024 16:25:36 +0100
Subject: [PATCH 05/23] doc/option-types: Move nullOr to Union types

---
 nixos/doc/manual/development/option-types.section.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md
index f8b25d90088d..cf9422291d9f 100644
--- a/nixos/doc/manual/development/option-types.section.md
+++ b/nixos/doc/manual/development/option-types.section.md
@@ -299,6 +299,11 @@ If some values are instances of more than one of the types, it is not possible t
     `with types; oneOf [ int str bool ]`. Multiple definitions cannot be
     merged.
 
+`types.nullOr` *`t`*
+
+:   `null` or type *`t`*. Multiple definitions are merged according to
+    type *`t`*.
+
 
 ## Sum types {#sec-option-types-sums}
 
@@ -353,11 +358,6 @@ Composed types are types that take a type as parameter. `listOf
     returned instead for the same `mkIf false` definition.
     :::
 
-`types.nullOr` *`t`*
-
-:   `null` or type *`t`*. Multiple definitions are merged according to
-    type *`t`*.
-
 `types.uniq` *`t`*
 
 :   Ensures that type *`t`* cannot be merged. It is used to ensure option

From 5b49672af44875df0449f7ff1b55965eedeec1da Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 29 Jan 2024 07:10:14 +0100
Subject: [PATCH 06/23] lib.types.attrTag: Support module docs

---
 lib/tests/modules/docs.nix          | 41 +++++++++++++++++++++++++++++
 lib/tests/modules/types-attrTag.nix | 19 +++++++++++++
 lib/types.nix                       |  6 ++++-
 3 files changed, 65 insertions(+), 1 deletion(-)
 create mode 100644 lib/tests/modules/docs.nix

diff --git a/lib/tests/modules/docs.nix b/lib/tests/modules/docs.nix
new file mode 100644
index 000000000000..225aa7eac1de
--- /dev/null
+++ b/lib/tests/modules/docs.nix
@@ -0,0 +1,41 @@
+/*
+  A basic documentation generating module.
+  Declares and defines a `docs` option, suitable for making assertions about
+  the extraction "phase" of documentation generation.
+ */
+{ lib, options, ... }:
+
+let
+  inherit (lib)
+    head
+    length
+    mkOption
+    types
+  ;
+
+  traceListSeq = l: v: lib.foldl' (a: b: lib.traceSeq b a) v l;
+
+in
+
+{
+  options.docs = mkOption {
+    type = types.lazyAttrsOf types.raw;
+    description = ''
+      All options to be rendered, without any visibility filtering applied.
+    '';
+  };
+  config.docs =
+    lib.zipAttrsWith
+      (name: values:
+        if length values > 1 then
+          traceListSeq values
+          abort "Multiple options with the same name: ${name}"
+        else
+          assert length values == 1;
+          head values
+      )
+      (map
+        (opt: { ${opt.name} = opt; })
+        (lib.optionAttrSetToDocList options)
+      );
+}
diff --git a/lib/tests/modules/types-attrTag.nix b/lib/tests/modules/types-attrTag.nix
index 08854ca73f56..1a0a0f7ba01e 100644
--- a/lib/tests/modules/types-attrTag.nix
+++ b/lib/tests/modules/types-attrTag.nix
@@ -28,9 +28,24 @@ in
         }
       );
     };
+    submodules = mkOption {
+      type = types.attrsOf (
+        types.attrTag {
+          foo = types.submodule {
+            options = {
+              bar = mkOption {
+                type = types.int;
+              };
+            };
+          };
+          qux = types.str;
+        }
+      );
+    };
     okChecks = mkOption {};
   };
   imports = [
+    ./docs.nix
     {
       options.merged = mkOption {
         type = types.attrsOf (
@@ -59,6 +74,10 @@ in
       assert config.intStrings.numberOne.left == 1;
       assert config.merged.negative.nay == false;
       assert config.merged.positive.yay == 100;
+      # assert lib.foldl' (a: b: builtins.trace b a) true (lib.attrNames config.docs);
+      assert config.docs."submodules.<name>.foo.bar".type == "signed integer";
+      # It's not an option, so we can't render it as such. Something would be nice though.
+      assert ! (config.docs?"submodules.<name>.qux");
       true;
   };
 }
diff --git a/lib/types.nix b/lib/types.nix
index 59577856f4e1..5286ce76862e 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -623,7 +623,11 @@ rec {
       mkOptionType {
         name = "attrTag";
         description = "attribute-tagged union of ${choicesStr}";
-        getSubModules = null;
+        getSubOptions = prefix:
+          mapAttrs
+            (tagName: tagType:
+              tagType.getSubOptions (prefix ++ [ tagName ]))
+            tags;
         substSubModules = m: attrTagWith { tags = mapAttrs (n: v: v.substSubModules m) tags; };
         check = v: isAttrs v && length (attrNames v) == 1 && tags?${head (attrNames v)};
         merge = loc: defs:

From 42d3b54f0dab73e42e6643e0a3c0ee140b6c8112 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 29 Jan 2024 07:56:35 +0100
Subject: [PATCH 07/23] lib.types.attrTag: Take options instead of types

---
 lib/tests/modules/types-attrTag.nix | 49 ++++++++++++++++++++---------
 lib/types.nix                       | 27 ++++++++++++----
 2 files changed, 55 insertions(+), 21 deletions(-)

diff --git a/lib/tests/modules/types-attrTag.nix b/lib/tests/modules/types-attrTag.nix
index 1a0a0f7ba01e..b105d01512dc 100644
--- a/lib/tests/modules/types-attrTag.nix
+++ b/lib/tests/modules/types-attrTag.nix
@@ -8,37 +8,55 @@ in
     intStrings = mkOption {
       type = types.attrsOf
         (types.attrTag {
-          left = types.int;
-          right = types.str;
+          left = mkOption {
+            type = types.int;
+          };
+          right = mkOption {
+            type = types.str;
+          };
         });
     };
     nested = mkOption {
       type = types.attrTag {
-        left = types.int;
-        right = types.attrTag {
-          left = types.int;
-          right = types.str;
+        left = mkOption {
+          type = types.int;
+        };
+        right = mkOption {
+          type = types.attrTag {
+            left = mkOption {
+              type = types.int;
+            };
+            right = mkOption {
+              type = types.str;
+            };
+          };
         };
       };
     };
     merged = mkOption {
       type = types.attrsOf (
         types.attrTag {
-          yay = types.int;
+          yay = mkOption {
+            type = types.int;
+          };
         }
       );
     };
     submodules = mkOption {
       type = types.attrsOf (
         types.attrTag {
-          foo = types.submodule {
-            options = {
-              bar = mkOption {
-                type = types.int;
+          foo = mkOption {
+            type = types.submodule {
+              options = {
+                bar = mkOption {
+                  type = types.int;
+                };
               };
             };
           };
-          qux = types.str;
+          qux = mkOption {
+            type = types.str;
+          };
         }
       );
     };
@@ -50,7 +68,9 @@ in
       options.merged = mkOption {
         type = types.attrsOf (
           types.attrTag {
-            nay = types.bool;
+            nay = mkOption {
+              type = types.bool;
+            };
           }
         );
       };
@@ -76,8 +96,7 @@ in
       assert config.merged.positive.yay == 100;
       # assert lib.foldl' (a: b: builtins.trace b a) true (lib.attrNames config.docs);
       assert config.docs."submodules.<name>.foo.bar".type == "signed integer";
-      # It's not an option, so we can't render it as such. Something would be nice though.
-      assert ! (config.docs?"submodules.<name>.qux");
+      assert config.docs."submodules.<name>.qux".type == "string";
       true;
   };
 }
diff --git a/lib/types.nix b/lib/types.nix
index 5286ce76862e..2c6845178852 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -65,6 +65,11 @@ let
     fixupOptionType
     mergeOptionDecls
     ;
+
+  inAttrPosSuffix = v: name:
+    let pos = builtins.unsafeGetAttrPos name v; in
+    if pos == null then "" else " at ${pos.file}:${toString pos.line}:${toString pos.column}";
+
   outer_types =
 rec {
   __attrsFailEvaluation = true;
@@ -616,8 +621,16 @@ rec {
 
     attrTag = tags: attrTagWith { inherit tags; };
 
-    attrTagWith = { tags }:
+    attrTagWith = args@{ tags }:
       let
+        tags =
+          mapAttrs
+            (n: opt:
+              builtins.addErrorContext "while checking that attrTag tag ${lib.strings.escapeNixIdentifier n} is an option with a type${inAttrPosSuffix args.tags n}" (
+                assert opt._type == "option";
+                opt
+              ))
+            args.tags;
         choicesStr = concatMapStringsSep ", " lib.strings.escapeNixIdentifier (attrNames tags);
       in
       mkOptionType {
@@ -625,10 +638,12 @@ rec {
         description = "attribute-tagged union of ${choicesStr}";
         getSubOptions = prefix:
           mapAttrs
-            (tagName: tagType:
-              tagType.getSubOptions (prefix ++ [ tagName ]))
+            (tagName: tagOption: {
+              "${lib.showOption prefix}" =
+                tagOption // { loc = prefix ++ [ tagName ]; };
+            })
             tags;
-        substSubModules = m: attrTagWith { tags = mapAttrs (n: v: v.substSubModules m) tags; };
+        substSubModules = m: attrTagWith { tags = mapAttrs (n: opt: opt // { type = (opt.type or types.unspecified).substSubModules m; }) tags; };
         check = v: isAttrs v && length (attrNames v) == 1 && tags?${head (attrNames v)};
         merge = loc: defs:
           let
@@ -644,11 +659,11 @@ rec {
             if tags?${choice}
             then
               { ${choice} =
-                  (mergeDefinitions
+                  (lib.modules.evalOptionValue
                     (loc ++ [choice])
                     tags.${choice}
                     checkedValueDefs
-                  ).mergedValue;
+                  ).value;
               }
             else throw "The option `${showOption loc}` is defined as ${lib.strings.escapeNixIdentifier choice}, but ${lib.strings.escapeNixIdentifier choice} is not among the valid choices (${choicesStr}). Value ${choice} was defined in ${showFiles (getFiles defs)}.";
         nestedTypes = tags;

From 0bc978322178fe6dbe91fe1477d275e1005d5e77 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 29 Jan 2024 08:14:36 +0100
Subject: [PATCH 08/23] lib.types.attrTag: Support type merging

---
 lib/tests/modules/types-attrTag.nix | 10 ++++++++++
 lib/types.nix                       | 23 ++++++++++++++++++++++-
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/lib/tests/modules/types-attrTag.nix b/lib/tests/modules/types-attrTag.nix
index b105d01512dc..b8b1dff21e19 100644
--- a/lib/tests/modules/types-attrTag.nix
+++ b/lib/tests/modules/types-attrTag.nix
@@ -39,6 +39,9 @@ in
           yay = mkOption {
             type = types.int;
           };
+          extensible = mkOption {
+            type = types.enum [ "foo" ];
+          };
         }
       );
     };
@@ -71,6 +74,9 @@ in
             nay = mkOption {
               type = types.bool;
             };
+            extensible = mkOption {
+              type = types.enum [ "bar" ];
+            };
           }
         );
       };
@@ -89,11 +95,15 @@ in
     nested.right.left = "not a number";
     merged.negative.nay = false;
     merged.positive.yay = 100;
+    merged.extensi-foo.extensible = "foo";
+    merged.extensi-bar.extensible = "bar";
     okChecks =
       assert config.intStrings.hello.right == "hello world";
       assert config.intStrings.numberOne.left == 1;
       assert config.merged.negative.nay == false;
       assert config.merged.positive.yay == 100;
+      assert config.merged.extensi-foo.extensible == "foo";
+      assert config.merged.extensi-bar.extensible == "bar";
       # assert lib.foldl' (a: b: builtins.trace b a) true (lib.attrNames config.docs);
       assert config.docs."submodules.<name>.foo.bar".type == "signed integer";
       assert config.docs."submodules.<name>.qux".type == "string";
diff --git a/lib/types.nix b/lib/types.nix
index 2c6845178852..2f0b10fe9658 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -667,7 +667,28 @@ rec {
               }
             else throw "The option `${showOption loc}` is defined as ${lib.strings.escapeNixIdentifier choice}, but ${lib.strings.escapeNixIdentifier choice} is not among the valid choices (${choicesStr}). Value ${choice} was defined in ${showFiles (getFiles defs)}.";
         nestedTypes = tags;
-        functor = (defaultFunctor "attrTagWith") // { payload = { inherit tags; }; binOp = a: b: { tags = a.tags // b.tags; }; };
+        functor = (defaultFunctor "attrTagWith") // {
+          payload = { inherit tags; };
+          binOp =
+            let
+              # Add metadata in the format that submodules work with
+              wrapOptionDecl =
+                option: { options = option; _file = "<attrTag {...}>"; pos = null; };
+            in
+            a: b: {
+              tags = a.tags // b.tags //
+                mapAttrs
+                  (tagName: bOpt:
+                    lib.mergeOptionDecls
+                      # FIXME: loc is not accurate; should include prefix
+                      #        Fortunately, it's only used for error messages, where a "relative" location is kinda ok.
+                      #        It is also returned though, but use of the attribute seems rare?
+                      [tagName]
+                      [ (wrapOptionDecl a.tags.${tagName}) (wrapOptionDecl bOpt) ]
+                  )
+                  (builtins.intersectAttrs a.tags b.tags);
+          };
+        };
       };
 
     uniq = unique { message = ""; };

From e090bb55f0599afcdfda63f3e7e27bfd1cfd0691 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 29 Jan 2024 08:17:46 +0100
Subject: [PATCH 09/23] lib/types.nix: Fix getSubOptions doc

This comment was added in 73f32d03758a5, when it was already
supposed to be an attrset.
---
 lib/types.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/types.nix b/lib/types.nix
index 2f0b10fe9658..43c4b72ad350 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -157,7 +157,7 @@ rec {
       # If it doesn't, this should be {}
       # This may be used when a value is required for `mkIf false`. This allows the extra laziness in e.g. `lazyAttrsOf`.
       emptyValue ? {}
-    , # Return a flat list of sub-options.  Used to generate
+    , # Return a flat attrset of sub-options.  Used to generate
       # documentation.
       getSubOptions ? prefix: {}
     , # List of modules if any, or null if none.

From 4c7d990badc4a6ef9adcffb0790902de94faa51e Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 29 Jan 2024 08:54:02 +0100
Subject: [PATCH 10/23] lib.types.attrTag: Provide declarations, definitions

---
 lib/tests/modules/types-attrTag.nix |  1 +
 lib/types.nix                       | 21 +++++++++++++++++++--
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/lib/tests/modules/types-attrTag.nix b/lib/tests/modules/types-attrTag.nix
index b8b1dff21e19..43d71b3ae6ad 100644
--- a/lib/tests/modules/types-attrTag.nix
+++ b/lib/tests/modules/types-attrTag.nix
@@ -107,6 +107,7 @@ in
       # assert lib.foldl' (a: b: builtins.trace b a) true (lib.attrNames config.docs);
       assert config.docs."submodules.<name>.foo.bar".type == "signed integer";
       assert config.docs."submodules.<name>.qux".type == "string";
+      assert lib.length config.docs."merged.<name>.extensible".declarations == 2;
       true;
   };
 }
diff --git a/lib/types.nix b/lib/types.nix
index 43c4b72ad350..02532a991e98 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -628,7 +628,16 @@ rec {
             (n: opt:
               builtins.addErrorContext "while checking that attrTag tag ${lib.strings.escapeNixIdentifier n} is an option with a type${inAttrPosSuffix args.tags n}" (
                 assert opt._type == "option";
-                opt
+                opt // {
+                  declarations = opt.declarations or (
+                    let pos = builtins.unsafeGetAttrPos n args.tags;
+                    in if pos == null then [] else [ pos.file ]
+                  );
+                  declarationPositions = opt.declarationPositions or (
+                    let pos = builtins.unsafeGetAttrPos n args.tags;
+                    in if pos == null then [] else [ pos ]
+                  );
+                }
               ))
             args.tags;
         choicesStr = concatMapStringsSep ", " lib.strings.escapeNixIdentifier (attrNames tags);
@@ -640,7 +649,10 @@ rec {
           mapAttrs
             (tagName: tagOption: {
               "${lib.showOption prefix}" =
-                tagOption // { loc = prefix ++ [ tagName ]; };
+                tagOption // {
+                  loc = prefix ++ [ tagName ];
+                  definitions = [];
+                };
             })
             tags;
         substSubModules = m: attrTagWith { tags = mapAttrs (n: opt: opt // { type = (opt.type or types.unspecified).substSubModules m; }) tags; };
@@ -685,6 +697,11 @@ rec {
                       #        It is also returned though, but use of the attribute seems rare?
                       [tagName]
                       [ (wrapOptionDecl a.tags.${tagName}) (wrapOptionDecl bOpt) ]
+                    // {
+                      # mergeOptionDecls is not idempotent in these attrs:
+                      declarations = a.tags.${tagName}.declarations ++ bOpt.declarations;
+                      declarationPositions = a.tags.${tagName}.declarations ++ bOpt.declarations;
+                    }
                   )
                   (builtins.intersectAttrs a.tags b.tags);
           };

From 2e1d470569f5a2a1a9154efdf6f21d12c659631d Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 29 Jan 2024 08:58:33 +0100
Subject: [PATCH 11/23] lib.modules.evalOptionValue: Undeprecate for lib.types

lib.types.attrTag needs it.
---
 lib/default.nix | 3 ++-
 lib/modules.nix | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/lib/default.nix b/lib/default.nix
index a17307be6e07..c33a4d0eb075 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -128,7 +128,7 @@ let
       canCleanSource pathIsGitRepo;
     inherit (self.modules) evalModules setDefaultModuleLocation
       unifyModuleSyntax applyModuleArgsIfFunction mergeModules
-      mergeModules' mergeOptionDecls evalOptionValue mergeDefinitions
+      mergeModules' mergeOptionDecls mergeDefinitions
       pushDownProperties dischargeProperties filterOverrides
       sortProperties fixupOptionType mkIf mkAssert mkMerge mkOverride
       mkOptionDefault mkDefault mkImageMediaOverride mkForce mkVMOverride
@@ -138,6 +138,7 @@ let
       mkMergedOptionModule mkChangedOptionModule
       mkAliasOptionModule mkDerivedConfig doRename
       mkAliasOptionModuleMD;
+    evalOptionValue = lib.warn "External use of `lib.evalOptionValue` is deprecated. If your use case isn't covered by non-deprecated functions, we'd like to know more and perhaps support your use case well, instead of providing access to these low level functions. In this case please open an issue in https://github.com/nixos/nixpkgs/issues/." self.modules.evalOptionValue;
     inherit (self.options) isOption mkEnableOption mkSinkUndeclaredOptions
       mergeDefaultOption mergeOneOption mergeEqualOption mergeUniqueOption
       getValues getFiles
diff --git a/lib/modules.nix b/lib/modules.nix
index 0c484fa684aa..93f892bd28c1 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -1307,7 +1307,6 @@ let
       inherit
         applyModuleArgsIfFunction
         dischargeProperties
-        evalOptionValue
         mergeModules
         mergeModules'
         pushDownProperties
@@ -1328,6 +1327,7 @@ private //
     defaultPriority
     doRename
     evalModules
+    evalOptionValue  # for use by lib.types
     filterOverrides
     filterOverrides'
     fixMergeModules

From 475a55b2f0433d5324817ab9882102db65e3733e Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 29 Jan 2024 09:03:08 +0100
Subject: [PATCH 12/23] lib.types.attrTag: Remove tags from description

You can find them in the sub-options now.
---
 lib/tests/modules.sh | 12 ++++++------
 lib/types.nix        |  3 ++-
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh
index 318efc4c3d05..b1994ff31638 100755
--- a/lib/tests/modules.sh
+++ b/lib/tests/modules.sh
@@ -105,12 +105,12 @@ checkConfigError '.*A definition for option .bad. is not of type .non-empty .lis
 
 # types.attrTag
 checkConfigOutput '^true$' config.okChecks ./types-attrTag.nix
-checkConfigError 'A definition for option .intStrings\.syntaxError. is not of type .attribute-tagged union of left, right' config.intStrings.syntaxError ./types-attrTag.nix
-checkConfigError 'A definition for option .intStrings\.syntaxError2. is not of type .attribute-tagged union of left, right' config.intStrings.syntaxError2 ./types-attrTag.nix
-checkConfigError 'A definition for option .intStrings\.syntaxError3. is not of type .attribute-tagged union of left, right' config.intStrings.syntaxError3 ./types-attrTag.nix
-checkConfigError 'A definition for option .intStrings\.syntaxError4. is not of type .attribute-tagged union of left, right' config.intStrings.syntaxError4 ./types-attrTag.nix
-checkConfigError 'A definition for option .intStrings\.mergeError. is not of type .attribute-tagged union of left, right' config.intStrings.mergeError ./types-attrTag.nix
-checkConfigError 'A definition for option .intStrings\.badTagError. is not of type .attribute-tagged union of left, right' config.intStrings.badTagError ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.syntaxError. is not of type .attribute-tagged union' config.intStrings.syntaxError ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.syntaxError2. is not of type .attribute-tagged union' config.intStrings.syntaxError2 ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.syntaxError3. is not of type .attribute-tagged union' config.intStrings.syntaxError3 ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.syntaxError4. is not of type .attribute-tagged union' config.intStrings.syntaxError4 ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.mergeError. is not of type .attribute-tagged union' config.intStrings.mergeError ./types-attrTag.nix
+checkConfigError 'A definition for option .intStrings\.badTagError. is not of type .attribute-tagged union' config.intStrings.badTagError ./types-attrTag.nix
 checkConfigError 'A definition for option .intStrings\.badTagTypeError\.left. is not of type .signed integer.' config.intStrings.badTagTypeError.left ./types-attrTag.nix
 checkConfigError 'A definition for option .nested\.right\.left. is not of type .signed integer.' config.nested.right.left ./types-attrTag.nix
 
diff --git a/lib/types.nix b/lib/types.nix
index 02532a991e98..7fe7b5d92eac 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -644,7 +644,8 @@ rec {
       in
       mkOptionType {
         name = "attrTag";
-        description = "attribute-tagged union of ${choicesStr}";
+        description = "attribute-tagged union";
+        descriptionClass = "noun";
         getSubOptions = prefix:
           mapAttrs
             (tagName: tagOption: {

From c0f54d3dea047729d754dc2419ecfe8ab2cce23b Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 29 Jan 2024 09:14:18 +0100
Subject: [PATCH 13/23] doc/option-types: Add attrTag example

---
 .../development/option-types.section.md       | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md
index cf9422291d9f..6bf579ff7802 100644
--- a/nixos/doc/manual/development/option-types.section.md
+++ b/nixos/doc/manual/development/option-types.section.md
@@ -318,6 +318,30 @@ If the built-in Nix value types provide enough distinction, you simplify your sy
     the attribute set (`attr1`, etc) and whose value must be of the accompanying
     type.
 
+    This type appears in the documentation as _attribute-tagged union_.
+
+    Example:
+
+    ```nix
+    types.attrTag {
+      bounce = mkOption {
+        description = "Send back a packet explaining why it wasn't forwarded.";
+        type = submodule {
+          options.errorMessage = mkOption { … };
+        };
+      };
+      forward = mkOption {
+        description = "Forward the packet.";
+        type = submodule {
+          options.destination = mkOption { … };
+        };
+      };
+      ignore = mkOption {
+        description = "Drop the packet without sending anything back.";
+        type = submodule {};
+      };
+    }
+    ```
 
 ## Composed types {#sec-option-types-composed}
 

From fa8b46adf467eec196da8808d62c9e03d69caa37 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 4 Feb 2024 17:17:47 +0100
Subject: [PATCH 14/23] doc/option-types: Make attrTag example self-contained

... well, except for the ellipses, which hide unnecessary descriptions,
which you should write!
---
 .../development/option-types.section.md       | 46 +++++++++++++------
 1 file changed, 32 insertions(+), 14 deletions(-)

diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md
index 6bf579ff7802..0b348094bfcf 100644
--- a/nixos/doc/manual/development/option-types.section.md
+++ b/nixos/doc/manual/development/option-types.section.md
@@ -323,22 +323,40 @@ If the built-in Nix value types provide enough distinction, you simplify your sy
     Example:
 
     ```nix
-    types.attrTag {
-      bounce = mkOption {
-        description = "Send back a packet explaining why it wasn't forwarded.";
-        type = submodule {
-          options.errorMessage = mkOption { … };
-        };
+    { lib, ... }:
+    let inherit (lib) type mkOption;
+    in {
+      options.toyRouter.rules = mkOption {
+        description = ''
+          Rules for a fictional packet routing service.
+        '';
+        type = types.attrsOf (
+          types.attrTag {
+            bounce = mkOption {
+              description = "Send back a packet explaining why it wasn't forwarded.";
+              type = types.submodule {
+                options.errorMessage = mkOption { … };
+              };
+            };
+            forward = mkOption {
+              description = "Forward the packet.";
+              type = types.submodule {
+                options.destination = mkOption { … };
+              };
+            };
+            ignore = types.mkOption {
+              description = "Drop the packet without sending anything back.";
+              type = types.submodule {};
+            };
+          });
       };
-      forward = mkOption {
-        description = "Forward the packet.";
-        type = submodule {
-          options.destination = mkOption { … };
+      config.toyRouter.rules = {
+        http = {
+          bounce = {
+            errorMessage = "Unencrypted HTTP is banned. You must always use https://.";
+          };
         };
-      };
-      ignore = mkOption {
-        description = "Drop the packet without sending anything back.";
-        type = submodule {};
+        ssh = { drop = {}; };
       };
     }
     ```

From bcd774606a257fd6f14bda50effac67474005447 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 4 Feb 2024 17:31:40 +0100
Subject: [PATCH 15/23] lib/tests/modules/types-attrTag: Test against
 unexpected attrs

Thank you lheckemann for pointing this out!
---
 lib/tests/modules/types-attrTag.nix | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/lib/tests/modules/types-attrTag.nix b/lib/tests/modules/types-attrTag.nix
index 43d71b3ae6ad..7825cfe203fb 100644
--- a/lib/tests/modules/types-attrTag.nix
+++ b/lib/tests/modules/types-attrTag.nix
@@ -98,12 +98,12 @@ in
     merged.extensi-foo.extensible = "foo";
     merged.extensi-bar.extensible = "bar";
     okChecks =
-      assert config.intStrings.hello.right == "hello world";
-      assert config.intStrings.numberOne.left == 1;
-      assert config.merged.negative.nay == false;
-      assert config.merged.positive.yay == 100;
-      assert config.merged.extensi-foo.extensible == "foo";
-      assert config.merged.extensi-bar.extensible == "bar";
+      assert config.intStrings.hello == { right = "hello world"; };
+      assert config.intStrings.numberOne == { left = 1; };
+      assert config.merged.negative == { nay = false; };
+      assert config.merged.positive == { yay = 100; };
+      assert config.merged.extensi-foo == { extensible = "foo"; };
+      assert config.merged.extensi-bar == { extensible = "bar"; };
       # assert lib.foldl' (a: b: builtins.trace b a) true (lib.attrNames config.docs);
       assert config.docs."submodules.<name>.foo.bar".type == "signed integer";
       assert config.docs."submodules.<name>.qux".type == "string";

From 1465777b63d38988d5ecd81683d2975321e59d1a Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sun, 4 Feb 2024 18:09:51 +0100
Subject: [PATCH 16/23] lib.types.attrTag: Custom error when passing bare type

---
 lib/tests/modules.sh                           |  1 +
 lib/tests/modules/types-attrTag-wrong-decl.nix | 14 ++++++++++++++
 lib/types.nix                                  |  9 ++++++++-
 3 files changed, 23 insertions(+), 1 deletion(-)
 create mode 100644 lib/tests/modules/types-attrTag-wrong-decl.nix

diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh
index b1994ff31638..f5f7e907d277 100755
--- a/lib/tests/modules.sh
+++ b/lib/tests/modules.sh
@@ -113,6 +113,7 @@ checkConfigError 'A definition for option .intStrings\.mergeError. is not of typ
 checkConfigError 'A definition for option .intStrings\.badTagError. is not of type .attribute-tagged union' config.intStrings.badTagError ./types-attrTag.nix
 checkConfigError 'A definition for option .intStrings\.badTagTypeError\.left. is not of type .signed integer.' config.intStrings.badTagTypeError.left ./types-attrTag.nix
 checkConfigError 'A definition for option .nested\.right\.left. is not of type .signed integer.' config.nested.right.left ./types-attrTag.nix
+checkConfigError 'In attrTag/attrTagWith, each tag value must be an option, but tag int was a bare type, not wrapped in mkOption.' config.opt.int ./types-attrTag-wrong-decl.nix
 
 # types.pathInStore
 checkConfigOutput '".*/store/0lz9p8xhf89kb1c1kk6jxrzskaiygnlh-bash-5.2-p15.drv"' config.pathInStore.ok1 ./types.nix
diff --git a/lib/tests/modules/types-attrTag-wrong-decl.nix b/lib/tests/modules/types-attrTag-wrong-decl.nix
new file mode 100644
index 000000000000..d03370bc10da
--- /dev/null
+++ b/lib/tests/modules/types-attrTag-wrong-decl.nix
@@ -0,0 +1,14 @@
+{ lib, ... }:
+let
+  inherit (lib) types mkOption;
+in
+{
+  options = {
+    opt = mkOption {
+      type = types.attrTag {
+        int = types.int;
+      };
+      default = { int = 1; };
+    };
+  };
+}
diff --git a/lib/types.nix b/lib/types.nix
index 7fe7b5d92eac..a77a8ef11244 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -15,6 +15,7 @@ let
     isList
     isString
     isStorePath
+    throwIf
     toDerivation
     toList
     ;
@@ -627,7 +628,13 @@ rec {
           mapAttrs
             (n: opt:
               builtins.addErrorContext "while checking that attrTag tag ${lib.strings.escapeNixIdentifier n} is an option with a type${inAttrPosSuffix args.tags n}" (
-                assert opt._type == "option";
+                throwIf (opt._type or null != "option")
+                  "In attrTag/attrTagWith, each tag value must be an option, but tag ${lib.strings.escapeNixIdentifier n} ${
+                    if opt?_type then
+                      if opt._type == "option-type"
+                      then "was a bare type, not wrapped in mkOption."
+                      else "was of type ${lib.strings.escapeNixString opt._type}."
+                    else "was not."}"
                 opt // {
                   declarations = opt.declarations or (
                     let pos = builtins.unsafeGetAttrPos n args.tags;

From 47e4a18d018be9efaa93a199e24fbeedc80f14be Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Thu, 4 Apr 2024 10:29:56 +0200
Subject: [PATCH 17/23] types.attrTagWith: remove

Keep it simple for now.
---
 lib/tests/modules.sh |  2 +-
 lib/types.nix        | 28 ++++++++++++++++++----------
 2 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh
index f5f7e907d277..750b1d025e02 100755
--- a/lib/tests/modules.sh
+++ b/lib/tests/modules.sh
@@ -113,7 +113,7 @@ checkConfigError 'A definition for option .intStrings\.mergeError. is not of typ
 checkConfigError 'A definition for option .intStrings\.badTagError. is not of type .attribute-tagged union' config.intStrings.badTagError ./types-attrTag.nix
 checkConfigError 'A definition for option .intStrings\.badTagTypeError\.left. is not of type .signed integer.' config.intStrings.badTagTypeError.left ./types-attrTag.nix
 checkConfigError 'A definition for option .nested\.right\.left. is not of type .signed integer.' config.nested.right.left ./types-attrTag.nix
-checkConfigError 'In attrTag/attrTagWith, each tag value must be an option, but tag int was a bare type, not wrapped in mkOption.' config.opt.int ./types-attrTag-wrong-decl.nix
+checkConfigError 'In attrTag, each tag value must be an option, but tag int was a bare type, not wrapped in mkOption.' config.opt.int ./types-attrTag-wrong-decl.nix
 
 # types.pathInStore
 checkConfigOutput '".*/store/0lz9p8xhf89kb1c1kk6jxrzskaiygnlh-bash-5.2-p15.drv"' config.pathInStore.ok1 ./types.nix
diff --git a/lib/types.nix b/lib/types.nix
index a77a8ef11244..2e44dd5472ee 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -620,16 +620,15 @@ rec {
       nestedTypes.elemType = elemType;
     };
 
-    attrTag = tags: attrTagWith { inherit tags; };
-
-    attrTagWith = args@{ tags }:
+    attrTag = tags:
+      let tags_ = tags; in
       let
         tags =
           mapAttrs
             (n: opt:
-              builtins.addErrorContext "while checking that attrTag tag ${lib.strings.escapeNixIdentifier n} is an option with a type${inAttrPosSuffix args.tags n}" (
+              builtins.addErrorContext "while checking that attrTag tag ${lib.strings.escapeNixIdentifier n} is an option with a type${inAttrPosSuffix tags_ n}" (
                 throwIf (opt._type or null != "option")
-                  "In attrTag/attrTagWith, each tag value must be an option, but tag ${lib.strings.escapeNixIdentifier n} ${
+                  "In attrTag, each tag value must be an option, but tag ${lib.strings.escapeNixIdentifier n} ${
                     if opt?_type then
                       if opt._type == "option-type"
                       then "was a bare type, not wrapped in mkOption."
@@ -637,16 +636,16 @@ rec {
                     else "was not."}"
                 opt // {
                   declarations = opt.declarations or (
-                    let pos = builtins.unsafeGetAttrPos n args.tags;
+                    let pos = builtins.unsafeGetAttrPos n tags_;
                     in if pos == null then [] else [ pos.file ]
                   );
                   declarationPositions = opt.declarationPositions or (
-                    let pos = builtins.unsafeGetAttrPos n args.tags;
+                    let pos = builtins.unsafeGetAttrPos n tags_;
                     in if pos == null then [] else [ pos ]
                   );
                 }
               ))
-            args.tags;
+            tags_;
         choicesStr = concatMapStringsSep ", " lib.strings.escapeNixIdentifier (attrNames tags);
       in
       mkOptionType {
@@ -663,7 +662,15 @@ rec {
                 };
             })
             tags;
-        substSubModules = m: attrTagWith { tags = mapAttrs (n: opt: opt // { type = (opt.type or types.unspecified).substSubModules m; }) tags; };
+        substSubModules = m:
+          attrTag
+            (mapAttrs
+              (n: opt:
+                opt // {
+                  type = (opt.type or types.unspecified).substSubModules m;
+                }
+              )
+              tags);
         check = v: isAttrs v && length (attrNames v) == 1 && tags?${head (attrNames v)};
         merge = loc: defs:
           let
@@ -687,7 +694,8 @@ rec {
               }
             else throw "The option `${showOption loc}` is defined as ${lib.strings.escapeNixIdentifier choice}, but ${lib.strings.escapeNixIdentifier choice} is not among the valid choices (${choicesStr}). Value ${choice} was defined in ${showFiles (getFiles defs)}.";
         nestedTypes = tags;
-        functor = (defaultFunctor "attrTagWith") // {
+        functor = defaultFunctor "attrTag" // {
+          type = { tags, ... }: types.attrTag tags;
           payload = { inherit tags; };
           binOp =
             let

From 2d791b5f7b6575f2153f5971a2046bec15f637f7 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Thu, 4 Apr 2024 11:45:03 +0200
Subject: [PATCH 18/23] types.attrTag: Remove substSubmodules

I haven't managed to trigger the error, and it turns out that this
method is optional.
Specifically, getSubmodules is unimplemented (and unimplementable),
the tests pass, and we seem to have good location info.
---
 lib/types.nix | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/lib/types.nix b/lib/types.nix
index 2e44dd5472ee..694e800f5092 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -662,15 +662,6 @@ rec {
                 };
             })
             tags;
-        substSubModules = m:
-          attrTag
-            (mapAttrs
-              (n: opt:
-                opt // {
-                  type = (opt.type or types.unspecified).substSubModules m;
-                }
-              )
-              tags);
         check = v: isAttrs v && length (attrNames v) == 1 && tags?${head (attrNames v)};
         merge = loc: defs:
           let

From f354686536823a0bedb95abf13b090b961485bf9 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Thu, 4 Apr 2024 11:47:36 +0200
Subject: [PATCH 19/23] doc/option-types: Update sum types

---
 nixos/doc/manual/development/option-types.section.md | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md
index 0b348094bfcf..5ed55f53aec0 100644
--- a/nixos/doc/manual/development/option-types.section.md
+++ b/nixos/doc/manual/development/option-types.section.md
@@ -307,16 +307,15 @@ If some values are instances of more than one of the types, it is not possible t
 
 ## Sum types {#sec-option-types-sums}
 
-A sum type can be thought of, conceptually, as a *`types.enum`* where each valid item is paired with a type, through some value syntax.
+A sum type can be thought of, conceptually, as a *`types.enum`* where each valid item is paired with at least a type, through some value syntax.
 Nix does not have a built-in syntax for this pairing of a label and a type or value, so sum types may be represented in multiple ways.
 
-If the built-in Nix value types provide enough distinction, you simplify your syntax with a [union type](#sec-option-types-unions) instead.
+If the you're interested in can be distinguished without a label, you may simplify your value syntax with a [union type](#sec-option-types-unions) instead.
 
-`types.attrTag` *`{ attr1 = t1; attr2 = t2; ... }`*
+`types.attrTag` *`{ attr1 = option1; attr2 = option2; ... }`*
 
 :   An attribute set containing one attribute, whose name must be picked from
-    the attribute set (`attr1`, etc) and whose value must be of the accompanying
-    type.
+    the attribute set (`attr1`, etc) and whose value consists of definitions that are valid for the corresponding option (`option1`, etc).
 
     This type appears in the documentation as _attribute-tagged union_.
 

From 74831d8b38ad4754940d25a03a39ce66b6b6cf4f Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Thu, 4 Apr 2024 10:06:59 +0200
Subject: [PATCH 20/23] lib/tests/modules/types-attrTag.nix: Clean up unneeded
 comment

---
 lib/tests/modules/types-attrTag.nix | 1 -
 1 file changed, 1 deletion(-)

diff --git a/lib/tests/modules/types-attrTag.nix b/lib/tests/modules/types-attrTag.nix
index 7825cfe203fb..277d4cc4cc0b 100644
--- a/lib/tests/modules/types-attrTag.nix
+++ b/lib/tests/modules/types-attrTag.nix
@@ -104,7 +104,6 @@ in
       assert config.merged.positive == { yay = 100; };
       assert config.merged.extensi-foo == { extensible = "foo"; };
       assert config.merged.extensi-bar == { extensible = "bar"; };
-      # assert lib.foldl' (a: b: builtins.trace b a) true (lib.attrNames config.docs);
       assert config.docs."submodules.<name>.foo.bar".type == "signed integer";
       assert config.docs."submodules.<name>.qux".type == "string";
       assert lib.length config.docs."merged.<name>.extensible".declarations == 2;

From cf4968a9045e7404ba54598ee9608f7e33458006 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Thu, 4 Apr 2024 12:22:08 +0200
Subject: [PATCH 21/23] lib/tests/modules/types-attrTag.nix: Test other option
 doc attrs

---
 lib/tests/modules/types-attrTag.nix | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/lib/tests/modules/types-attrTag.nix b/lib/tests/modules/types-attrTag.nix
index 277d4cc4cc0b..ae676e347136 100644
--- a/lib/tests/modules/types-attrTag.nix
+++ b/lib/tests/modules/types-attrTag.nix
@@ -59,6 +59,7 @@ in
           };
           qux = mkOption {
             type = types.str;
+            description = "A qux for when you don't want a foo";
           };
         }
       );
@@ -106,6 +107,14 @@ in
       assert config.merged.extensi-bar == { extensible = "bar"; };
       assert config.docs."submodules.<name>.foo.bar".type == "signed integer";
       assert config.docs."submodules.<name>.qux".type == "string";
+      assert config.docs."submodules.<name>.qux".declarations == [ __curPos.file ];
+      assert config.docs."submodules.<name>.qux".loc == [ "submodules" "<name>" "qux" ];
+      assert config.docs."submodules.<name>.qux".name == "submodules.<name>.qux";
+      assert config.docs."submodules.<name>.qux".description == "A qux for when you don't want a foo";
+      assert config.docs."submodules.<name>.qux".readOnly == false;
+      assert config.docs."submodules.<name>.qux".visible == true;
+      # Not available (yet?)
+      # assert config.docs."submodules.<name>.qux".declarationsWithPositions == [ ... ];
       assert lib.length config.docs."merged.<name>.extensible".declarations == 2;
       true;
   };

From 22d7f146a4b11f89118fc4dd5939e09d2e4e652d Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Thu, 4 Apr 2024 12:54:23 +0200
Subject: [PATCH 22/23] lib.types.attrTag: Fix declarationPositions after merge

---
 lib/tests/modules/types-attrTag.nix | 20 +++++++++++++++++---
 lib/types.nix                       |  2 +-
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/lib/tests/modules/types-attrTag.nix b/lib/tests/modules/types-attrTag.nix
index ae676e347136..b2e5158bb44b 100644
--- a/lib/tests/modules/types-attrTag.nix
+++ b/lib/tests/modules/types-attrTag.nix
@@ -1,7 +1,8 @@
-{ lib, config, ... }:
+{ lib, config, options, ... }:
 let
   inherit (lib) mkOption types;
   forceDeep = x: builtins.deepSeq x x;
+  mergedSubOption = (options.merged.type.getSubOptions options.merged.loc).extensible."merged.<name>";
 in
 {
   options = {
@@ -98,7 +99,7 @@ in
     merged.positive.yay = 100;
     merged.extensi-foo.extensible = "foo";
     merged.extensi-bar.extensible = "bar";
-    okChecks =
+    okChecks = builtins.addErrorContext "while evaluating the assertions" (
       assert config.intStrings.hello == { right = "hello world"; };
       assert config.intStrings.numberOne == { left = 1; };
       assert config.merged.negative == { nay = false; };
@@ -115,7 +116,20 @@ in
       assert config.docs."submodules.<name>.qux".visible == true;
       # Not available (yet?)
       # assert config.docs."submodules.<name>.qux".declarationsWithPositions == [ ... ];
+      assert options.submodules.declarations == [ __curPos.file ];
+      assert lib.length options.submodules.declarationPositions == 1;
+      assert (lib.head options.submodules.declarationPositions).file == __curPos.file;
+      assert options.merged.declarations == [ __curPos.file __curPos.file ];
+      assert lib.length options.merged.declarationPositions == 2;
+      assert (lib.elemAt options.merged.declarationPositions 0).file == __curPos.file;
+      assert (lib.elemAt options.merged.declarationPositions 1).file == __curPos.file;
+      assert (lib.elemAt options.merged.declarationPositions 0).line != (lib.elemAt options.merged.declarationPositions 1).line;
+      assert mergedSubOption.declarations == [ __curPos.file __curPos.file ];
+      assert lib.length mergedSubOption.declarationPositions == 2;
+      assert (lib.elemAt mergedSubOption.declarationPositions 0).file == __curPos.file;
+      assert (lib.elemAt mergedSubOption.declarationPositions 1).file == __curPos.file;
+      assert (lib.elemAt mergedSubOption.declarationPositions 0).line != (lib.elemAt mergedSubOption.declarationPositions 1).line;
       assert lib.length config.docs."merged.<name>.extensible".declarations == 2;
-      true;
+      true);
   };
 }
diff --git a/lib/types.nix b/lib/types.nix
index 694e800f5092..f7d878dfcbc5 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -707,7 +707,7 @@ rec {
                     // {
                       # mergeOptionDecls is not idempotent in these attrs:
                       declarations = a.tags.${tagName}.declarations ++ bOpt.declarations;
-                      declarationPositions = a.tags.${tagName}.declarations ++ bOpt.declarations;
+                      declarationPositions = a.tags.${tagName}.declarationPositions ++ bOpt.declarationPositions;
                     }
                   )
                   (builtins.intersectAttrs a.tags b.tags);

From 35fe538330b738b90d527d908ee487e38d42de40 Mon Sep 17 00:00:00 2001
From: Robert Hensing <roberth@users.noreply.github.com>
Date: Thu, 4 Apr 2024 13:00:19 +0200
Subject: [PATCH 23/23] types.attrTag: Remove unnecessary definitions override

Committing because tests pass.

Co-authored-by: Silvan Mosberger <github@infinisil.com>
---
 lib/types.nix | 1 -
 1 file changed, 1 deletion(-)

diff --git a/lib/types.nix b/lib/types.nix
index f7d878dfcbc5..c7e8ddcedd95 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -658,7 +658,6 @@ rec {
               "${lib.showOption prefix}" =
                 tagOption // {
                   loc = prefix ++ [ tagName ];
-                  definitions = [];
                 };
             })
             tags;