Merge branch '3.4' into 4.1

* 3.4:
  Improved and standardized the explanation about priorities

components/event_dispatcher.rst

@@ -147,7 +147,7 @@ The ``addListener()`` method takes up to three arguments:
 #. The event name (string) that this listener wants to listen to;
 #. A PHP callable that will be executed when the specified event is dispatched;
 #. An optional priority, defined as a positive or negative integer (defaults to
-   ``0``). The higher the priority, the earlier the listener is called. If two 
+   ``0``). The higher the number, the earlier the listener is called. If two
    listeners have the same priority, they are executed in the order that they
    were added to the dispatcher.
 
@@ -383,10 +383,12 @@ method::
 The dispatcher will automatically register the subscriber for each event
 returned by the ``getSubscribedEvents()`` method. This method returns an array
 indexed by event names and whose values are either the method name to call
-or an array composed of the method name to call and a priority. The example
-above shows how to register several listener methods for the same event
-in subscriber and also shows how to pass the priority of each listener method.
-The higher the priority, the earlier the method is called. In the above
+or an array composed of the method name to call and a priority (a positive or
+negative integer that defaults to ``0``).
+
+The example above shows how to register several listener methods for the same
+event in subscriber and also shows how to pass the priority of each listener
+method. The higher the number, the earlier the method is called. In the above
 example, when the ``kernel.response`` event is triggered, the methods
 ``onKernelResponsePre()`` and ``onKernelResponsePost()`` are called in that
 order.

doctrine/event_listeners_subscribers.rst

@@ -246,8 +246,9 @@ Priorities for Event Listeners
 ------------------------------
 
 In case you have multiple listeners for the same event you can control the order
-in which they are invoked using the ``priority`` attribute on the tag.
-Listeners with a higher priority are invoked first.
+in which they are invoked using the ``priority`` attribute on the tag. Priorities
+are defined with positive or negative integers (they default to ``0``). Higher
+numbers mean that listeners are invoked earlier.
 
 .. configuration-block::
 

event_dispatcher.rst

@@ -126,12 +126,12 @@ listener class:
 .. note::
 
     There is an optional attribute for the ``kernel.event_listener`` tag called
-    ``priority``, which defaults to ``0`` and it controls the order in which
-    listeners are executed (the higher the priority, the earlier a listener is
-    executed). This is useful when you need to guarantee that one listener is
-    executed before another. The priorities of the internal Symfony listeners
-    usually range from ``-255`` to ``255`` but your own listeners can use any
-    positive or negative integer.
+    ``priority``, which is a positive or negative integer that defaults to ``0``
+    and it controls the order in which listeners are executed (the higher the
+    number, the earlier a listener is executed). This is useful when you need to
+    guarantee that one listener is executed before another. The priorities of the
+    internal Symfony listeners usually range from ``-255`` to ``255`` but your
+    own listeners can use any positive or negative integer.
 
 .. _events-subscriber:
 
@@ -145,7 +145,7 @@ they are listening to.
 
 In a given subscriber, different methods can listen to the same event. The order
 in which methods are executed is defined by the ``priority`` parameter of each
-method (the higher the priority the earlier the method is called). To learn more
+method (the higher the number the earlier the method is called). To learn more
 about event subscribers, read :doc:`/components/event_dispatcher`.
 
 The following example shows an event subscriber that defines several methods which

profiler/data_collector.rst

@@ -276,5 +276,7 @@ to specify a tag that contains the template:
             ))
         ;
 
-The position of each panel in the toolbar is determined by the collector priority
-(the higher the priority, the earlier the panel is displayed in the toolbar).
+The position of each panel in the toolbar is determined by the collector priority.
+Priorities are defined as positive or negative integers and they default to ``0``.
+Most built-in collectors use ``255`` as their priority. If you want your collector
+to be displayed before them, use a higher value (like 300).

reference/dic_tags.rst

@@ -389,8 +389,9 @@ can also register it manually:
 
 .. note::
 
-    The ``priority`` value is optional and defaults to 0. The higher the
-    priority, the sooner it gets executed.
+    The ``priority`` is optional and its value is a positive or negative integer
+    that defaults to ``0``. The higher the number, the earlier that warmers are
+    executed.
 
 .. caution::
 
@@ -1173,8 +1174,8 @@ also register it manually:
 
 .. note::
 
-    The ``priority`` value is optional and defaults to ``0``.
-    The higher priority loaders are tried first.
+    The ``priority`` is optional and its value is a positive or negative integer
+    that defaults to ``0``. Loaders with higher numbers are tried first.
 
 .. _reference-dic-tags-twig-runtime: