Merge pull request #1208

Author: jmikola

docs/en/reference/annotations-reference.rst

@@ -1248,6 +1248,14 @@ is used for pessimistic and optimistic locking. This is only compatible with
     /** @Int @Version */
     private $version;
 
+By default, Doctrine ODM processes updates :ref:`embed-many <embed_many>` and
+:ref:`reference-many <reference_many>` collections in separate write operations,
+which do not bump the document version. Users employing document versioning are
+encouraged to use the :ref:`atomicSet <atomic_set>` or
+:ref:`atomicSetArray <atomic_set_array>` strategies for such collections, which
+will ensure that collections are updated in the same write operation as the
+versioned document.
+
 .. _BSON specification: http://bsonspec.org/spec.html
 .. _DBRef: http://docs.mongodb.org/manual/reference/database-references/#dbrefs
 .. _geoNear command: http://docs.mongodb.org/manual/reference/command/geoNear/

docs/en/reference/collection-strategies.rst

@@ -52,6 +52,8 @@ elements into the array. MongoDB does not allow elements to be added and removed
 from an array in a single operation, so this strategy relies on multiple update
 queries to remove and insert elements (in that order).
 
+.. _atomic_set:
+
 ``atomicSet``
 -------------
 
@@ -66,6 +68,8 @@ strategy can be especially useful when dealing with high concurrency and
     The ``atomicSet`` and ``atomicSetArray`` strategies may only be used for 
     collections mapped directly in a top-level document.
 
+.. _atomic_set_array:
+
 ``atomicSetArray``
 ------------------