minor #4748 Re-reading private service section (weaverryan)

weaverryan · weaverryan · commit 43543bb0fbb0 · 2015-01-04T17:46:39.000-05:00
This PR was merged into the 2.3 branch. Discussion ---------- Re-reading private service section | Q | A | --- | --- | Doc fix? | yes | New docs? | kind of | Applies to | all | Fixed tickets | n/a Hi guys! This follows #4656. I merged that, but then realized that if you read the wider section, the top was still talking about private services as if their benefit was to *not* allow fetching directly (whereas the true emphasis now is on performance, and how `get()` may or may not work. Thanks! Commits ------- 8f5e210 Re-wording based on Wouter's recommendation 0f86a86 [#4656] Re-reading private service section
diff --git a/components/dependency_injection/advanced.rst b/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, if they are only injected once,
+they are converted from services to inlined instantiations (e.g. ``new PrivateThing()``).
+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).
 
