feature #3916 [Component][EventDispatcher] documentation for the Trac…

…eableEventDispatcher (xabbuh)

This PR was merged into the 2.3 branch.

Discussion
----------

[Component][EventDispatcher] documentation for the TraceableEventDispatcher

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | 2.3, 2.4
| Fixed tickets | #3879

After this has been merged, the document has to be updated for Symfony 2.5 and higher to reflect that the ``TraceableEventDispatcher`` is now part of the EventDispatcher component.

Commits
-------

1160f7c add documentation for the TraceableEventDispatcher class

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**