symfony · javiereguiluz · Nov 12, 2018 · Nov 13, 2018
diff --git a/components/event_dispatcher.rst b/components/event_dispatcher.rst
@@ -148,7 +148,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.
 
@@ -387,10 +387,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.

diff --git a/doctrine/event_listeners_subscribers.rst b/doctrine/event_listeners_subscribers.rst
@@ -276,8 +276,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::
 

diff --git a/event_dispatcher.rst b/event_dispatcher.rst
@@ -119,7 +119,7 @@ using a special "tag":
 
     The other optional tag attribute is 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
+    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.
@@ -134,7 +134,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

diff --git a/profiler/data_collector.rst b/profiler/data_collector.rst
@@ -315,8 +315,9 @@ the ``data_collector`` tag in your service configuration:
     The ``id`` attribute must match the value returned by the ``getName()`` method.
 
 The position of each panel in the toolbar is determined by the priority defined
-by each collector. Most built-in collectors use ``255`` as their priority. If you
-want your collector to be displayed before them, use a higher value:
+by each collector. 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:
 
 .. configuration-block::
 

diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst
@@ -568,8 +568,9 @@ tag:
 
 .. 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::
 
@@ -1422,8 +1423,8 @@ the new loader and tag it with ``twig.loader``:
 
 .. 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.
 
 validator.constraint_validator
 ------------------------------