Merge pull request #620 from TomHAnderson/doc/editor-4

entity manager editing

docs/entity-manager.rst

@@ -24,6 +24,7 @@ Container
 .. code-block:: php
 
   app('em'); // alias
+  app('Doctrine\ORM\EntityManager');
   app('Doctrine\ORM\EntityManagerInterface');
 
 
@@ -67,7 +68,9 @@ you want, you'll have to inject ``Doctrine\Common\Persistence\ManagerRegistry``
 Finding entities
 ----------------
 
-    Note: for making the examples more expressive, we will use the facade.
+.. note::
+
+    For making the examples more expressive, we will use the facade.
     However I do recommend to leverage dependency injection as much as possible.
     This makes mocking the EntityManager in your tests a lot easier.
 
@@ -77,9 +80,9 @@ can uniquely identify each article by that id.
 
 In the example below, the Article entity is fetched from the entity manager
 twice, but was modified after the first find. Doctrine2 keeps track of all
-those changes. This pattern is called `Identity Map pattern`, which means
-that Doctrine keeps a map of each entity and ids that have been retrieved
-per request and keeps return the same instances on every find.
+those changes. This pattern is the `Identity Map Pattern <https://martinfowler.com/eaaCatalog/identityMap.html>`_,
+which means that Doctrine keeps a map of each entity and ids that have been
+retrieved per request and keeps return the same instances on every find.
 
 ``$article`` and ``$article1`` will be identical, eventhough we haven't
 persisted the changes to ``$article`` to the database yet.
@@ -99,18 +102,21 @@ persisted the changes to ``$article`` to the database yet.
 Persisting
 ==========
 
-By passing the entity through the ``persist`` method of the EntityManager,
-that entity becomes MANAGED, which means that its persistence is from now
+By passing the entity through the ``$entityManager->persist`` method of the EntityManager,
+that entity becomes managed, which means that its persistence is from now
 on managed by an EntityManager. As a result the persistent state of such
 an entity will subsequently be properly synchronised with the database
-when ``EntityManager::flush()`` is invoked.
+when ``$entityManager->flush()`` is invoked.
+
+.. note::
 
-    Note: ``persist()`` doesn't do any ``INSERT`` queries.
+  ``$entityManager->persist()`` doesn't execuate an ``INSERT`` query
+  immediately.
 
 .. code-block:: php
 
-  $article = new Article;
-  $article->setTitle('Let\'s learn about persisting');
+  $article = new Article();
+  $article->title = 'Let\'s learn about persisting';
 
   EntityManager::persist($article);
   EntityManager::flush();
@@ -128,17 +134,18 @@ persist these changes to the database.
   // Flush all changes
   EntityManager::flush();
 
-  // Only flush changes of given entity
+  // Only flush changes of given entity.
+  // If you have to use this, you're doing it wrong.
   EntityManager::flush($article);
 
 
 Removing (deleting)
 ===================
 
 An entity can be removed from persistent storage by passing it to the
-``remove($entity)`` method. By applying the remove operation on some entity,
+``$entityManager->remove($entity)`` method. By applying the remove operation on some entity,
 that entity becomes REMOVED, which means that its persistent state will be
-deleted once ``flush()`` is invoked.
+deleted once ``$entityManager->flush()`` is invoked.
 
 .. code-block:: php