diff --git a/docs/odm-ng/reference/annotations-reference.rst b/docs/odm-ng/reference/annotations-reference.rst
new file mode 100644
index 0000000000..fb94016f56
--- /dev/null
+++ b/docs/odm-ng/reference/annotations-reference.rst
@@ -0,0 +1,1067 @@
+Annotations Reference
+=====================
+
+In this chapter a reference of every Doctrine 2 ODM Annotation is
+given with short explanations on their context and usage.
+
+@AlsoLoad
+---------
+
+Specify one or more MongoDB fields to use for loading data if the original field
+does not exist.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Field(type="string") @AlsoLoad("name") */
+    public $fullName;
+
+The ``$fullName`` property will be loaded from ``fullName`` if it exists, but
+fall back to ``name`` if it does not exist. If multiple fall back fields are
+specified, ODM will consider them in order until the first is found.
+
+Additionally, `@AlsoLoad`_ may annotate a method with one or more field names.
+Before normal hydration, the field(s) will be considered in order and the method
+will be invoked with the first value found as its single argument.
+
+.. code-block:: php
+
+    <?php
+
+    /** @AlsoLoad({"name", "fullName"}) */
+    public function populateFirstAndLastName($name)
+    {
+        list($this->firstName, $this->lastName) = explode(' ', $name);
+    }
+
+For additional information on using `@AlsoLoad`_, see
+:doc:`Migrations <migrating-schemas>`.
+
+@ChangeTrackingPolicy
+---------------------
+
+This annotation is used to change the change tracking policy for a document:
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Document
+     * @ChangeTrackingPolicy("DEFERRED_EXPLICIT")
+     */
+    class Person
+    {
+        // ...
+    }
+
+For a list of available policies, read the section on :ref:`change tracking policies <change_tracking_policies>`.
+
+@DefaultDiscriminatorValue
+--------------------------
+
+This annotation can be used when using `@DiscriminatorField`_. It will be used
+as a fallback value if a document has no discriminator field set. This must
+correspond to a value from the configured discriminator map.
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Document
+     * @InheritanceType("SINGLE_COLLECTION")
+     * @DiscriminatorField("type")
+     * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
+     * @DefaultDiscriminatorValue("person")
+     */
+    class Person
+    {
+        // ...
+    }
+
+@DiscriminatorField
+-------------------
+
+This annotation is required for the top-most class in a
+:ref:`single collection inheritance <single_collection_inheritance>` hierarchy.
+It takes a string as its only argument, which specifies the database field to
+store a class name or key (if a discriminator map is used). ODM uses this field
+during hydration to select the instantiation class.
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Document
+     * @InheritanceType("SINGLE_COLLECTION")
+     * @DiscriminatorField("type")
+     */
+    class SuperUser
+    {
+        // ...
+    }
+
+.. note::
+
+    For backwards compatibility, the discriminator field may also be specified
+    via either the ``name`` or ``fieldName`` annotation attributes.
+
+@DiscriminatorMap
+-----------------
+
+This annotation is required for the top-most class in a
+:ref:`single collection inheritance <single_collection_inheritance>` hierarchy.
+It takes an array as its only argument, which maps keys to class names. The
+class names may be fully qualified or relative to the current namespace. When
+a document is persisted to the database, its class name key will be stored in
+the discriminator field instead of the |FQCN|.
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Document
+     * @InheritanceType("SINGLE_COLLECTION")
+     * @DiscriminatorField("type")
+     * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
+     */
+    class Person
+    {
+        // ...
+    }
+
+.. _annotation_distance:
+
+@Distance
+---------
+
+This annotation can be used in combination with geospatial indexes and the
+:ref:`geoNear() <geonear>` query method to populate the property with the
+calculated distance value.
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Document
+     * @Index(keys={"coordinates"="2d"})
+     */
+    class Place
+    {
+        /** @Id */
+        public $id;
+    
+        /** @EmbedOne(targetDocument="Coordinates") */
+        public $coordinates;
+    
+        /** @Distance */
+        public $distance;
+    }
+    
+    /** @EmbeddedDocument */
+    class Coordinates
+    {
+        /** @Field(type="float") */
+        public $latitude;
+    
+        /** @Field(type="float") */
+        public $longitude;
+    }
+
+Now you can run a `geoNear command`_ and access the computed distance. The
+following example would return the distance of the city nearest the query
+coordinates:
+
+.. code-block:: php
+
+    <?php
+
+    $city = $this->dm->createQuery('City')
+        ->geoNear(50, 60)
+        ->limit(1)
+        ->getQuery()
+        ->getSingleResult();
+    echo $city->distance;
+
+@Document
+---------
+
+Required annotation to mark a PHP class as a document, whose peristence will be
+managed by ODM.
+
+Optional attributes:
+
+-
+   db - By default, the document manager will use the MongoDB database defined
+   in the configuration, but this option may be used to override the database
+   for a particular document class.
+-
+   collection - By default, the collection name is derived from the document's
+   class name, but this option may be used to override that behavior.
+-
+   repositoryClass - Specifies a custom repository class to use.
+-
+   indexes - Specifies an array of indexes for this document.
+-
+   writeConcern - Specifies the write concern for this document that overwrites
+   the default write concern specified in the configuration. It does not overwrite
+   a write concern given as :ref:`option <flush_options>` to the ``flush``
+   method when committing your documents.
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Document(
+     *     db="documents",
+     *     collection="users",
+     *     repositoryClass="MyProject\UserRepository",
+     *     indexes={
+     *         @Index(keys={"username"="desc"}, options={"unique"=true})
+     *     }
+     * )
+     */
+    class User
+    {
+        //...
+    }
+
+@EmbedMany
+----------
+
+This annotation is similar to `@EmbedOne`_, but instead of embedding one
+document, it embeds a collection of documents.
+
+Optional attributes:
+
+-
+    targetDocument - A |FQCN| of the target document.
+-
+    discriminatorField - The database field name to store the discriminator
+    value within the embedded document.
+-
+    discriminatorMap - Map of discriminator values to class names.
+-
+    defaultDiscriminatorValue - A default value for discriminatorField if no value
+    has been set in the embedded document.
+-
+    strategy - The strategy used to persist changes to the collection. Possible
+    values are ``addToSet``, ``pushAll``, ``set``, and ``setArray``. ``pushAll``
+    is the default. See :ref:`storage_strategies` for more information.
+-
+    collectionClass - A |FQCN| of class that implements ``Collection`` interface
+    and is used to hold documents. Doctrine's ``ArrayCollection`` is used by default.
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @EmbedMany(
+     *     strategy="set",
+     *     discriminatorField="type",
+     *     discriminatorMap={
+     *         "book"="Documents\BookTag",
+     *         "song"="Documents\SongTag"
+     *     },
+     *     defaultDiscriminatorValue="book"
+     * )
+     */
+    private $tags = array();
+
+Depending on the embedded document's class, a value of ``user`` or ``author``
+will be stored in the ``type`` field and used to reconstruct the proper class
+during hydration. The ``type`` field need not be mapped on the embedded
+document classes.
+
+@EmbedOne
+---------
+
+The `@EmbedOne`_ annotation works similarly to `@ReferenceOne`_, except that
+that document will be embedded within the parent document. Consider the
+following excerpt from the MongoDB documentation:
+
+    The key question in MongoDB schema design is "does this object merit its own
+    collection, or rather should it be embedded within objects in other
+    collections?" In relational databases, each sub-item of interest typically
+    becomes a separate table (unless you are denormalizing for performance). In
+    MongoDB, this is not recommended – embedding objects is much more efficient.
+    Data is then collocated on disk; client-server turnarounds to the database
+    are eliminated. So in general, the question to ask is, "why would I not want
+    to embed this object?"
+
+Optional attributes:
+
+-
+    targetDocument - A |FQCN| of the target document.
+-
+    discriminatorField - The database field name to store the discriminator
+    value within the embedded document.
+-
+    discriminatorMap - Map of discriminator values to class names.
+-
+    defaultDiscriminatorValue - A default value for discriminatorField if no value
+    has been set in the embedded document.
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @EmbedOne(
+     *     discriminatorField="type",
+     *     discriminatorMap={
+     *         "user"="Documents\User",
+     *         "author"="Documents\Author"
+     *     },
+     *     defaultDiscriminatorValue="user"
+     * )
+     */
+    private $creator;
+
+Depending on the embedded document's class, a value of ``user`` or ``author``
+will be stored in the ``type`` field and used to reconstruct the proper class
+during hydration. The ``type`` field need not be mapped on the embedded
+document classes.
+
+@EmbeddedDocument
+-----------------
+
+Marks the document as embeddable. This annotation is required for any documents
+to be stored within an `@EmbedOne`_ or `@EmbedMany`_ relationship.
+
+.. code-block:: php
+
+    <?php
+
+    /** @EmbeddedDocument */
+    class Money
+    {
+        /** @Field(type="float") */
+        private $amount;
+    
+        public function __construct($amount)
+        {
+            $this->amount = (float) $amount;
+        }
+        //...
+    }
+    
+    /** @Document(db="finance", collection="wallets") */
+    class Wallet
+    {
+        /** @EmbedOne(targetDocument="Money") */
+        private $money;
+    
+        public function setMoney(Money $money)
+        {
+            $this->money = $money;
+        }
+        //...
+    }
+    //...
+    $wallet = new Wallet();
+    $wallet->setMoney(new Money(34.39));
+    $dm->persist($wallet);
+    $dm->flush();
+
+Unlike normal documents, embedded documents cannot specify their own database or
+collection. That said, a single embedded document class may be used with
+multiple document classes, and even other embedded documents!
+
+Optional attributes:
+
+-
+   indexes - Specifies an array of indexes for this embedded document, to be
+   included in the schemas of any embedding documents.
+
+@Field
+------
+
+Marks an annotated instance variable for persistence. Values for this field will
+be saved to and loaded from the document store as part of the document class'
+lifecycle.
+
+Optional attributes:
+
+-
+   type - Name of the ODM type, which will determine the value's representation
+   in PHP and BSON (i.e. MongoDB). See :ref:`doctrine_mapping_types` for a list
+   of types. Defaults to "string".
+-
+   name - By default, the property name is used for the field name in MongoDB;
+   however, this option may be used to specify a database field name.
+-
+   nullable - By default, ODM will ``$unset`` fields in MongoDB if the PHP value
+   is null. Specify true for this option to force ODM to store a null value in
+   the database instead of unsetting the field.
+
+Examples:
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Field(type="string")
+     */
+    protected $username;
+    
+    /**
+     * @Field(type="string", name="co")
+     */
+    protected $country;
+    
+    /**
+     * @Field(type="float")
+     */
+    protected $height;
+
+@File
+-----
+
+Marks an annotated instance variable as a file. Additionally, this instructs ODM
+to store the entire document in `GridFS`_. Only a single field in a document may
+be mapped as a file.
+
+The instance variable will be an ``Doctrine\MongoDB\GridFSFile`` object, which
+is a wrapper class for `MongoGridFSFile`_ and facilitates access to the file
+data in GridFS. If the variable is a file path string when the document is first
+persisted, ODM will convert it to GridFSFile object automatically.
+
+.. code-block:: php
+
+    <?php
+
+    /** @File */
+    private $file;
+
+Additional fields can be mapped in GridFS documents like any other, but metadata
+fields set by the driver (e.g. ``length``) should be mapped with `@NotSaved`_ so
+as not to inadvertently overwrite them. Some metadata fields, such as
+``filename`` may be modified and do not require `@NotSaved`_. In the following
+example, we also add a custom field to refer to the corresponding User document
+that created the file.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Field(type="string") */
+    private $filename;
+
+    /** @NotSaved(type="int") */
+    private $length;
+
+    /** @NotSaved(type="string") */
+    private $md5;
+
+    /** @NotSaved(type="date") */
+    private $uploadDate;
+
+    /** @ReferenceOne(targetDocument="Documents\User") */
+    private $uploadedBy;
+
+.. _haslifecyclecallbacks:
+
+@HasLifecycleCallbacks
+----------------------
+
+This annotation must be set on the document class to instruct Doctrine to check
+for lifecycle callback annotations on public methods. Using `@PreFlush`_,
+`@PreLoad`_, `@PostLoad`_, `@PrePersist`_, `@PostPersist`_, `@PreRemove`_,
+`@PostRemove`_, `@PreUpdate`_, or `@PostUpdate`_ on methods without this
+annotation will cause Doctrine to ignore the callbacks.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Document @HasLifecycleCallbacks */
+    class User
+    {
+        /** @PostPersist */
+        public function sendWelcomeEmail() {}
+    }
+
+@Id
+---
+
+The annotated instance variable will be marked as the document identifier. The
+default behavior is to store a `MongoId`_ instance, but you may customize this
+via the :ref:`strategy <basic_mapping_identifiers>` attribute.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Document */
+    class User
+    {
+        /** @Id */
+        protected $id;
+    }
+
+@Index
+------
+
+This annotation is used inside of the class-level `@Document`_ or
+`@EmbeddedDocument`_ annotations to specify indexes to be created on the
+collection (or embedding document's collection in the case of
+`@EmbeddedDocument`_). It may also be used at the property-level to define
+single-field indexes.
+
+Optional attributes:
+
+-
+    keys - Mapping of indexed fields to their ordering or index type. ODM will
+    allow "asc" and "desc" to be used in place of ``1`` and ``-1``,
+    respectively. Special index types (e.g. "2dsphere") should be specified as
+    strings. This is required when `@Index`_ is used at the class level.
+-
+    options - Options for creating the index
+
+The ``keys`` and ``options`` attributes correspond to the arguments for
+`MongoCollection::createIndex() <http://php.net/manual/en/mongocollection.createindex.php>`_.
+ODM allows mapped field names (i.e. PHP property names) to be used when defining
+``keys``.
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Document(
+     *   indexes={
+     *     @Index(keys={"username"="desc"}, options={"unique"=true})
+     *   }
+     * )
+     */
+    class User
+    {
+        //...
+    }
+
+If you are creating a single-field index, you can simply specify an `@Index`_ or
+`@UniqueIndex`_ on a mapped property:
+
+.. code-block:: php
+
+    <?php
+
+    /** @Field(type="string") @UniqueIndex */
+    private $username;
+
+@Indexes
+--------
+
+This annotation may be used at the class level to specify an array of `@Index`_
+annotations. It is functionally equivalent to using the ``indexes`` option for
+the `@Document`_ or `@EmbeddedDocument`_ annotations.
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Document
+     * @Indexes({
+     *   @Index(keys={"username"="desc"}, options={"unique"=true})
+     * })
+     */
+    class User
+    {
+        //...
+    }
+
+@InheritanceType
+----------------
+
+This annotation must appear on the top-most class in an
+:ref:`inheritance hierarchy <inheritance_mapping>`. ``SINGLE_COLLECTION`` and
+``COLLECTION_PER_CLASS`` are currently supported.
+
+Examples:
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Document
+     * @InheritanceType("COLLECTION_PER_CLASS")
+     */
+    class Person
+    {
+        // ...
+    }
+    
+    /**
+     * @Document
+     * @InheritanceType("SINGLE_COLLECTION")
+     * @DiscriminatorField("type")
+     * @DiscriminatorMap({"person"="Person", "employee"="Employee"})
+     */
+    class Person
+    {
+        // ...
+    }
+
+@MappedSuperclass
+-----------------
+
+The annotation is used to specify classes that are parents of document classes
+and should not be managed directly. See
+:ref:`inheritance mapping <inheritance_mapping>` for additional information.
+
+.. code-block:: php
+
+    <?php
+
+    /** @MappedSuperclass */
+    class BaseDocument
+    {
+        // ...
+    }
+
+@NotSaved
+---------
+
+The annotation is used to specify properties that are loaded if they exist in
+MongoDB; however, ODM will not save the property value back to the database.
+
+.. code-block:: php
+
+    <?php
+
+    /** @NotSaved */
+    public $field;
+
+@PostLoad
+---------
+
+Marks a method on the document class to be called on the ``postLoad`` event. The
+`@HasLifecycleCallbacks`_ annotation must be present on the same class for the
+method to be registered.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Document @HasLifecycleCallbacks */
+    class Article
+    {
+        // ...
+    
+        /** @PostLoad */
+        public function postLoad()
+        {
+            // ...
+        }
+    }
+
+See :ref:`lifecycle_events` for more information.
+
+@PostPersist
+------------
+
+Marks a method on the document class to be called on the ``postPersist`` event.
+The `@HasLifecycleCallbacks`_ annotation must be present on the same class for
+the method to be registered.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Document @HasLifecycleCallbacks */
+    class Article
+    {
+        // ...
+    
+        /** @PostPersist */
+        public function postPersist()
+        {
+            // ...
+        }
+    }
+
+See :ref:`lifecycle_events` for more information.
+
+@PostRemove
+-----------
+
+Marks a method on the document class to be called on the ``postRemove`` event.
+The `@HasLifecycleCallbacks`_ annotation must be present on the same class for
+the method to be registered.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Document @HasLifecycleCallbacks */
+    class Article
+    {
+        // ...
+    
+        /** @PostRemove */
+        public function postRemove()
+        {
+            // ...
+        }
+    }
+
+See :ref:`lifecycle_events` for more information.
+
+@PostUpdate
+-----------
+
+Marks a method on the document class to be called on the ``postUpdate`` event.
+The `@HasLifecycleCallbacks`_ annotation must be present on the same class for
+the method to be registered.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Document @HasLifecycleCallbacks */
+    class Article
+    {
+        // ...
+    
+        /** @PostUpdate */
+        public function postUpdate()
+        {
+            // ...
+        }
+    }
+
+See :ref:`lifecycle_events` for more information.
+
+@PreFlush
+---------
+
+Marks a method on the document class to be called on the ``preFlush`` event. The
+`@HasLifecycleCallbacks`_ annotation must be present on the same class for the
+method to be registered.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Document @HasLifecycleCallbacks */
+    class Article
+    {
+        // ...
+    
+        /** @PreFlush */
+        public function preFlush()
+        {
+            // ...
+        }
+    }
+
+See :ref:`lifecycle_events` for more information.
+
+@PreLoad
+--------
+
+Marks a method on the document class to be called on the ``preLoad`` event. The
+`@HasLifecycleCallbacks`_ annotation must be present on the same class for the
+method to be registered.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\ODM\MongoDB\Event\PreLoadEventArgs;
+
+    /** @Document @HasLifecycleCallbacks */
+    class Article
+    {
+        // ...
+    
+        /** @PreLoad */
+        public function preLoad(PreLoadEventArgs $eventArgs)
+        {
+            // ...
+        }
+    }
+
+See :ref:`lifecycle_events` for more information.
+
+@PrePersist
+-----------
+
+Marks a method on the document class to be called on the ``prePersist`` event.
+The `@HasLifecycleCallbacks`_ annotation must be present on the same class for
+the method to be registered.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Document @HasLifecycleCallbacks */
+    class Article
+    {
+        // ...
+    
+        /** @PrePersist */
+        public function prePersist()
+        {
+            // ...
+        }
+    }
+
+See :ref:`lifecycle_events` for more information.
+
+@PreRemove
+----------
+
+Marks a method on the document class to be called on the ``preRemove`` event.
+The `@HasLifecycleCallbacks`_ annotation must be present on the same class for
+the method to be registered.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Document @HasLifecycleCallbacks */
+    class Article
+    {
+        // ...
+    
+        /** @PreRemove */
+        public function preRemove()
+        {
+            // ...
+        }
+    }
+
+See :ref:`lifecycle_events` for more information.
+
+@PreUpdate
+----------
+
+Marks a method on the document class to be called on the ``preUpdate`` event.
+The `@HasLifecycleCallbacks`_ annotation must be present on the same class for
+the method to be registered.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Document @HasLifecycleCallbacks */
+    class Article
+    {
+        // ...
+    
+        /** @PreUpdate */
+        public function preUpdated()
+        {
+            // ...
+        }
+    }
+
+See :ref:`lifecycle_events` for more information.
+
+.. _annotations_reference_reference_many:
+
+@ReferenceMany
+--------------
+
+Defines that the annotated instance variable holds a collection of referenced
+documents.
+
+Optional attributes:
+
+-
+    targetDocument - A |FQCN| of the target document.
+-
+    simple - deprecated (use ``storeAs: id``)
+-
+    storeAs - Indicates how to store the reference. ``id`` uses ``MongoId``,
+    ``dbRef`` uses a `DBRef`_ without ``$db`` value and ``dbRefWithDb`` stores
+    a full `DBRef`_ (``$ref``, ``$id``, and ``$db``). Note that ``id``
+    references are not compatible with the discriminators.
+-
+    cascade - Cascade Option
+-
+    discriminatorField - The field name to store the discriminator value within
+    the `DBRef`_ object.
+-
+    discriminatorMap - Map of discriminator values to class names.
+-
+    defaultDiscriminatorValue - A default value for discriminatorField if no value
+    has been set in the embedded document.
+-
+    inversedBy - The field name of the inverse side. Only allowed on owning side.
+-
+    mappedBy - The field name of the owning side. Only allowed on the inverse side.
+-
+    repositoryMethod - The name of the repository method to call to populate this reference.
+-
+    sort - The default sort for the query that loads the reference.
+-
+    criteria - Array of default criteria for the query that loads the reference.
+-
+    limit - Limit for the query that loads the reference.
+-
+    skip - Skip for the query that loads the reference.
+-
+    strategy - The strategy used to persist changes to the collection. Possible
+    values are ``addToSet``, ``pushAll``, ``set``, and ``setArray``. ``pushAll``
+    is the default. See :ref:`storage_strategies` for more information.
+-
+    collectionClass - A |FQCN| of class that implements ``Collection`` interface
+    and is used to hold documents. Doctrine's ``ArrayCollection`` is used by default
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @ReferenceMany(
+     *     strategy="set",
+     *     targetDocument="Documents\Item",
+     *     cascade="all",
+     *     sort={"sort_field": "asc"}
+     *     discriminatorField="type",
+     *     discriminatorMap={
+     *         "book"="Documents\BookItem",
+     *         "song"="Documents\SongItem"
+     *     },
+     *     defaultDiscriminatorValue="book"
+     * )
+     */
+    private $cart;
+
+.. _annotations_reference_reference_one:
+
+@ReferenceOne
+-------------
+
+Defines an instance variable holds a related document instance.
+
+Optional attributes:
+
+-
+    targetDocument - A |FQCN| of the target document.
+-
+    simple - deprecated (use ``storeAs: id``)
+-
+    storeAs - Indicates how to store the reference. ``id`` uses ``MongoId``,
+    ``dbRef`` uses a `DBRef`_ without ``$db`` value and ``dbRefWithDb`` stores
+    a full `DBRef`_ (``$ref``, ``$id``, and ``$db``). Note that ``id``
+    references are not compatible with the discriminators.
+-
+    cascade - Cascade Option
+-
+    discriminatorField - The field name to store the discriminator value within
+    the `DBRef`_ object.
+-
+    discriminatorMap - Map of discriminator values to class names.
+-
+    defaultDiscriminatorValue - A default value for discriminatorField if no value
+    has been set in the embedded document.
+-
+    inversedBy - The field name of the inverse side. Only allowed on owning side.
+-
+    mappedBy - The field name of the owning side. Only allowed on the inverse side.
+-
+    repositoryMethod - The name of the repository method to call to populate this reference.
+-
+    sort - The default sort for the query that loads the reference.
+-
+    criteria - Array of default criteria for the query that loads the reference.
+-
+    limit - Limit for the query that loads the reference.
+-
+    skip - Skip for the query that loads the reference.
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @ReferenceOne(
+     *     targetDocument="Documents\Item",
+     *     cascade="all",
+     *     discriminatorField="type",
+     *     discriminatorMap={
+     *         "book"="Documents\BookItem",
+     *         "song"="Documents\SongItem"
+     *     },
+     *     defaultDiscriminatorValue="book"
+     * )
+     */
+    private $cart;
+
+@ShardKey
+---------
+
+This annotation may be used at the class level to specify a shard key to be used
+for sharding the document collection.
+
+.. code-block:: php
+
+    <?php
+
+    /**
+     * @Document
+     * @ShardKey(keys={"username"="asc"})
+     */
+    class User
+    {
+        //...
+    }
+
+@UniqueIndex
+------------
+
+Alias of `@Index`_, with the ``unique`` option set by default.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Field(type="string") @UniqueIndex */
+    private $email;
+
+.. _annotations_reference_version:
+
+@Version
+--------
+
+The annotated instance variable will be used to store version information, which
+is used for pessimistic and optimistic locking. This is only compatible with
+integer and date field types, and cannot be combined with `@Id`_.
+
+.. code-block:: php
+
+    <?php
+
+    /** @Field(type="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: https://docs.mongodb.com/manual/reference/database-references/#dbrefs
+.. _geoNear command: https://docs.mongodb.com/manual/reference/command/geoNear/
+.. _GridFS: https://docs.mongodb.com/manual/core/gridfs/
+.. _MongoGridFSFile: http://php.net/manual/en/class.mongogridfsfile.php
+.. _MongoId: http://php.net/manual/en/class.mongoid.php
+.. |FQCN| raw:: html
+  <abbr title="Fully-Qualified Class Name">FQCN</abbr>
diff --git a/docs/odm-ng/reference/introduction.rst b/docs/odm-ng/reference/introduction.rst
new file mode 100644
index 0000000000..543e288045
--- /dev/null
+++ b/docs/odm-ng/reference/introduction.rst
@@ -0,0 +1,498 @@
+Introduction
+============
+
+Doctrine MongoDB Object Document Mapper is built for PHP 5.3.0+ and
+provides transparent persistence for PHP objects to the popular `MongoDB`_ database by `10gen`_.
+
+Features Overview
+-----------------
+
+-  Transparent persistence.
+-  Map one or many embedded documents.
+-  Map one or many referenced documents.
+-  Create references between documents in different databases.
+-  Map documents with Annotations, XML, YAML or plain old PHP code.
+-  Documents can be stored on the `MongoGridFS <http://www.php.net/MongoGridFS>`_.
+-  Collection per class(concrete) and single collection inheritance supported.
+-  Map your Doctrine 2 ORM Entities to the ODM and use mixed data stores.
+-  Inserts are performed using `MongoCollection::batchInsert() <http://us.php.net/manual/en/mongocollection.batchinsert.php>`_
+-  Updates are performed using atomic operators.
+
+Here is a quick example of some PHP object documents that demonstrates a few of the features:
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\Common\Collections\ArrayCollection;
+    use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+    use DateTime;
+
+    /** @ODM\MappedSuperclass */
+    abstract class BaseEmployee
+    {
+        /** @ODM\Id */
+        private $id;
+    
+        /** @ODM\Field(type="int", strategy="increment") */
+        private $changes = 0;
+    
+        /** @ODM\Field(type="collection") */
+        private $notes = array();
+    
+        /** @ODM\Field(type="string") */
+        private $name;
+    
+        /** @ODM\Field(type="int") */
+        private $salary;
+    
+        /** @ODM\Field(type="date") */
+        private $started;
+    
+        /** @ODM\Field(type="date") */
+        private $left;
+    
+        /** @ODM\EmbedOne(targetDocument="Address") */
+        private $address;
+
+        public function getId() { return $this->id; }
+
+        public function getChanges() { return $this->changes; }
+        public function incrementChanges() { $this->changes++; }
+
+        public function getNotes() { return $this->notes; }
+        public function addNote($note) { $this->notes[] = $note; }
+
+        public function getName() { return $this->name; }
+        public function setName($name) { $this->name = $name; }
+
+        public function getSalary() { return $this->salary; }
+        public function setSalary($salary) { $this->salary = (int) $salary; }
+
+        public function getStarted() { return $this->started; }
+        public function setStarted(DateTime $started) { $this->started = $started; }
+
+        public function getLeft() { return $this->left; }
+        public function setLeft(DateTime $left) { $this->left = $left; }
+
+        public function getAddress() { return $this->address; }
+        public function setAddress(Address $address) { $this->address = $address; }
+    }
+    
+    /** @ODM\Document */
+    class Employee extends BaseEmployee
+    {
+        /** @ODM\ReferenceOne(targetDocument="Documents\Manager") */
+        private $manager;
+    
+        public function getManager() { return $this->manager; }
+        public function setManager(Manager $manager) { $this->manager = $manager; }
+    }
+    
+    /** @ODM\Document */
+    class Manager extends BaseEmployee
+    {
+        /** @ODM\ReferenceMany(targetDocument="Documents\Project") */
+        private $projects;
+    
+        public __construct() { $this->projects = new ArrayCollection(); }
+
+        public function getProjects() { return $this->projects; }
+        public function addProject(Project $project) { $this->projects[] = $project; }
+    }
+    
+    /** @ODM\EmbeddedDocument */
+    class Address
+    {
+        /** @ODM\Field(type="string") */
+        private $address;
+    
+        /** @ODM\Field(type="string") */
+        private $city;
+    
+        /** @ODM\Field(type="string") */
+        private $state;
+    
+        /** @ODM\Field(type="string") */
+        private $zipcode;
+
+        public function getAddress() { return $this->address; }
+        public function setAddress($address) { $this->address = $address; }
+
+        public function getCity() { return $this->city; }
+        public function setCity($city) { $this->city = $city; }
+
+        public function getState() { return $this->state; }
+        public function setState($state) { $this->state = $state; }
+
+        public function getZipcode() { return $this->zipcode; }
+        public function setZipcode($zipcode) { $this->zipcode = $zipcode; }
+    }
+    
+    /** @ODM\Document */
+    class Project
+    {
+        /** @ODM\Id */
+        private $id;
+    
+        /** @ODM\Field(type="string") */
+        private $name;
+    
+        public function __construct($name) { $this->name = $name; }
+
+        public function getId() { return $this->id; }
+
+        public function getName() { return $this->name; }
+        public function setName($name) { $this->name = $name; }
+    }
+
+Now those objects can be used just like you weren't using any
+persistence layer at all and can be persisted transparently by
+Doctrine:
+
+.. code-block:: php
+
+    <?php
+    
+    use Documents\Employee;
+    use Documents\Address;
+    use Documents\Project;
+    use Documents\Manager;
+    use DateTime;
+
+    $employee = new Employee();
+    $employee->setName('Employee');
+    $employee->setSalary(50000);
+    $employee->setStarted(new DateTime());
+    
+    $address = new Address();
+    $address->setAddress('555 Doctrine Rd.');
+    $address->setCity('Nashville');
+    $address->setState('TN');
+    $address->setZipcode('37209');
+    $employee->setAddress($address);
+    
+    $project = new Project('New Project');
+    $manager = new Manager();
+    $manager->setName('Manager');
+    $manager->setSalary(100000);
+    $manager->setStarted(new DateTime());
+
+    $dm->persist($employee);
+    $dm->persist($address);
+    $dm->persist($project);
+    $dm->persist($manager);
+    $dm->flush();
+
+The above would insert the following:
+
+::
+
+    Array
+    (
+        [000000004b0a33690000000001c304c6] => Array
+            (
+                [name] => New Project
+            )
+    
+    )
+    Array
+    (
+        [000000004b0a33660000000001c304c6] => Array
+            (
+                [changes] => 0
+                [notes] => Array
+                    (
+                    )
+    
+                [name] => Manager
+                [salary] => 100000
+                [started] => MongoDate Object
+                    (
+                        [sec] => 1275265048
+                        [usec] => 0
+                    )
+    
+                [projects] => Array
+                    (
+                        [0] => Array
+                            (
+                                [$ref] => projects
+                                [$id] => 4c0300188ead0e947a000000
+                                [$db] => my_db
+                            )
+    
+                    )
+    
+            )
+    
+    )
+    Array
+    (
+        [000000004b0a336a0000000001c304c6] => Array
+            (
+                [changes] => 0
+                [notes] => Array
+                    (
+                    )
+    
+                [name] => Employee
+                [salary] => 50000
+                [started] => MongoDate Object
+                    (
+                        [sec] => 1275265048
+                        [usec] => 0
+                    )
+    
+                [address] => Array
+                    (
+                        [address] => 555 Doctrine Rd.
+                        [city] => Nashville
+                        [state] => TN
+                        [zipcode] => 37209
+                    )
+    
+            )
+    
+    )
+
+If we update a property and call ``->flush()`` again we'll get an
+efficient update query using the atomic operators:
+
+.. code-block:: php
+
+    <?php
+    $newProject = new Project('Another Project');
+    $manager->setSalary(200000);
+    $manager->addNote('Gave user 100k a year raise');
+    $manager->incrementChanges(2);
+    $manager->addProject($newProject);
+    
+    $dm->persist($newProject);
+    $dm->flush();
+
+The above could would produce an update that looks something like
+this:
+
+::
+
+    Array
+    (
+        [$inc] => Array
+            (
+                [changes] => 2
+            )
+    
+        [$pushAll] => Array
+            (
+                [notes] => Array
+                    (
+                        [0] => Gave user 100k a year raise
+                    )
+    
+                [projects] => Array
+                    (
+                        [0] => Array
+                            (
+                                [$ref] => projects
+                                [$id] => 4c0310718ead0e767e030000
+                                [$db] => my_db
+                            )
+    
+                    )
+    
+            )
+    
+        [$set] => Array
+            (
+                [salary] => 200000
+            )
+    
+    )
+
+This is a simple example, but it demonstrates well that you can
+transparently persist PHP objects while still utilizing the
+atomic operators for updating documents! Continue reading to learn
+how to get the Doctrine MongoDB Object Document Mapper setup and
+running!
+
+Setup
+-----
+
+Before we can begin, we'll need to install the Doctrine MongoDB ODM library and
+its dependencies. The easiest way to do this is with `Composer`_:
+
+::
+
+    $ composer require "doctrine/mongodb-odm"
+
+Once ODM and its dependencies have been downloaded, we can begin by creating a
+``bootstrap.php`` file in our project's root directory, where Composer's
+``vendor/`` directory also resides. Let's start by importing some of the classes
+we'll use:
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\MongoDB\Connection;
+    use Doctrine\ODM\MongoDB\Configuration;
+    use Doctrine\ODM\MongoDB\DocumentManager;
+    use Doctrine\ODM\MongoDB\Mapping\Driver\AnnotationDriver;
+
+The first bit of code will be to import Composer's autoloader, so these classes
+can actually be loaded:
+
+.. code-block:: php
+
+    <?php
+
+    // ...
+
+    if ( ! file_exists($file = __DIR__.'/vendor/autoload.php')) {
+        throw new RuntimeException('Install dependencies to run this script.');
+    }
+
+    $loader = require_once $file;
+
+Note that instead of simply requiring the file, we assign its return value to
+the ``$loader`` variable. Assuming document classes will be stored in the
+``Documents/`` directory (with a namespace to match), we can register them with
+the autoloader like so:
+
+.. code-block:: php
+
+    <?php
+
+    // ...
+
+    $loader->add('Documents', __DIR__);
+
+Ultimately, our application will utilize ODM through its ``DocumentManager``
+class. Before we can instantiate a ``DocumentManager``, we need to construct the
+``Connection`` and ``Configuration`` objects required by its factory method:
+
+.. code-block:: php
+
+    <?php
+
+    // ...
+
+    $connection = new Connection();
+    $config = new Configuration();
+
+Next, we'll specify some essential configuration options. The following assumes
+that we will store generated proxy and hydrator classes in the ``Proxies/`` and
+``Hydrators/`` directories, respectively. Additionally, we'll define a default
+database name to use for document classes that do not specify a database in
+their mapping.
+
+.. code-block:: php
+
+    <?php
+
+    // ...
+
+    $config->setProxyDir(__DIR__ . '/Proxies');
+    $config->setProxyNamespace('Proxies');
+    $config->setHydratorDir(__DIR__ . '/Hydrators');
+    $config->setHydratorNamespace('Hydrators');
+    $config->setDefaultDB('doctrine_odm');
+
+The easiest way to define mappings for our document classes is with annotations.
+We'll need to specify an annotation driver in our configuration (with one or
+more paths) and register the annotations for the driver:
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\Common\Annotations\AnnotationRegistry;
+
+    // ...
+
+    $config->setMetadataDriverImpl(AnnotationDriver::create(__DIR__ . '/Documents'));
+
+    $loader = require_once('path/to/vendor/autoload.php');
+
+    AnnotationRegistry::registerLoader([$loader, 'loadClass']);
+
+At this point, we have everything necessary to construct a ``DocumentManager``:
+
+.. code-block:: php
+
+    <?php
+
+    // ...
+
+    $dm = DocumentManager::create($connection, $config);
+
+The final ``bootstrap.php`` file should look like this:
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\Common\Annotations\AnnotationRegistry;
+    use Doctrine\MongoDB\Connection;
+    use Doctrine\ODM\MongoDB\Configuration;
+    use Doctrine\ODM\MongoDB\DocumentManager;
+    use Doctrine\ODM\MongoDB\Mapping\Driver\AnnotationDriver;
+
+    if ( ! file_exists($file = __DIR__.'/vendor/autoload.php')) {
+        throw new RuntimeException('Install dependencies to run this script.');
+    }
+
+    $loader = require_once $file;
+    $loader->add('Documents', __DIR__);
+
+    AnnotationRegistry::registerLoader([$loader, 'loadClass']);
+
+    $connection = new Connection();
+
+    $config = new Configuration();
+    $config->setProxyDir(__DIR__ . '/Proxies');
+    $config->setProxyNamespace('Proxies');
+    $config->setHydratorDir(__DIR__ . '/Hydrators');
+    $config->setHydratorNamespace('Hydrators');
+    $config->setDefaultDB('doctrine_odm');
+    $config->setMetadataDriverImpl(AnnotationDriver::create(__DIR__ . '/Documents'));
+
+    $dm = DocumentManager::create($connection, $config);
+
+That is it! Your ``DocumentManager`` instance is ready to be used!
+
+Using PHP 7
+-----------
+
+You can use Doctrine MongoDB ODM with PHP 7, but there are a few extra steps during
+the installation. Since the legacy driver (referred to as ``ext-mongo``) is not
+available on PHP 7, you will need the new driver (``ext-mongodb``) installed and
+use a polyfill to provide the API of the legacy driver.
+
+To do this, you have to require ``alcaeus/mongo-php-adapter`` before adding a composer
+dependency to ODM. To do this, run the following command:
+
+::
+
+    $ composer require "alcaeus/mongo-php-adapter"
+
+Next, manually add a ``provide`` section to your ``composer.json``:
+
+.. code-block:: json
+
+    "provide": {
+        "ext-mongo": "1.6.14"
+    }
+
+This section needs to be added to work around a composer issue with libraries
+providing platform packages (such as ``ext-mongo``). Now, you may install ODM as
+described above:
+
+::
+
+    $ composer require "doctrine/mongodb-odm"
+
+.. _MongoDB: https://www.mongodb.com/
+.. _10gen: http://www.10gen.com
+.. _Composer: http://getcomposer.org/
diff --git a/docs/odm-ng/tutorials/getting-started.rst b/docs/odm-ng/tutorials/getting-started.rst
new file mode 100644
index 0000000000..c4077700d6
--- /dev/null
+++ b/docs/odm-ng/tutorials/getting-started.rst
@@ -0,0 +1,304 @@
+Getting Started
+===============
+
+Doctrine is a project that aims to handle the persistence of your
+domain model in a non-interfering way. Non-relational or no-sql
+databases like MongoDB give you flexibility of building data store
+around your object model and not vise versa. You can read more on the
+initial configuration and setup in :doc:`Introduction to MongoDB Object
+Document Mapper <../reference/introduction>`. This section will give you a basic
+overview of what could be accomplished using Doctrine MongoDB ODM.
+
+Example Model: Simple Blog
+--------------------------
+
+To create the simplest example, let’s assume the following in a simple blog web application:
+
+-  Blog has a user.
+-  Blog user can make blog posts
+
+A first prototype
+-----------------
+
+For the above mentioned example, something as simple as this could be modeled with plain PHP classes.
+First define the ``User`` document:
+
+.. code-block:: php
+
+    <?php
+
+    namespace Documents;
+
+    class User
+    {
+        private $name;
+        private $email;
+        private $posts = array();
+
+        // ...
+    }
+
+Now define the ``BlogPost`` document:
+
+.. code-block:: php
+
+    <?php
+
+    namespace Documents;
+
+    class BlogPost
+    {
+        private $title;
+        private $body;
+        private $createdAt;
+
+        // ...
+    }
+
+Persistent Models
+-----------------
+
+To make the above classes persistent, all we need to do is provide Doctrine with some mapping
+information so that it knows how to consume the objects and persist them to the database.
+
+You can provide your mapping information in Annotations, XML, or YAML:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+
+        /** @ODM\Document */
+        class User
+        {
+            /** @ODM\Id */
+            private $id;
+
+            /** @ODM\Field(type="string") */
+            private $name;
+
+            /** @ODM\Field(type="string") */
+            private $email;
+
+            /** @ODM\ReferenceMany(targetDocument="BlogPost", cascade="all") */
+            private $posts = array();
+
+            // ...
+        }
+
+        /** @ODM\Document */
+        class BlogPost
+        {
+            /** @ODM\Id */
+            private $id;
+
+            /** @ODM\Field(type="string") */
+            private $title;
+
+            /** @ODM\Field(type="string") */
+            private $body;
+
+            /** @ODM\Field(type="date") */
+            private $createdAt;
+
+            // ...
+        }
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8"?>
+        <doctrine-mongo-mapping xmlns="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping"
+                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                        xsi:schemaLocation="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping
+                        http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd">
+          <document name="Documents\User">
+                <field fieldName="id" id="true" />
+                <field fieldName="name" type="string" />
+                <field fieldName="email" type="string" />
+                <reference-many fieldName="posts" targetDocument="Documents\BlogPost">
+                    <cascade>
+                        <all/>
+                    </cascade>
+                </reference-many>
+          </document>
+        </doctrine-mongo-mapping>
+
+        <?xml version="1.0" encoding="UTF-8"?>
+        <doctrine-mongo-mapping xmlns="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping"
+                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                        xsi:schemaLocation="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping
+                        http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd">
+          <document name="Documents\BlogPost">
+                <field fieldName="id" id="true" />
+                <field fieldName="title" type="string" />
+                <field fieldName="body" type="string" />
+                <field fieldName="createdAt" type="date" />
+          </document>
+        </doctrine-mongo-mapping>
+
+    .. code-block:: yaml
+
+        Documents\User:
+          fields:
+            id:
+              type: id
+              id: true
+            name:
+              type: string
+            email:
+              type: string
+          referenceMany:
+            posts:
+              targetDocument: Documents\BlogPost
+              cascade: all
+
+        Documents\BlogPost:
+          fields:
+            id:
+              type: id
+              id: true
+            title:
+              type: string
+            body:
+              type: string
+            createdAt:
+              type: date
+
+That’s it, we have our models, and we can save and retrieve them. Now
+all we need to do is to properly instantiate the ``DocumentManager``
+instance. Read more about setting up the Doctrine MongoDB ODM in the
+:doc:`Introduction to MongoDB Object Document Mapper <../reference/introduction>`:
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\Common\Annotations\AnnotationRegistry;
+    use Doctrine\MongoDB\Connection;
+    use Doctrine\ODM\MongoDB\Configuration;
+    use Doctrine\ODM\MongoDB\DocumentManager;
+    use Doctrine\ODM\MongoDB\Mapping\Driver\AnnotationDriver;
+
+    $loader = require_once('path/to/vendor/autoload.php');
+
+    AnnotationRegistry::registerLoader([$loader, 'loadClass']);
+
+    $config = new Configuration();
+    $config->setProxyDir('/path/to/generate/proxies');
+    $config->setProxyNamespace('Proxies');
+    $config->setHydratorDir('/path/to/generate/hydrators');
+    $config->setHydratorNamespace('Hydrators');
+    $config->setMetadataDriverImpl(AnnotationDriver::create('/path/to/document/classes'));
+
+    $dm = DocumentManager::create(new Connection(), $config);
+
+Usage
+-----
+
+Here is how you would use your models now:
+
+.. code-block:: php
+
+    <?php
+
+    // ...
+
+    // create user
+    $user = new User();
+    $user->setName('Bulat S.');
+    $user->setEmail('email@example.com');
+
+    // tell Doctrine 2 to save $user on the next flush()
+    $dm->persist($user);
+
+    // create blog post
+    $post = new BlogPost();
+    $post->setTitle('My First Blog Post');
+    $post->setBody('MongoDB + Doctrine 2 ODM = awesomeness!');
+    $post->setCreatedAt(new DateTime());
+
+    $user->addPost($post);
+
+    // store everything to MongoDB
+    $dm->flush();
+
+.. note::
+
+    Note that you do not need to explicitly call persist on the ``$post`` because the operation
+    will cascade on to the reference automatically.
+
+Now if you did everything correctly, you should have those two objects
+stored in MongoDB in correct collections and databases. You can use the
+`php-mongodb-admin project, hosted on github`_ to look at your
+``BlogPost`` collection, where you will see only one document:
+
+::
+
+    Array
+    (
+        [_id] => 4bec5869fdc212081d000000
+        [title] => My First Blog Post
+        [body] => MongoDB + Doctrine 2 ODM = awesomeness!
+        [createdAt] => MongoDate Object
+            (
+                [sec] => 1273723200
+                [usec] => 0
+            )
+    )
+
+And the ``User`` collection would consist of the following:
+
+::
+
+    Array
+    (
+        [_id] => 4bec5869fdc212081d010000
+        [name] => Bulat S.
+        [email] => email@example.com
+        [posts] => Array
+            (
+                [0] => Array
+                    (
+                        [$ref] => blog_posts
+                        [$id] => 4bec5869fdc212081d000000
+                        [$db] => test_database
+                    )
+            )
+    )
+
+You can retrieve the user later by its identifier:
+
+.. code-block:: php
+
+    <?php
+
+    // ...
+
+    $userId = '....';
+    $user = $dm->find('User', $userId);
+
+Or you can find the user by name even:
+
+.. code-block:: php
+
+    <?php
+
+    $user = $dm->getRepository('User')->findOneByName('Bulat S.');
+
+If you want to iterate over the posts the user references it is as easy as the following:
+
+.. code-block:: php
+
+    <?php
+
+    $posts = $dm->getPosts();
+    foreach ($posts as $post) {
+    }
+
+You will notice that working with objects is nothing magical and you only have access to the properties,
+getters and setters that you have defined yourself so the semantics are very clear. You can continue
+reading about the MongoDB in the :doc:`Introduction to MongoDB Object Document Mapper <../reference/introduction>`.
+
+.. _php-mongodb-admin project, hosted on github: http://github.com/jwage/php-mongodb-admin