[HttpKernel] Added more code documentation to the HttpKernel events

src/Symfony/Component/HttpKernel/Event/FilterControllerEvent.php

@@ -14,8 +14,23 @@ namespace Symfony\Component\HttpKernel\Event;
 use Symfony\Component\HttpKernel\HttpKernelInterface;
 use Symfony\Component\HttpFoundation\Request;
 
+/**
+ * Allows to filter a controller callable
+ *
+ * You can call getController() to retrieve the current controller. With
+ * setController() you can set a new controller that is used in for processing
+ * a request.
+ *
+ * Controllers should be callables.
+ *
+ * @author Bernhard Schussek <bernhard.schussek@symfony.com>
+ */
 class FilterControllerEvent extends KernelEvent
 {
+    /**
+     * The current controller
+     * @var callable
+     */
     private $controller;
 
     public function __construct(HttpKernelInterface $kernel, $controller, Request $request, $requestType)
@@ -25,11 +40,21 @@ class FilterControllerEvent extends KernelEvent
         $this->setController($controller);
     }
 
+    /**
+     * Returns the current controller
+     *
+     * @return callable
+     */
     public function getController()
     {
         return $this->controller;
     }
 
+    /**
+     * Sets a new controller
+     *
+     * @param callable $controller
+     */
     public function setController($controller)
     {
         // controller must be a callable

src/Symfony/Component/HttpKernel/Event/FilterResponseEvent.php

@@ -15,8 +15,21 @@ use Symfony\Component\HttpKernel\HttpKernelInterface;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
 
+/**
+ * Allows to filter a Response object
+ *
+ * You can call getResponse() to retrieve the current response. With
+ * setResponse() you can set a new response that will be returned to the
+ * browser.
+ *
+ * @author Bernhard Schussek <bernhard.schussek@symfony.com>
+ */
 class FilterResponseEvent extends KernelEvent
 {
+    /**
+     * The current response object
+     * @var Symfony\Component\HttpFoundation\Response
+     */
     private $response;
 
     public function __construct(HttpKernelInterface $kernel, Request $request, $requestType, Response $response)
@@ -26,11 +39,21 @@ class FilterResponseEvent extends KernelEvent
         $this->setResponse($response);
     }
 
+    /**
+     * Returns the current response object
+     *
+     * @return Symfony\Component\HttpFoundation\Response
+     */
     public function getResponse()
     {
         return $this->response;
     }
 
+    /**
+     * Sets a new response object
+     *
+     * @param Symfony\Component\HttpFoundation\Response $response
+     */
     public function setResponse(Response $response)
     {
         $this->response = $response;

src/Symfony/Component/HttpKernel/Event/GetResponseEvent.php

@@ -15,15 +15,38 @@ use Symfony\Component\HttpKernel\HttpKernelInterface;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
 
+/**
+ * Allows to create a response for a request
+ *
+ * Call setResponse() to set the response that will be returned for the
+ * current request. The propagation of this event is stopped as soon as a
+ * response is set.
+ *
+ * @author Bernhard Schussek <bernhard.schussek@symfony.com>
+ */
 class GetResponseEvent extends KernelEvent
 {
+    /**
+     * The response object
+     * @var Symfony\Component\HttpFoundation\Response
+     */
     private $response;
 
+    /**
+     * Returns the response object
+     *
+     * @return Symfony\Component\HttpFoundation\Response
+     */
     public function getResponse()
     {
         return $this->response;
     }
 
+    /**
+     * Sets a response and stops event propagation
+     *
+     * @param Symfony\Component\HttpFoundation\Response $response
+     */
     public function setResponse(Response $response)
     {
         $this->response = $response;
@@ -31,6 +54,11 @@ class GetResponseEvent extends KernelEvent
         $this->stopPropagation();
     }
 
+    /**
+     * Returns whether a response was set
+     *
+     * @return Boolean Whether a response was set
+     */
     public function hasResponse()
     {
         return null !== $this->response;

src/Symfony/Component/HttpKernel/Event/GetResponseForControllerResultEvent.php

@@ -14,8 +14,21 @@ namespace Symfony\Component\HttpKernel\Event;
 use Symfony\Component\HttpKernel\HttpKernelInterface;
 use Symfony\Component\HttpFoundation\Request;
 
+/**
+ * Allows to create a response for the return value of a controller
+ *
+ * Call setResponse() to set the response that will be returned for the
+ * current request. The propagation of this event is stopped as soon as a
+ * response is set.
+ *
+ * @author Bernhard Schussek <bernhard.schussek@symfony.com>
+ */
 class GetResponseForControllerResultEvent extends GetResponseEvent
 {
+    /**
+     * The return value of the controller
+     * @var mixed
+     */
     private $controllerResult;
 
     public function __construct(HttpKernelInterface $kernel, Request $request, $requestType, $controllerResult)
@@ -25,6 +38,11 @@ class GetResponseForControllerResultEvent extends GetResponseEvent
         $this->controllerResult = $controllerResult;
     }
 
+    /**
+     * Returns the return value of the controller
+     *
+     * @return mixed The controller return value
+     */
     public function getControllerResult()
     {
         return $this->controllerResult;

src/Symfony/Component/HttpKernel/Event/GetResponseForExceptionEvent.php

@@ -14,8 +14,25 @@ namespace Symfony\Component\HttpKernel\Event;
 use Symfony\Component\HttpKernel\HttpKernelInterface;
 use Symfony\Component\HttpFoundation\Request;
 
+/**
+ * Allows to create a response for a thrown exception
+ *
+ * Call setResponse() to set the response that will be returned for the
+ * current request. The propagation of this event is stopped as soon as a
+ * response is set.
+ *
+ * You can also call setException() to replace the thrown exception. This
+ * exception will be thrown if no response is set during processing of this
+ * event.
+ *
+ * @author Bernhard Schussek <bernhard.schussek@symfony.com>
+ */
 class GetResponseForExceptionEvent extends GetResponseEvent
 {
+    /**
+     * The exception object
+     * @var \Exception
+     */
     private $exception;
 
     public function __construct(HttpKernelInterface $kernel, Request $request, $requestType, \Exception $e)
@@ -25,11 +42,23 @@ class GetResponseForExceptionEvent extends GetResponseEvent
         $this->setException($e);
     }
 
+    /**
+     * Returns the thrown exception
+     *
+     * @return \Exception  The thrown exception
+     */
     public function getException()
     {
         return $this->exception;
     }
 
+    /**
+     * Replaces the thrown exception
+     *
+     * This exception will be thrown if no response is set in the event.
+     *
+     * @param \Exception $exception  The thrown exception
+     */
     public function setException(\Exception $exception)
     {
         $this->exception = $exception;

src/Symfony/Component/HttpKernel/Event/KernelEvent.php

@@ -15,12 +15,30 @@ use Symfony\Component\HttpKernel\HttpKernelInterface;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\EventDispatcher\Event;
 
+/**
+ * Base class for events thrown in the HttpKernel component
+ *
+ * @author Bernhard Schussek <bernhard.schussek@symfony.com>
+ */
 class KernelEvent extends Event
 {
+    /**
+     * The kernel in which this event was thrown
+     * @var Symfony\Component\HttpKernel\HttpKernelInterface
+     */
     private $kernel;
 
+    /**
+     * The request the kernel is currently processing
+     * @var Symfony\Component\HttpFoundation\Request
+     */
     private $request;
 
+    /**
+     * The request type the kernel is currently processing.  One of
+     * HttpKernelInterface::MASTER_REQUEST and HttpKernelInterface::SUB_REQUEST
+     * @var integer
+     */
     private $requestType;
 
     public function __construct(HttpKernelInterface $kernel, Request $request, $requestType)
@@ -30,16 +48,32 @@ class KernelEvent extends Event
         $this->requestType = $requestType;
     }
 
+    /**
+     * Returns the kernel in which this event was thrown
+     *
+     * @return Symfony\Component\HttpKernel\HttpKernelInterface
+     */
     public function getKernel()
     {
         return $this->kernel;
     }
 
+    /**
+     * Returns the request the kernel is currently processing
+     *
+     * @return Symfony\Component\HttpFoundation\Request
+     */
     public function getRequest()
     {
         return $this->request;
     }
 
+    /**
+     * Returns the request type the kernel is currently processing
+     *
+     * @return integer  One of HttpKernelInterface::MASTER_REQUEST and
+     *                  HttpKernelInterface::SUB_REQUEST
+     */
     public function getRequestType()
     {
         return $this->requestType;

src/Symfony/Component/HttpKernel/Events.php

@@ -11,17 +11,74 @@
 
 namespace Symfony\Component\HttpKernel;
 
+/**
+ * Contains all events thrown in the HttpKernel component
+ *
+ * @author Bernhard Schussek <bernhard.schussek@symfony.com>
+ */
 final class Events
 {
-    const onCoreException = 'onCoreException';
-
+    /**
+     * The onCoreRequest event occurs at the very beginning of request
+     * dispatching
+     *
+     * This event allows you to create a response for a request before any
+     * other code in the framework is executed. The event listener method
+     * receives a Symfony\Component\HttpKernel\Event\GetResponseEvent
+     * instance.
+     *
+     * @var string
+     */
     const onCoreRequest = 'onCoreRequest';
 
-    const filterCoreController = 'filterCoreController';
+    /**
+     * The onCoreException event occurs when an uncaught exception appears
+     *
+     * This event allows you to create a response for a thrown exception or
+     * to modify the thrown exception. The event listener method receives
+     * a Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent
+     * instance.
+     *
+     * @var string
+     */
+    const onCoreException = 'onCoreException';
 
+    /**
+     * The onCoreView event occurs when the return value of a controller
+     * is not a Response instance
+     *
+     * This event allows you to create a response for the return value of the
+     * controller. The event listener method receives a
+     * Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent
+     * instance.
+     *
+     * @var string
+     */
     const onCoreView = 'onCoreView';
 
-    const filterCoreResponse = 'filterCoreResponse';
-
     const onCoreSecurity = 'onCoreSecurity';
+
+    /**
+     * The filterCoreController event occurs once a controller was found for
+     * handling a request
+     *
+     * This event allows you to change the controller that will handle the
+     * request. The event listener method receives a
+     * Symfony\Component\HttpKernel\Event\FilterControllerEvent instance.
+     *
+     * @var string
+     */
+    const filterCoreController = 'filterCoreController';
+
+    /**
+     * The filterCoreController event occurs once a reponse was created for
+     * replying to a request
+     *
+     * This event allows you to modify or replace the response that will be
+     * replied. The event listener method receives a
+     * Symfony\Component\HttpKernel\Event\FilterResponseEvent instance.
+     *
+     * @var string
+     */
+    const filterCoreResponse = 'filterCoreResponse';
 }