minor #6511 [DependencyInjection] Improved "optional argument" documentation (dantleech)

This PR was merged into the 2.3 branch.

Discussion
----------

[DependencyInjection] Improved "optional argument" documentation

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | yes
| Applies to    | 2.3+/master

The `on-ignore=null` behavior of the DI container arguments is currently undocumented.

TODO:

- Add `- When used on a collection argument, the argument will be removed.` list item in master.

Commits
-------

84b1037 Improved "optional argument" documentation"

Author: xabbuh

book/service_container.rst

@@ -744,15 +744,75 @@ Injecting the dependency by the setter method just needs a change of syntax:
     and "setter injection". The Symfony service container also supports
     "property injection".
 
-Making References optional
+Making References Optional
 --------------------------
 
 Sometimes, one of your services may have an optional dependency, meaning
 that the dependency is not required for your service to work properly. In
 the example above, the ``app.mailer`` service *must* exist, otherwise an exception
 will be thrown. By modifying the ``app.newsletter_manager`` service definition,
-you can make this reference optional. The container will then inject it if
-it exists and do nothing if it doesn't:
+you can make this reference optional, there are two strategies for doing this.
+
+Setting Missing Dependencies to null
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the ``null`` strategy to explicitly set the argument to ``null``
+if the service does not exist:
+
+.. configuration-block::
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="app.mailer">
+                <!-- ... -->
+                </service>
+
+                <service id="app.newsletter_manager" class="AppBundle\Newsletter\NewsletterManager">
+                    <argument type="service" id="app.mailer" on-invalid="null" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        use Symfony\Component\DependencyInjection\Definition;
+        use Symfony\Component\DependencyInjection\Reference;
+        use Symfony\Component\DependencyInjection\ContainerInterface;
+
+        $container->setDefinition('app.mailer', ...);
+
+        $container->setDefinition('app.newsletter_manager', new Definition(
+            'AppBundle\Newsletter\NewsletterManager',
+            array(
+                new Reference(
+                    'app.mailer',
+                    ContainerInterface::NULL_ON_INVALID_REFERENCE
+                )
+            )
+        ));
+
+.. note::
+
+    The "null" strategy is not currently supported by the YAML driver.
+
+Ignoring Missing Dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The behavior of ignoring missing dependencies is the same as the "null"
+behavior except when used within a method call, in which case the method call
+itself will be removed.
+
+In the following example the container will inject a service using a method
+call if the service exists and remove the method call if it does not:
 
 .. configuration-block::
 
@@ -779,7 +839,9 @@ it exists and do nothing if it doesn't:
                 </service>
 
                 <service id="app.newsletter_manager" class="AppBundle\Newsletter\NewsletterManager">
-                    <argument type="service" id="app.mailer" on-invalid="ignore" />
+                    <call method="setMailer">
+                        <argument type="service" id="my_mailer" on-invalid="ignore"/>
+                    </call>
                 </service>
             </services>
         </container>
@@ -794,13 +856,12 @@ it exists and do nothing if it doesn't:
         $container->setDefinition('app.mailer', ...);
 
         $container->setDefinition('app.newsletter_manager', new Definition(
-            'AppBundle\Newsletter\NewsletterManager',
-            array(
-                new Reference(
-                    'app.mailer',
-                    ContainerInterface::IGNORE_ON_INVALID_REFERENCE
-                )
-            )
+            'AppBundle\Newsletter\NewsletterManager'
+        ))->addMethodCall('setMailer', array(
+            new Reference(
+                'my_mailer',
+                ContainerInterface::IGNORE_ON_INVALID_REFERENCE
+            ),
         ));
 
 In YAML, the special ``@?`` syntax tells the service container that the dependency