minor symfony#16936 [Security] backported phpdoc from Guard component. (hhamon)

This PR was merged into the 2.3 branch.

Discussion
----------

[Security] backported phpdoc from Guard component.

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | ~
| License       | MIT
| Doc PR        | ~

Commits
-------

cab6fd5 [Security] backported phpdoc from Guard component.

Author: Tobion

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

@@ -24,7 +24,17 @@
 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 RedirectResponse('/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