minor #11178 Use the ".. deprecated::" directive for deprecations (OskarStark)

javiereguiluz · javiereguiluz · commit 5def9777011e · 2019-03-20T11:33:34.000+01:00
This PR was squashed before being merged into the 3.4 branch (closes #11178). Discussion ---------- Use the ".. deprecated::" directive for deprecations Refs #11154 ## Todo: - [ ] We need no ensure the correct html markup - [ ] @symfony/docs-team please review the new documentation about "[how/when to use this new directive](2b0504d)" Commits ------- b48d0c7 Use the \".. deprecated::\" directive for deprecations
diff --git a/bundles/extension.rst b/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.
diff --git a/components/console/events.rst b/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.
diff --git a/components/event_dispatcher/container_aware_dispatcher.rst b/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
diff --git a/components/filesystem/lock_handler.rst b/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>`
diff --git a/configuration/external_parameters.rst b/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
diff --git a/contributing/documentation/format.rst b/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/
diff --git a/debug/debugging.rst b/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
diff --git a/reference/configuration/kernel.rst b/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.
diff --git a/reference/configuration/security.rst b/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.
diff --git a/reference/configuration/web_profiler.rst b/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.
diff --git a/security.rst b/security.rst
@@ -963,7 +963,7 @@ For more details on expressions and security, see :doc:`/security/expressions`.
 Access Control Lists (ACLs): Securing individual Database Objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 3.4
+.. deprecated:: 3.4
 
     ACL support was deprecated in Symfony 3.4 and will be removed in 4.0. Install
     the `Symfony ACL bundle`_ if you want to keep using ACL.
diff --git a/security/acl.rst b/security/acl.rst
@@ -4,7 +4,7 @@
 How to Use Access Control Lists (ACLs)
 ======================================
 
-.. versionadded:: 3.4
+.. deprecated:: 3.4
 
     ACL support was deprecated in Symfony 3.4 and will be removed in 4.0. Install
     the `Symfony ACL bundle`_ if you want to keep using ACL.
diff --git a/security/acl_advanced.rst b/security/acl_advanced.rst
@@ -4,7 +4,7 @@
 How to Use advanced ACL Concepts
 ================================
 
-.. versionadded:: 3.4
+.. deprecated:: 3.4
 
     ACL support was deprecated in Symfony 3.4 and will be removed in 4.0. Install
     the `Symfony ACL bundle`_ if you want to keep using ACL.
diff --git a/security/multiple_user_providers.rst b/security/multiple_user_providers.rst
@@ -92,7 +92,7 @@ Now, all firewalls that explicitly define ``chain_provider`` as their user
 provider will, in turn, try to load the user from both the ``in_memory`` and
 ``user_db`` providers.
 
-.. versionadded:: 3.4
+.. deprecated:: 3.4
 
     In previous Symfony versions, firewalls that didn't define their user provider
     explicitly, used the first existing provider (``chain_provider`` in this
