doctrine.rst - suggestions by ryan symfony#1

Author: timglabisch

reference/configuration/doctrine.rst

@@ -502,11 +502,15 @@ Keep in mind that you can't use both syntaxes at the same time.
 Custom Mapping
 --------------
 
-It's possible to not rely on the auto mapping and set all the configuration
-on your own.
+Doctrine's ```auto_mapping`` feature loads annotation configuration from the
+``Entity/`` directory of each bundle *and* looks for other formats (e.g. YAML, XML)
+in the ``Resources/config/doctrine``directory.
 
-For example, you can overwrite the configuration directory for a given bundle.
-Keep in mind that the bundle you want to overwrite has to exist.
+If you store metadata somewhere else, you can define your own mappings,
+where you tell Doctrine exactly *where* to look, along with some other information.
+
+For example, suppose you decide to store your configuration for `AppBundle` entities
+in the ``app/Resources/config/doctrine`` directory instead
 
 .. configuration-block::
 
@@ -520,7 +524,7 @@ Keep in mind that the bundle you want to overwrite has to exist.
                 mappings:
                     # ...
                     AppBundle:
-                        dir: Resources/config/doctrine
+                        dir: SomeResources/config/doctrine
                         
     .. code-block:: xml
     
@@ -530,7 +534,7 @@ Keep in mind that the bundle you want to overwrite has to exist.
         
             <doctrine:config>
                 <doctrine:orm auto-mapping="true">
-                    <mapping name="AppBundle" dir="Resources/config/doctrine" />
+                    <mapping name="AppBundle" dir="SomeResources/config/doctrine" />
                 </doctrine:orm>
             </doctrine:config>
         </container>
@@ -541,13 +545,16 @@ Keep in mind that the bundle you want to overwrite has to exist.
             'orm' => array(
                 'auto_mapping' => true,
                 'mappings' => array(
-                    'AppBundle' => array('dir' => 'Resources/config/doctrine'),
+                    'AppBundle' => array('dir' => 'SomeResources/config/doctrine'),
                 ),
             ),
         ));
 
 You can also create new mappings. For example outside of the Symfony folder.
 
+For example, the following looks for entity classes in the ``App\Entity`` namespace in the
+`src/Entity` directory and gives them an ``App`` alias (so you can say things like `App:Post`):
+
 .. configuration-block::
 
     .. code-block:: yaml
@@ -612,9 +619,10 @@ The ``ResourceConfigurationDirectory``, by default, points to
 ``Resources/config/doctrine``.
 
 The bundle looks for (in this order) XML, YAML and PHP files.
-Every bundle can by default just register one ``MetadataDriver``.
+Using the ``automapping`` feature, every bundle can have only one configuration format.
+The bundle will stop as soon as it locates one.
 
-If it wasn't possible to determine a ``MetadataDriver``, it will check if
+If it wasn't possible to determine a configuration format, it will check if
 there is an ``Entity`` folder in the bundle's root directory.
 If the folder does not exist, Doctrine will fall back to using an annotation driver.