minor symfony#20090 [Security] Authenticator methods description (smn…

…andre)

This PR was submitted for the 7.1 branch but it was squashed and merged into the 6.4 branch instead.

Discussion
----------

[Security] Authenticator methods description

At first i just wanted to reword this sentence i found missleading.. in the [Custom Authenticator](https://symfony.com/doc/current/security/custom_authenticator.html) page.

> If ``null`` is returned, the request continues like normal (i.e. the  controller matching the login route is called).

I think it should be:

```diff
- (i.e. the controller matching the login route is called)
+ (i.e. the controller matching the current route is called)
```

Because it _can_ be the login route for _some_ Authenticators, but it's not for stateless requests, Header tokens, remember me...

I then realize the "if / if" was the reason I found things a bit unclear at first sight.

```
onAuthenticationSuccess(Request $request, ...)

    If the user is authenticated, (...)

    If ``null`` is returned, (...)

```

I read this as some sort of "if / else" ... but the first "if" englobes the whole paragraph (it's true again in the second one).

So i tried to rewrite a bit (using the docblocks from the [AuthenticatorInterface](https://github.com/symfony/symfony/blob/7.2/src/Symfony/Component/Security/Http/Authenticator/AuthenticatorInterface.php) as inspiration)

Commits
-------

236e419 [Security] Authenticator methods description

security/custom_authenticator.rst

@@ -153,22 +153,25 @@ or there was something wrong (e.g. incorrect password). The authenticator
 can define what happens in these cases:
 
 ``onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response``
-    If the user is authenticated, this method is called with the
-    authenticated ``$token``. This method can return a response (e.g.
-    redirect the user to some page).
+    If authentication is successful, this method is called with the
+    authenticated ``$token``.
 
-    If ``null`` is returned, the request continues like normal (i.e. the
-    controller matching the login route is called). This is useful for API
-    routes where each route is protected by an API key header.
+    This method can return a response (e.g. redirect the user to some page).
+
+    If ``null`` is returned, the current request will continue (and the
+    user will be authenticated). This is useful for API routes where each
+    route is protected by an API key header.
 
 ``onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response``
-    If an ``AuthenticationException`` is thrown during authentication, the
-    process fails and this method is called. This method can return a
-    response (e.g. to return a 401 Unauthorized response in API routes).
+    If authentication failed (e. g. wrong username password), this method
+    is called with the ``AuthenticationException`` thrown.
+
+    This method can return a response (e.g. send a 401 Unauthorized in API
+    routes).
 
-    If ``null`` is returned, the request continues like normal. This is
-    useful for e.g. login forms, where the login controller is run again
-    with the login errors.
+    If ``null`` is returned, the request continues (but the user will **not**
+    be authenticated). This is useful for login forms, where the login
+    controller is run again with the login errors.
 
     If you're using :ref:`login throttling <security-login-throttling>`,
     you can check if ``$exception`` is an instance of