Use the \".. deprecated::\" directive for deprecations

Author: OskarStark

bundles/extension.rst

@@ -130,7 +130,7 @@ read more about it, see the ":doc:`/bundles/configuration`" article.
 Adding Classes to Compile
 -------------------------
 
-.. versionadded:: 3.3
+.. deprecated:: 3.3
 
     This technique is discouraged and the ``addClassesToCompile()`` method was
     deprecated in Symfony 3.3 because modern PHP versions make it unnecessary.

components/console/events.rst

@@ -86,7 +86,7 @@ C/C++ standard.::
 The ``ConsoleEvents::EXCEPTION`` Event
 --------------------------------------
 
-.. versionadded:: 3.3
+.. deprecated:: 3.3
 
     The ``ConsoleEvents::EXCEPTION`` event was deprecated in Symfony 3.3. Use
     the ``ConsoleEvents::ERROR`` event instead.

components/event_dispatcher/container_aware_dispatcher.rst

@@ -4,7 +4,7 @@
 The Container Aware Event Dispatcher
 ====================================
 
-.. versionadded:: 3.3
+.. deprecated:: 3.3
 
     The ``ContainerAwareEventDispatcher`` class has been deprecated in Symfony 3.3
     and it will be removed in Symfony 4.0. Use ``EventDispatcher`` with

components/filesystem/lock_handler.rst

@@ -1,7 +1,7 @@
 LockHandler
 ===========
 
-.. versionadded:: 3.4
+.. deprecated:: 3.4
 
     The ``LockHandler`` class was deprecated in Symfony 3.4 and it will be
     removed in Symfony 4.0. Use :ref:`SemaphoreStore <lock-store-semaphore>`

configuration/external_parameters.rst

@@ -122,7 +122,7 @@ of the following:
 
 .. tip::
 
-    .. versionadded:: 3.3
+    .. deprecated:: 3.3
 
         The support of the special ``SYMFONY__`` environment variables was
         deprecated in Symfony 3.3 and it will be removed in 4.0. Instead of

contributing/documentation/format.rst

@@ -168,21 +168,24 @@ of the linked resource (``namespace``, ``class`` or ``method``):
 
     :phpfunction:`iterator_to_array`
 
-New Features or Behavior Changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+New Features, Behavior Changes or Deprecations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you're documenting a brand new feature or a change that's been made in
-Symfony, you should precede your description of the change with a
-``.. versionadded:: 3.x`` directive and a short description:
+If you are documenting a brand new feature, a change or a deprecation that's
+been made in Symfony, you should precede your description of the change with
+the corresponding directive and a short description:
+
+For a new feature or a behaviour change use the ``.. versionadded:: 3.x``
+directive:
 
 .. code-block:: rst
 
     .. versionadded:: 3.4
 
         The special ``!`` template prefix was introduced in Symfony 3.4.
 
-If you're documenting a behavior change, it may be helpful to *briefly* describe
-how the behavior has changed:
+If you are documenting a behavior change, it may be helpful to *briefly*
+describe how the behavior has changed:
 
 .. code-block:: rst
 
@@ -191,12 +194,21 @@ how the behavior has changed:
         Support for annotation routing without an external bundle was added in
         Symfony 3.4. Prior, you needed to install the SensioFrameworkExtraBundle.
 
+For a deprecation use the ``.. deprecated:: 3.X`` directive:
+
+.. code-block:: rst
+
+    .. deprecated:: 3.3
+
+        This technique is discouraged and the ``addClassesToCompile()`` method was
+        deprecated in Symfony 3.3 because modern PHP versions make it unnecessary.
+
 Whenever a new major version of Symfony is released (e.g. 3.0, 4.0, etc),
 a new branch of the documentation is created from the ``master`` branch.
-At this point, all the ``versionadded`` tags for Symfony versions that have
-a lower major version will be removed. For example, if Symfony 4.0 were
-released today, 3.0 to 3.4 ``versionadded`` tags would be removed from the new
-``4.0`` branch.
+At this point, all the ``versionadded`` and ``deprecated`` tags for Symfony
+versions that have a lower major version will be removed. For example, if
+Symfony 4.0 were released today, 3.0 to 3.4 ``versionadded`` and ``deprecated``
+tags would be removed from the new ``4.0`` branch.
 
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _Sphinx: http://sphinx-doc.org/

debug/debugging.rst

@@ -61,7 +61,7 @@ cache files, or you can change the extension used by Symfony for these files::
 
     $kernel->loadClassCache('classes', '.php.cache');
 
-.. versionadded:: 3.3
+.. deprecated:: 3.3
 
     The ``loadClassCache()`` was deprecated in Symfony 3.3 and removed in
     Symfony 4.0. No alternative is provided because this feature is useless

reference/configuration/kernel.rst

@@ -56,7 +56,7 @@ directory and rename it to something else (e.g. ``foo``).
 Root Directory
 ~~~~~~~~~~~~~~
 
-.. versionadded:: 3.3
+.. deprecated:: 3.3
 
     The ``getRootDir()`` method is deprecated since Symfony 3.3. Use the new
     ``getProjectDir()`` method instead.

reference/configuration/security.rst

@@ -500,7 +500,7 @@ Learn more about user checkers in :doc:`/security/user_checkers`.
 HTTP-Digest Authentication
 --------------------------
 
-.. versionadded:: 3.4
+.. deprecated:: 3.4
 
     HTTP-Digest Authentication was deprecated in Symfony 3.4 and it will be
     removed in Symfony 4.0.

reference/configuration/web_profiler.rst

@@ -50,7 +50,7 @@ environment.
 position
 ~~~~~~~~
 
-.. versionadded:: 3.4
+.. deprecated:: 3.4
 
     The ``position`` option was deprecated in Symfony 3.4 and it will be removed
     in Symfony 4.0, where the toolbar is always displayed in the ``bottom`` position.