[DI] Add some documentation for the deprecation feature

Author: Taluu

components/dependency_injection/advanced.rst

@@ -218,3 +218,54 @@ You can change the inner service name if you want to:
             ->addArgument(new Reference('bar.wooz'))
             ->setPublic(false)
             ->setDecoratedService('foo', 'bar.wooz');
+
+Deprecating Services
+--------------------
+
+Once you have decided to deprecate the use of a service (because it is outdated,
+or you decided not to use and maintain it anymore), you can deprecate its 
+definition:
+
+.. configuration-block::
+
+   .. code-block: yaml
+      
+      bar:
+         class: stdClass
+         deprecated: true
+         deprecation_message: The '%service_id%' service is deprecated. You should stop using it, as it will soon be removed.
+    
+    .. code-block:: xml
+
+        <service id="bar" class="stdClass">
+            <deprecated>The '%service_id%' service is deprecated. You should stop using it, as it will soon be removed.</deprecated>
+        </service>
+
+    .. code-block:: php
+
+        $container->register('bar', 'stdClass')
+            ->setDeprecated(true, 'The \'%service_id%\' service is deprecated. You should stop using it, as it will soon be removed.');
+
+Now, every time a service is created using this deprecated definition will
+trigger a deprecation error, advising you to stop or change your uses of that
+service.
+
+.. note::
+   The deprecation message is optional. If not set, Symfony will show a default
+   message ``The '%service_id%' service is deprecated. You should stop using it,
+   as it will soon be removed.``.
+
+.. note::
+   The message is actually a template message, which will replace occurrences
+   of ``%service_id%`` by the service's id. You **must** have at least one
+   occurrence of ``%service_id%`` in your template message.
+
+.. note::
+   We really recommand you to fill the template message, to avoid a message that
+   could be too generic such as the default one. A good message explains
+   (shortly) why this service was deprecated, from which version and until when
+   it will be maintained.
+
+For services decorators (see above), if the definition does not modify the
+deprecated status, it will inherit the status from the definition that is
+decorated.