Add documentation regarding new features

Author: alcaeus

UPGRADE-1.3.md

@@ -1,5 +1,31 @@
 # UPGRADE FROM 1.2 TO 1.3
 
+## Events
+
+### `onClassMetadataNotFound` event added
+
+The default ClassMetadataFactory now triggers an `onClassMetadataNotFound` event
+when no metadata was found for a given class. The event args contain information
+about the loaded class and can store a metadata object which can be used to load
+custom metadata when none was found.
+
+### `ResolveTargetDocumentListener` is now an event subscriber
+
+The `Doctrine\ODM\MongoDB\Tools\ResolveTargetDocumentListener` class now
+implements the `EventSubscriber` interface. You can still register it as a
+listener as was necessary previously, but in order to use new functionality you
+have to register it as an event subscriber.
+
+### `ResolveTargetDocumentListener` resolves class names on document load
+
+The `Doctrine\ODM\MongoDB\Tools\ResolveTargetDocumentListener` class not only
+resolves class names when looking up the `targetDoccumet` of an association in
+a document, but it also uses the new `onClassMetadataNotFound` event to resolve
+class names and trigger a secondary metadata load cycle if no metadata was found
+for the original class name. To use this functionality, either register an event
+listener for the `onClassMetadataNotFound` event or register the entire class as
+an event subscriber.
+
 ## GridFS
 
 GridFS support will be rewritten for 2.0 and was deprecated in its current form.

docs/en/cookbook/resolve-target-document-listener.rst

@@ -10,7 +10,8 @@ Doctrine MongoDB ODM includes a utility called
 inside Doctrine and rewriting ``targetDocument`` parameters in your metadata
 mapping at runtime. This allows your bundle to use an interface or abstract
 class in its mappings while still allowing the mapping to resolve to a concrete
-document class at runtime.
+document class at runtime. It will also rewrite class names when no mapping
+metadata has been found for the original class name.
 
 This functionality allows you to define relationships between different
 documents without creating hard dependencies.
@@ -126,7 +127,7 @@ you cannot be guaranteed that the targetDocument resolution will occur reliably:
     );
 
     // Add the ResolveTargetDocumentListener
-    $evm->addEventListener(\Doctrine\ODM\MongoDB\Events::loadClassMetadata, $rtdl);
+    $evm->addEventSubscriber($rtdl);
 
     // Create the document manager as you normally would
     $dm = \Doctrine\ODM\MongoDB\DocumentManager::create($connectionOptions, $config, $evm);