review @Spomky

Author: soyuka

object-mapper.rst

@@ -3,7 +3,8 @@ Object Mapper
 
 Symfony provides a mapper component to transform a given object into another one,
 simplifying tasks like converting DTOs (Data Transfer Objects) to entities or
-vice-versa.
+vice-versa. It may also be useful when decoupling API input/output from internal
+models helping with legacy code or hexagonal architectures implementations.
 
 .. versionadded:: 7.2
 
@@ -386,7 +387,8 @@ executed *after* the target object is initially created (if the target is a
 class name we use ``newInstanceWithoutConstructor``) but *before* properties
 are mapped. Its responsibility is often to return a correctly initialized
 instance, potentially replacing the one created by the mapper.
-The returned value *must* be an object of the target type.
+The returned value *must* be an object of the target type or else an
+exception will be thrown.
 
 ::
 
@@ -479,6 +481,9 @@ specifying where its properties should come from in the *source* class. This is
 done using the ``source`` parameter within the ``#[Map]`` attribute on the target's
 properties.
 
+Note that if both the ``source`` and the ``target`` classes define the ``#[Map]``
+attribute, the ``source`` takes precedence.
+
 ::
 
     // src/Api/Payload.php - Represents data from an external API