From 6a2acd7fed61159a4ede4d460fd4ef5079ab674c Mon Sep 17 00:00:00 2001
From: Joe Shindelar <eojthebrave@gmail.com>
Date: Mon, 9 Feb 2015 14:15:55 -0700
Subject: [PATCH] Initial pass at RoutingEvents docs.

---
 core/lib/Drupal/Core/Routing/RoutingEvents.php | 42 +++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 4 deletions(-)

diff --git a/core/lib/Drupal/Core/Routing/RoutingEvents.php b/core/lib/Drupal/Core/Routing/RoutingEvents.php
index 8df9698..0372c38 100644
--- a/core/lib/Drupal/Core/Routing/RoutingEvents.php
+++ b/core/lib/Drupal/Core/Routing/RoutingEvents.php
@@ -13,21 +13,55 @@
 final class RoutingEvents {
 
   /**
-   * THE DYNAMIC event is fired on a route collection to allow new routes.
+   * The DYNAMIC event is fired on a route collection to allow new routes.
    *
-   * This event is used to add new routes based upon existing routes.
+   * This event is used to add new routes based upon existing routes giving
+   * modules the opportunity to dynamically generate additional routes. The
+   * event listener method receives a \Drupal\Core\Routing\RouteBuildEvent
+   * instance.
+   *
+   * @Event
+   *
+   * @see \Drupal\Core\Routing\RouteBuildEvent
+   * @see \Drupal\Core\EventSubscriber\EntityRouteProviderSubscriber
+   * @see \Drupal\Core\Routing\RouteBuilder::rebuild()
+   *
+   * @var string
    */
   const DYNAMIC = 'routing.route_dynamic';
 
   /**
    * The ALTER event is fired on a route collection to allow changes to routes.
    *
-   * This event is used to process new routes before they get saved.
+   * This event is used to process new routes before they get saved giving
+   * modules the opportunity to alter routes provided by any other module. The
+   * event listener method receives a \Drupal\Core\Routing\RouteBuildEvent
+   * instance.
+   *
+   * @Event
+   *
+   * @see \Symfony\Component\Routing\RouteCollection
+   * @see \Drupal\system\EventSubscriber\AdminRouteSubscriber
+   * @see \Drupal\Core\Routing\RouteBuilder::rebuild()
+   *
+   * @var string
    */
   const ALTER = 'routing.route_alter';
 
   /**
-   * The FINISHED event is fired when the route building ended.
+   * The FINISHED event is fired after the route building has ended.
+   *
+   * This event gives modules the opportunity to perform some action after route
+   * building has completed. The event listener receives an
+   * \Drupal\Core\Routing\RouteBuildEvent instance.
+   *
+   * @Event
+   *
+   * @see \Drupal\Core\Routing\RouteBuildEvent
+   * @see \Drupal\Core\EventSubscriber\MenuRouterRebuildSubscriber
+   * @see \Drupal\Core\Routing\RouteBuilder::rebuild()
+   *
+   * @var string
    */
   const FINISHED = 'routing.route_finished';
 
-- 
2.2.2