add docs for UnionDiscriminator

Author: idbentley

doc/reference/annotations.rst

@@ -9,6 +9,8 @@ JMS serializer now supports PHP 8 attributes, with a few caveats:
 - There is an edge case when setting this exact serialization group ``#[Groups(['value' => 'any value here'])]``.
 (when there is only one item in th serialization groups array and has as key ``value`` the attribute will not work as expected,
 please use the alternative syntax ``#[Groups(groups: ['value' => 'any value here'])]`` that works with no issues),
+- Some support for unions exists.  For unions of primitive types, the system will try to resolve them automatically.  For
+classes that contain union attributes, the ``#[UnionDiscriminator]`` attribute must be used to specify the type of the union.
 
 Converting your annotations to attributes
 -----------------------------------------
@@ -384,6 +386,31 @@ to the least super type:
 
     `groups` is optional and is used as exclusion policy.
 
+#[UnionDiscriminator]
+
+This attribute allows deserialization of unions.  The ``#[UnionDiscriminator]`` attribute has to be applied
+to an attribute that can be one of many types.
+
+.. code-block :: php
+
+    class Vehicle {
+        #[UnionDiscriminator(field: 'typeDiscriminator')]
+        private Manual|Automatic $transmission;
+    }
+
+In the case of this example, both Manual and Automatic should contain a string attribute named `typeDiscriminator`.  If the `typeDiscriminator` field
+will always contain the fully qualified clasname, then the appropriate type will be selected for deserialization.
+
+If, however, the field contains a string that is not the fully qualified classname, then the `map` option can be used to map the
+string to the appropriate class.
+
+.. code-block :: php
+
+    class Vehicle {
+        #[UnionDiscriminator(field: 'type', map: ['manual' => 'FullyQualified/Path/Manual', 'automatic' => 'FullyQualified/Path/Automatic'])]
+        private Manual|Automatic $transmission;
+    }
+
 #[Type]
 ~~~~~~~
 This attribute can be defined on a property to specify the type of that property.