[#6422] Detailed proof-read after the great PR from @iltar

wouterj · wouterj · commit 998cc4083ff4 · 2016-07-05T12:06:07.000+02:00
diff --git a/components/http_kernel/introduction.rst b/components/http_kernel/introduction.rst
@@ -83,9 +83,9 @@ Framework - works.
 Initially, using the :class:`Symfony\\Component\\HttpKernel\\HttpKernel`
 is really simple and involves creating an
 :doc:`event dispatcher </components/event_dispatcher/introduction>` and a
-:ref:`controller resolver <component-http-kernel-resolve-controller>` (explained
-below). To complete your working kernel, you'll add more event listeners
-to the events discussed below::
+:ref:`controller and argument resolver <component-http-kernel-resolve-controller>`
+(explained below). To complete your working kernel, you'll add more event
+listeners to the events discussed below::
 
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpKernel\HttpKernel;
@@ -122,13 +122,12 @@ See ":ref:`http-kernel-working-example`" for a more concrete implementation.
 For general information on adding listeners to the events below, see
 :ref:`http-kernel-creating-listener`.
 
-
 .. caution::
 
-    As of 3.1 the :class:`Symfony\\Component\\Httpkernel\\HttpKernel` accepts a fourth argument, which
-    must be an instance of :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolverInterface`.
-    In 4.0 this argument will become mandatory and the :class:`Symfony\\Component\\Httpkernel\\HttpKernel`
-    will no longer be able to fall back to the :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolver`.
+    As of 3.1 the :class:`Symfony\\Component\\Httpkernel\\HttpKernel` accepts a
+    fourth argument, which must be an instance of
+    :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolverInterface`.
+    In 4.0 this argument will become mandatory.
 
 .. seealso::
 
@@ -210,7 +209,7 @@ the next step in HttpKernel is to determine and prepare (i.e. resolve) the
 controller. The controller is the part of the end-application's code that
 is responsible for creating and returning the ``Response`` for a specific page.
 The only requirement is that it is a PHP callable - i.e. a function, method
-on an object, or a ``Closure``.
+on an object or a ``Closure``.
 
 But *how* you determine the exact controller for a request is entirely up
 to your application. This is the job of the "controller resolver" - a class
@@ -239,11 +238,14 @@ This implementation is explained more in the sidebar below::
 
 .. caution::
 
-    The ``getArguments()`` method in the :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolver`
-    and respective interface :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolverInterface`
+    The ``getArguments()`` method in the
+    :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolver` and
+    respective interface
+    :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolverInterface`
     are deprecated as of 3.1 and will be removed in 4.0. You can use the
-    :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolver` which uses the
-    :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolverInterface` instead.
+    :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolver` which
+    uses the :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolverInterface`
+    instead.
 
 Internally, the ``HttpKernel::handle`` method first calls
 :method:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolverInterface::getController`
@@ -330,9 +332,9 @@ on the event object that's passed to listeners on this event.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Next, ``HttpKernel::handle`` calls
-:method:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolverInterface::getArguments`.
-Remember that the controller returned in ``getController`` is a callable.
-The purpose of ``getArguments`` is to return the array of arguments that
+:method:`ArgumentResolverInterface::getArguments() <Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolverInterface::getArguments>`.
+Remember that the controller returned in ``getController()`` is a callable.
+The purpose of ``getArguments()`` is to return the array of arguments that
 should be passed to that controller. Exactly how this is done is completely
 up to your design, though the built-in :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver`
 is a good example.
@@ -353,7 +355,7 @@ of arguments that should be passed when executing that callable.
 
     a) If the ``Request`` attributes bag contains a key that matches the name
        of the argument, that value is used. For example, if the first argument
-       to a controller is ``$slug``, and there is a ``slug`` key in the ``Request``
+       to a controller is ``$slug`` and there is a ``slug`` key in the ``Request``
        ``attributes`` bag, that value is used (and typically this value came
        from the ``RouterListener``).
 
@@ -363,14 +365,15 @@ of arguments that should be passed when executing that callable.
        class, it will be injected as long as you extend the Symfony ``Request``.
 
     c) If the function or method argument is `variadic`_ and the ``Request``
