add documentation for the TraceableEventDispatcher class

Author: xabbuh

components/event_dispatcher/index.rst

@@ -8,3 +8,4 @@ EventDispatcher
     container_aware_dispatcher
     generic_event
     immutable_dispatcher
+    traceable_dispatcher

components/event_dispatcher/traceable_dispatcher.rst

@@ -0,0 +1,46 @@
+.. index::
+    single: EventDispatcher; Debug
+    single: EventDispatcher; Traceable
+
+The Traceable Event Dispatcher
+==============================
+
+The :class:`Symfony\\Component\\HttpKernel\\Debug\\TraceableEventDispatcher`
+is an event dispatcher that wraps any other event dispatcher and can then
+be used to determine which event listeners have been called by the dispatcher.
+Pass the event dispatcher to be wrapped and an instance of the
+:class:`Symfony\\Component\\Stopwatch\\Stopwatch` to its constructor::
+
+    use Symfony\Component\HttpKernel\Debug\TraceableEventDispatcher;
+    use Symfony\Component\Stopwatch\Stopwatch;
+
+    // the event dispatcher to debug
+    $eventDispatcher = ...;
+
+    $traceableEventDispatcher = new TraceableEventDispatcher($eventDispatcher, new Stopwatch());
+
+Now, the ``TraceableEventDispatcher`` can be used like any other event dispatcher
+to register event listeners and dispatch events::
+
+    // ...
+
+    // register an event listener
+    $eventListener = ...;
+    $priority = ...;
+    $traceableEventDispatcher->addListener('the-event-name', $eventListener, $priority);
+
+    // dispatch an event
+    $event = ...;
+    $traceableEventDispatcher->dispatch('the-event-name', $event);
+
+After your application has been processed, you can use the
+:method:`Symfony\\Component\\EventDispatcher\\Debug\\TraceableEventDispatcherInterface::getCalledListeners`
+method to retrieve an array of event listeners that have been called in your
+application. Similarly, the
+:method:`Symfony\\Component\\EventDispatcher\\Debug\\TraceableEventDispatcherInterface::getNotCalledListeners`
+method returns an array of event listeners that have not been called::
+
+    // ...
+
+    $calledListeners = $traceableEventDispatcher->getCalledListeners();
+    $notCalledListeners = $traceableEventDispatcher->getNotCalledListeners();

components/map.rst.inc

@@ -56,6 +56,7 @@
   * :doc:`/components/event_dispatcher/container_aware_dispatcher`
   * :doc:`/components/event_dispatcher/generic_event`
   * :doc:`/components/event_dispatcher/immutable_dispatcher`
+  * :doc:`/components/event_dispatcher/traceable_dispatcher`
 
 * **Filesystem**