[#4656] Re-reading private service section

components/dependency_injection/advanced.rst

@@ -10,29 +10,19 @@ Marking Services as public / private
 When defining services, you'll usually want to be able to access these definitions
 within your application code. These services are called ``public``. For example,
 the ``doctrine`` service registered with the container when using the DoctrineBundle
-is a public service as you can access it via::
+is a public service. This means that you can fetch it from the container
+using the ``get()`` method::
 
    $doctrine = $container->get('doctrine');
 
-However, there are use-cases when you don't want a service to be public. This
-is common when a service is only defined because it could be used as an
-argument for another service.
+In some cases, a service *only* exists to be injected into another service
+and is *not* intended to be fetched directly from the container as shown
+above. 
 
 .. _inlined-private-services:
 
-Since a container is not able to detect if a service is retrieved from inside
-the container or the outside, a private service may still be retrieved using
-the ``get()`` method.
-
-What makes private services special, is that they are converted from services
-to inlined instantiation (e.g. ``new PrivateThing()``) when they are only
-injected once, to increase the container performance. This means that you can
-never be sure if a private service exists in the container.
-
-Simply said: A service will be private when you do not want to access it
-directly from your code.
-
-Here is an example:
+In these cases, to get a minor performance boost, you can set the service
+to be *not* public (i.e. private):
 
 .. configuration-block::
 
@@ -63,11 +53,19 @@ Here is an example:
         $definition->setPublic(false);
         $container->setDefinition('foo', $definition);
 
-Now that the service is private, you *should not* call (should not means, this
-*might* fail, see the explaination above)::
+What makes private services special is that they are converted from services
+to inlined instantiations (e.g. ``new PrivateThing()``) if they are only
+injected once. This increases the container's performance.
+
+Now that the service is private, you *should not* fetch the service directly
+from the container::
 
     $container->get('foo');
 
+This *may or may not work*, depending on if the service could be inlined.
+Simply said: A service can be marked as private if you do not want to access
+it directly from your code.
+
 However, if a service has been marked as private, you can still alias it (see
 below) to access this service (via the alias).