Updated documentation regarding the SecurityContext split

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | >=2.6
| Fixed tickets | https://github.com/symfony/symfony/pull/11690

This PR is to update the documentation regarding my PR on symfony/symfony. I require some feedback regarding:
 - Code Examples, I did not change *all* examples because the class using the `$securityContext` was not updated in my PR as it's Backwards Compatible
 - The usage of "security context". The term is correct, but it might get really confusing for people who see that the security context is deprecated. However, this is only regarding the `SecurityContext`, `SecurityContextInterface` and `@security.context`.
 - The above point is what confused me too so the docs might be out of context in certain spots, please review this thoroughly 
I think it's better to move the block before the code and then use the `class` role in the "normal" text.