-       ``attributes`` bag contains and array for that argument, they will all be
+       ``attributes`` bag contains an array for that argument, they will all be
        available through the `variadic`_ argument.
 
     This functionality is provided by resolvers implementing the
     :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentValueResolverInterface`.
-    There are four implementations which provide the default behavior of Symfony but
-    customization is the key here. By implementing the ``ArgumentValueResolverInterface``
-    yourself and passing this to the ``ArgumentResolver``, you can extend this functionality.
+    There are four implementations which provide the default behavior of
+    Symfony but customization is the key here. By implementing the
+    ``ArgumentValueResolverInterface`` yourself and passing this to the
+    ``ArgumentResolver``, you can extend this functionality.
 
 .. _component-http-kernel-calling-controller:
 
@@ -650,45 +653,44 @@ use any argument resolver that implements the
 However, the HttpKernel component comes with some built-in listeners and everything
 else that can be used to create a working example::
 
-   use Symfony\Component\EventDispatcher\EventDispatcher;
-   use Symfony\Component\HttpFoundation\Request;
-   use Symfony\Component\HttpFoundation\RequestStack;
-   use Symfony\Component\HttpFoundation\Response;
-   use Symfony\Component\HttpKernel\Controller\ArgumentResolver;
-   use Symfony\Component\HttpKernel\Controller\ControllerResolver;
-   use Symfony\Component\HttpKernel\EventListener\RouterListener;
-   use Symfony\Component\HttpKernel\HttpKernel;
-   use Symfony\Component\Routing\Matcher\UrlMatcher;
-   use Symfony\Component\Routing\RequestContext;
-   use Symfony\Component\Routing\Route;
-   use Symfony\Component\Routing\RouteCollection;
-
-   $routes = new RouteCollection();
-   $routes->add('hello', new Route('/hello/{name}', array(
-       '_controller' => function (Request $request) {
-           return new Response(
-               sprintf("Hello %s", $request->get('name'))
-           );
-       })
-   ));
-
-   $request = Request::createFromGlobals();
+    use Symfony\Component\EventDispatcher\EventDispatcher;
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\RequestStack;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Controller\ArgumentResolver;
+    use Symfony\Component\HttpKernel\Controller\ControllerResolver;
+    use Symfony\Component\HttpKernel\EventListener\RouterListener;
+    use Symfony\Component\HttpKernel\HttpKernel;
+    use Symfony\Component\Routing\Matcher\UrlMatcher;
+    use Symfony\Component\Routing\RequestContext;
+    use Symfony\Component\Routing\Route;
+    use Symfony\Component\Routing\RouteCollection;
+
+    $routes = new RouteCollection();
+    $routes->add('hello', new Route('/hello/{name}', array(
+        '_controller' => function (Request $request) {
+            return new Response(
+                sprintf("Hello %s", $request->get('name'))
+            );
+        })
+    ));
 
-   $matcher = new UrlMatcher($routes, new RequestContext());
+    $request = Request::createFromGlobals();
 
-   $dispatcher = new EventDispatcher();
-   $dispatcher->addSubscriber(new RouterListener($matcher, new RequestStack()));
+    $matcher = new UrlMatcher($routes, new RequestContext());
 
-   $controllerResolver = new ControllerResolver();
-   $argumentResolver = new ArgumentResolver();
+    $dispatcher = new EventDispatcher();
+    $dispatcher->addSubscriber(new RouterListener($matcher, new RequestStack()));
 
-   $kernel = new HttpKernel($dispatcher, $controllerResolver, new RequestStack(), $argumentResolver);
+    $controllerResolver = new ControllerResolver();
+    $argumentResolver = new ArgumentResolver();
 
-   $response = $kernel->handle($request);
-   $response->send();
+    $kernel = new HttpKernel($dispatcher, $controllerResolver, new RequestStack(), $argumentResolver);
 
-   $kernel->terminate($request, $response);
+    $response = $kernel->handle($request);
+    $response->send();
 
+    $kernel->terminate($request, $response);
 
 .. _http-kernel-sub-requests:
 
diff --git a/create_framework/http_kernel_controller_resolver.rst b/create_framework/http_kernel_controller_resolver.rst
@@ -60,11 +60,11 @@ based on a Request object. All controller resolvers implement the following inte
 
 .. caution::
 
-    The ``getArguments()`` method in the :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolver`
-    and respective interface :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolverInterface`
-    are deprecated as of 3.1 and will be removed in 4.0. You can use the
-    :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolver` which uses the
-    :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolverInterface` instead.
+    The ``getArguments()`` method is deprecated as of Symfony 3.1. and will be
+    removed in 4.0. You can use the
+    :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolver` which
+    uses the :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolverInterface`
+    instead.
 
 The ``getController()`` method relies on the same convention as the one we
 have defined earlier: the ``_controller`` request attribute must contain the
@@ -142,10 +142,10 @@ Let's just inject the ``$year`` request attribute for our controller::
         }
     }
 
-The controller resolver also takes care of validating the controller callable
-and its arguments. In case of a problem, it throws an exception with a nice
-message explaining the problem (the controller class does not exist, the
-method is not defined, an argument has no matching attribute, ...).
+The resolvers also take care of validating the controller callable and its
+arguments. In case of a problem, it throws an exception with a nice message
+explaining the problem (the controller class does not exist, the method is not
+defined, an argument has no matching attribute, ...).
 
 .. note::
 
diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst
@@ -354,9 +354,13 @@ For details on registering your own commands in the service container, read
 controller.argument_value_resolver
 ----------------------------------
 
+.. versionadded:: 3.1
+    The ``controller.argument_value_resolver`` tag was introduced in Symfony 3.1.
+
 **Purpose**: Register a value resolver for controller arguments such as ``Request``
 
-Value resolvers implement the :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentValueResolverInterface`
+Value resolvers implement the
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentValueResolverInterface`
 and are used to resolve argument values for controllers as described here:
 :doc:`/cookbook/controller/argument_value_resolver`.
 
