added some doc comments

6 files changed, 78 insertions, 4 deletions

diff --git a/Http/Authentication/AuthenticationFailureHandlerInterface.php b/Http/Authentication/AuthenticationFailureHandlerInterface.php
index 4957edf..5eeefa1 100644
--- a/Http/Authentication/AuthenticationFailureHandlerInterface.php
+++ b/Http/Authentication/AuthenticationFailureHandlerInterface.php
@@ -5,7 +5,28 @@ namespace Symfony\Component\Security\Http\Authentication;
 use Symfony\Component\EventDispatcher\EventInterface;
 use Symfony\Component\HttpFoundation\Request;
 
+/**
+ * Interface for custom authentication failure handlers.
+ *
+ * If you want to customize the failure handling process, instead of
+ * overwriting the respective listener globally, you can set a custom failure
+ * handler which implements this interface.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 interface AuthenticationFailureHandlerInterface
 {
+    /**
+     * This is called when an interactive authentication attempt fails. This is
+     * called by authentication listeners inheriting from
+     * AbstractAuthenticationListener.
+     *
+     * @param EventInterface $event the "core.security" event, this event always
+     *                              has the kernel as target
+     * @param Request        $request
+     * @param \Exception     $exception
+     *
+     * @return Response the response to return
+     */
     function onAuthenticationFailure(EventInterface $event, Request $request, \Exception $exception);
 }
\ No newline at end of file
diff --git a/Http/Authentication/AuthenticationSuccessHandlerInterface.php b/Http/Authentication/AuthenticationSuccessHandlerInterface.php
index 6efa309..235eb94 100644
--- a/Http/Authentication/AuthenticationSuccessHandlerInterface.php
+++ b/Http/Authentication/AuthenticationSuccessHandlerInterface.php
@@ -6,7 +6,28 @@ use Symfony\Component\EventDispatcher\EventInterface;
 use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
 use Symfony\Component\HttpFoundation\Request;
 
+/**
+ * Interface for a custom authentication success handler
+ *
+ * If you want to customize the success handling process, instead of
+ * overwriting the respective listener globally, you can set a custom success
+ * handler which implements this interface.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 interface AuthenticationSuccessHandlerInterface
 {
+    /**
+     * This is called when an interactive authentication attempt succeeds. This
+     * is called by authentication listeners inheriting from
+     * AbstractAuthenticationListener.
+     *
+     * @param EventInterface $event the "core.security" event, this event always
+     *                              has the kernel as target
+     * @param Request        $request
+     * @param TokenInterface $token
+     *
+     * @return Response the response to return
+     */
     function onAuthenticationSuccess(EventInterface $event, Request $request, TokenInterface $token);
 }
\ No newline at end of file
diff --git a/Http/ExceptionTranslation/AccessDeniedHandlerInterface.php b/Http/Authorization/AccessDeniedHandlerInterface.php
index ba9553e..7a1bcf4 100644
--- a/Http/ExceptionTranslation/AccessDeniedHandlerInterface.php
+++ b/Http/Authorization/AccessDeniedHandlerInterface.php
@@ -1,6 +1,6 @@
 <?php
 
-namespace Symfony\Component\Security\Http\ExceptionTranslation;
+namespace Symfony\Component\Security\Http\Authorization;
 
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\EventDispatcher\EventInterface;
@@ -17,8 +17,8 @@ interface AccessDeniedHandlerInterface
     /**
      * Handles an access denied failure.
      *
-     * @param EventInterface $event
-     * @param Request $request
+     * @param EventInterface        $event
+     * @param Request               $request
      * @param AccessDeniedException $accessDeniedException
      *
      * @return Response may return null
diff --git a/Http/Firewall/ExceptionListener.php b/Http/Firewall/ExceptionListener.php
index 6d3aa6b..de90954 100644
--- a/Http/Firewall/ExceptionListener.php
+++ b/Http/Firewall/ExceptionListener.php
@@ -13,7 +13,7 @@ namespace Symfony\Component\Security\Http\Firewall;
 
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Bundle\SecurityBundle\Security\AccessDeniedHandler;
-use Symfony\Component\Security\Http\ExceptionTranslation\AccessDeniedHandlerInterface;
+use Symfony\Component\Security\Http\Authorization\AccessDeniedHandlerInterface;
 use Symfony\Component\Security\Core\SecurityContext;
 use Symfony\Component\Security\Core\Authentication\AuthenticationTrustResolverInterface;
 use Symfony\Component\Security\Core\Authentication\EntryPoint\AuthenticationEntryPointInterface;
diff --git a/Http/Session/SessionAuthenticationStrategy.php b/Http/Session/SessionAuthenticationStrategy.php
index 64f787f..1d25bd9 100644
--- a/Http/Session/SessionAuthenticationStrategy.php
+++ b/Http/Session/SessionAuthenticationStrategy.php
@@ -5,6 +5,16 @@ namespace Symfony\Component\Security\Http\Session;
 use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
 use Symfony\Component\HttpFoundation\Request;
 
+/**
+ * The default session strategy implementation.
+ *
+ * Supports the following strategies:
+ * NONE: the session is not changed
+ * MIGRATE: the session id is updated, attributes are kept
+ * INVALIDATE: the session id is updated, attributes are lost
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 class SessionAuthenticationStrategy implements SessionAuthenticationStrategyInterface
 {
     const NONE         = 'none';
@@ -18,6 +28,9 @@ class SessionAuthenticationStrategy implements SessionAuthenticationStrategyInte
         $this->strategy = $strategy;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function onAuthentication(Request $request, TokenInterface $token)
     {
         switch ($this->strategy) {
diff --git a/Http/Session/SessionAuthenticationStrategyInterface.php b/Http/Session/SessionAuthenticationStrategyInterface.php
index c2d95c3..b248fd7 100644
--- a/Http/Session/SessionAuthenticationStrategyInterface.php
+++ b/Http/Session/SessionAuthenticationStrategyInterface.php
@@ -5,7 +5,26 @@ namespace Symfony\Component\Security\Http\Session;
 use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
 use Symfony\Component\HttpFoundation\Request;
 
+/**
+ * SessionAuthenticationStrategyInterface
+ *
+ * Implementation are responsible for updating the session after an interactive
+ * authentication attempt was successful.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
 interface SessionAuthenticationStrategyInterface
 {
+    /**
+     * This performs any necessary changes to the session.
+     *
+     * This method is called before the SecurityContext is populated with a
+     * Token, and only by classes inheriting from AbstractAuthenticationListener.
+     *
+     * @param Request        $request
+     * @param TokenInterface $token
+     *
+     * @return void
+     */
     function onAuthentication(Request $request, TokenInterface $token);
 }
\ No newline at end of file