feature #3486 Documenting createAccessDeniedException() method (klaus…

…silveira)

This PR was merged into the master branch.

Discussion
----------

Documenting createAccessDeniedException() method

Updating documentation to reflect the changes added in symfony/symfony#9405.

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#9405)
| Applies to    | 2.5+
| Fixed tickets |

Commits
-------

da6002d Wrapping line
b1b9090 Adding versionadded detail
53f156c Updating references to match doc format
6fd3f93 Documenting createAccessDeniedException() method

book/security.rst

@@ -1072,19 +1072,25 @@ fine-grained enough in certain cases. When necessary, you can easily force
 authorization from inside a controller::
 
     // ...
-    use Symfony\Component\Security\Core\Exception\AccessDeniedException;
 
     public function helloAction($name)
     {
         if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) {
-            throw new AccessDeniedException();
+            throw $this->createAccessDeniedException('Unable to access this page!');
         }
 
         // ...
     }
 
 .. _book-security-securing-controller-annotations:
 
+.. versionadded:: 2.5
+    The ``createAccessDeniedException`` method was introduced in Symfony 2.5.
+
+The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createAccessDeniedException()`
+method creates a special :class:`Symfony\\Component\\Security\\Core\Exception\\AccessDeniedException`
+object, which ultimately triggers a 403 HTTP response inside Symfony.
+
 Thanks to the SensioFrameworkExtraBundle, you can also secure your controller using annotations::
 
     // ...