Merge branch '3.4' into 4.2

* 3.4:
  Use the \".. deprecated::\" directive for deprecations
  use same order for all configuration-blocks
  Add precision on the concerned fields
  Correct a sentence meaning
  use :: instead of .. code-block:: php

Author: javiereguiluz

components/expression_language/extending.rst

@@ -29,7 +29,7 @@ This method has 3 arguments:
   function;
 * **evaluator** - A function executed when the expression is evaluated.
 
-.. code-block:: php
+Example::
 
     use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
 

components/security/authorization.rst

@@ -49,7 +49,7 @@ recognizes several strategies:
 ``unanimous``
     only grant access if none of the voters has denied access;
 
-.. code-block:: php
+Usage of the available options in detail::
 
     use Symfony\Component\Security\Core\Authorization\AccessDecisionManager;
 

components/translation/usage.rst

@@ -67,16 +67,16 @@ is done just as before:
             </file>
         </xliff>
 
+    .. code-block:: yaml
+
+        'Hello %name%': Bonjour %name%
+
     .. code-block:: php
 
         return [
             'Hello %name%' => 'Bonjour %name%',
         ];
 
-    .. code-block:: yaml
-
-        'Hello %name%': Bonjour %name%
-
 .. note::
 
     The placeholders can take on any form as the full message is reconstructed

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/

deployment/proxies.rst

@@ -59,9 +59,7 @@ In this case, you'll need to - *very carefully* - trust *all* proxies.
    other than your load balancers. For AWS, this can be done with `security groups`_.
 
 #. Once you've guaranteed that traffic will only come from your trusted reverse
-   proxies, configure Symfony to *always* trust incoming request:
-
-   .. code-block:: php
+   proxies, configure Symfony to *always* trust incoming request::
 
        // public/index.php
 

reference/constraints/Uuid.rst

@@ -22,14 +22,6 @@ Basic Usage
 
 .. configuration-block::
 
-    .. code-block:: yaml
-
-        # config/validator/validation.yaml
-        App\Entity\File:
-            properties:
-                identifier:
-                    - Uuid: ~
-
     .. code-block:: php-annotations
 
         // src/Entity/File.php
@@ -45,6 +37,14 @@ Basic Usage
              protected $identifier;
         }
 
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\File:
+            properties:
+                identifier:
+                    - Uuid: ~
+
     .. code-block:: xml
 
         <!-- config/validator/validation.xml -->

setup/built_in_web_server.rst

@@ -109,8 +109,7 @@ you have to pass the correct location using the ``--docroot`` option:
 Stopping the Server
 -------------------
 
-When you are finished, you can stop the web server using the ``server:stop``
-command:
+When you finish your work, you can stop the web server with the following command:
 
 .. code-block:: terminal
 

validation/groups.rst

@@ -132,15 +132,18 @@ With this configuration, there are three validation groups:
 
 ``Default``
     Contains the constraints in the current class and all referenced classes
-    that belong to no other group.
+    that belong to no other group. In this example, it only contains the
+    ``city`` field.
 
 ``User``
     Equivalent to all constraints of the ``User`` object in the ``Default``
     group. This is always the name of the class. The difference between this
     and ``Default`` is explained in :doc:`/validation/sequence_provider`.
 
 ``registration``
-    Contains the constraints on the ``email`` and ``password`` fields only.
+    This is a custom validation group, so it only contains the constraints
+    explicitly associated to it. In this example, only the ``email`` and
+    ``password`` fields.
 
 Constraints in the ``Default`` group of a class are the constraints that have
 either no explicit group configured or that are configured to a group equal to

workflow/usage.rst

@@ -155,7 +155,7 @@ like this:
             ],
         ]);
 
-.. code-block:: php
+As configured, the following property is used by the marking store::
 
     class BlogPost
     {