[DI] Add some documentation for the deprecation feature

components/dependency_injection/advanced.rst

@@ -218,3 +218,47 @@ 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 bar is deprecated. You should stop using it, as it will soon be removed.
+    
+    .. code-block:: xml
+
+        <service id="bar" class="stdClass">
+            <deprecated>The service bar 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 %service_id% 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 message is optionnal, so you can basically set only the status, a
+   default message will be used instead.
+
+.. note::
+   The message is actually a template message, which will replace occurrences
+   of ``%service_id%`` by the service's id. While this is not really necessary
+   while using the xml or yaml loaders, it should be used for the php definition.
+
+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.