1 files changed, 58 insertions, 10 deletions
diff --git a/nixos/doc/manual/development/option-types.xml b/nixos/doc/manual/development/option-types.xml
index 5a6dae6e9912..3d2191e2f3f3 100644
--- a/nixos/doc/manual/development/option-types.xml
+++ b/nixos/doc/manual/development/option-types.xml
@@ -23,16 +23,6 @@
   <variablelist>
    <varlistentry>
     <term>
-     <varname>types.attrs</varname>
-    </term>
-    <listitem>
-     <para>
-      A free-form attribute set.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
      <varname>types.bool</varname>
     </term>
     <listitem>
@@ -64,6 +54,64 @@
      </para>
     </listitem>
    </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>types.anything</varname>
+    </term>
+    <listitem>
+     <para>
+      A type that accepts any value and recursively merges attribute sets together.
+      This type is recommended when the option type is unknown.
+      <example xml:id="ex-types-anything">
+       <title><literal>types.anything</literal> Example</title>
+       <para>
+        Two definitions of this type like
+<programlisting>
+{
+  str = lib.mkDefault "foo";
+  pkg.hello = pkgs.hello;
+  fun.fun = x: x + 1;
+}
+</programlisting>
+<programlisting>
+{
+  str = lib.mkIf true "bar";
+  pkg.gcc = pkgs.gcc;
+  fun.fun = lib.mkForce (x: x + 2);
+}
+</programlisting>
+        will get merged to
+<programlisting>
+{
+  str = "bar";
+  pkg.gcc = pkgs.gcc;
+  pkg.hello = pkgs.hello;
+  fun.fun = x: x + 2;
+}
+</programlisting>
+       </para>
+      </example>
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>types.attrs</varname>
+    </term>
+    <listitem>
+     <para>
+      A free-form attribute set.
+      <warning><para>
+       This type will be deprecated in the future because it doesn't recurse
+       into attribute sets, silently drops earlier attribute definitions, and
+       doesn't discharge <literal>lib.mkDefault</literal>, <literal>lib.mkIf
+       </literal> and co. For allowing arbitrary attribute sets, prefer
+       <literal>types.attrsOf types.anything</literal> instead which doesn't
+       have these problems.
+      </para></warning>
+     </para>
+    </listitem>
+   </varlistentry>
   </variablelist>
 
   <para>