Fixes after great review

Author: wouterj

service_container/definitions.rst

@@ -5,7 +5,9 @@ Working with Container Service Definitions
 ==========================================
 
 Service definitions are the instructions describing how the container should
-build a service. They are not the actual services used by your applications
+build a service. They are not the actual services used by your applications.
+The container will create the actual class instances based on the configuration
+in the definition.
 
 Getting and Setting Service Definitions
 ---------------------------------------

service_container/service_decoration.rst

@@ -5,7 +5,7 @@ How to Decorating Services
 ==========================
 
 When overriding an existing definition (e.g. when applying the `Decorator pattern`_),
-the old service is lost:
+the original service is lost:
 
 .. configuration-block::
 
@@ -15,8 +15,8 @@ the old service is lost:
             app.mailer:
                 class: AppBundle\Mailer
 
-            # this is going to replace the old app.mailer definition with the
-            # new one, the old definition is lost
+            # this replaces the old app.mailer definition with the new one, the
+            # old definition is lost
             app.mailer:
                 class AppBundle\DecoratingMailer
 
@@ -31,8 +31,8 @@ the old service is lost:
 
                 <service id="app.mailer" class="AppBundle\Mailer" />
 
-                <!-- this is going to replace the old app.mailer definition
-                     with the new one, the old definition is lost -->
+                <!-- this replaces the old app.mailer definition with the new
+                     one, the old definition is lost -->
                 <service id="app.mailer" class="AppBundle\DecoratingMailer" />
 
             </service>
@@ -42,8 +42,8 @@ the old service is lost:
 
         $container->register('mailer', 'AppBundle\Mailer');
 
-        // this is going to replace the old app.mailer definition with the new
-        // one, the old definition is lost
+        // this replaces the old app.mailer definition with the new one, the
+        // old definition is lost
         $container->register('mailer', 'AppBundle\DecoratingMailer');
 
 Most of the time, that's exactly what you want to do. But sometimes,
@@ -97,8 +97,8 @@ a reference of the old one  as ``app.decorating_mailer.inner``:
             ->setPublic(false)
         ;
 
-Here is what's going on here: the decorates option tells the container that the
-``app.decorating_mailer`` service should replace the ``app.mailer`` service. By
+Here is what's going on here: the ``decorates`` option tells the container that
+the ``app.decorating_mailer`` service replaces the ``app.mailer`` service. By
 convention, the old ``app.mailer`` service is renamed to
 ``app.decorating_mailer.inner``, so you can inject it into your new service.
 

service_container/synthetic_services.rst

@@ -4,8 +4,8 @@
 How to Inject Instances into the Container
 ------------------------------------------
 
-When using the container in your application, you sometimes need to inject
-an instance instead of configuring the container to create a new instance.
+In some applications, you may need to inject a class instance as service,
+instead of configuring the container to create a new instance.
 
 For instance, the ``kernel`` service in Symfony is injected into the container
 from within the ``Kernel`` class::

service_container/tags.rst

@@ -69,7 +69,7 @@ parameter).
 Creating custom Tags
 --------------------
 
-Tags on there own don't actually alter the functionality of your services in
+Tags on their own don't actually alter the functionality of your services in
 any way. But if you choose to, you can ask a container builder for a list of
 all services that were tagged with some specific tag. This is useful in
 compiler passes where you can find these services and use or modify them in