Improving phpdoc on AuthenticationEntryPointInterface so people that implement this understand it

src/Symfony/Component/Security/Http/EntryPoint/AuthenticationEntryPointInterface.php

@@ -16,15 +16,25 @@ use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
 
 /**
- * AuthenticationEntryPointInterface is the interface used to start the
+ * Implement this interface for any classes that will be called to "start"
- * authentication scheme.
+ * the authentication process (see method for more details).
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
 interface AuthenticationEntryPointInterface
 {
     /**
-     * Starts the authentication scheme.
+     * Returns a response that directs the user to authenticate
+     *
+     * This is called when an anonymous request accesses a resource that
+     * requires authentication. The job of this method is to return some
+     * response that "helps" the user start into the authentication process.
+     *
+     * Examples:
+     *  A) For a form login, you might redirect to the login page
+     *      return new Response('/login');
+     *  B) For an API token authentication system, you return a 401 response
+     *      return new Response('Auth header required', 401);
      *
      * @param Request                 $request       The request that resulted in an AuthenticationException
      * @param AuthenticationException $authException The exception that started the authentication process