Improved routing section

components/routing.rst

@@ -30,7 +30,7 @@ In order to set up a basic routing system you need three parts:
 
 * A :class:`Symfony\\Component\\Routing\\RouteCollection`, which contains the route definitions (instances of the class :class:`Symfony\\Component\\Routing\\Route`)
 * A :class:`Symfony\\Component\\Routing\\RequestContext`, which has information about the request
-* A :class:`Symfony\\Component\\Routing\\Matcher\\UrlMatcher`, which performs the mapping of the request to a single route
+* A :class:`Symfony\\Component\\Routing\\Matcher\\UrlMatcher`, which performs the mapping of the path to a single route
 
 Here is a quick example. Notice that this assumes that you've already configured
 your autoloader to load the Routing component::
@@ -423,7 +423,7 @@ routes with UTF-8 characters:
     .. code-block:: yaml
 
         route1:
-            path:     /category/{name}
+            path:       /category/{name}
             controller: App\Controller\DefaultController::category
             options:
                 utf8: true
@@ -492,8 +492,8 @@ You can also include UTF-8 strings as routing requirements:
     .. code-block:: yaml
 
         route2:
-            path:     /category/{name}
-            controller: 'App\Controller\DefaultController::category'
+            path:       /category/{name}
+            controller: App\Controller\DefaultController::category
             defaults:
                 name: "한국어"
             options:

routing.rst

@@ -27,7 +27,16 @@ route that can match *any* URL like ``/blog/my-post`` or
 ``/blog/all-about-symfony``.
 
 Routes can be configured in YAML, XML, PHP or annotations. All formats provide
-the same features and performance, so choose the one you prefer:
+the same features and performance, so choose the one you prefer. If you choose
+PHP annotations, run this command once in your application to add support for
+them (``SensioFrameworkExtraBundle`` wraps the required dependencies and
+provides many useful annotations for cache, security and more!):
+
+.. code-block:: terminal
+
+    $ composer require annotations
+
+Now you can configure the routes:
 
 .. configuration-block::
 
@@ -217,8 +226,12 @@ Symfony provides a handy way to declare localized routes without duplication.
         use App\Controller\CompanyController;
 
         return function (RoutingConfigurator $routes) {
-            $routes->add('about_us', ['nl' => '/over-ons', 'en' => '/about-us'])
-                ->controller([CompanyController::class, 'about']);
+            $routes->add('about_us', [
+                'nl' => '/over-ons',
+                'en' => '/about-us',
+            ])
+                ->controller([CompanyController::class, 'about'])
+            ;
         };
 
 When a localized route is matched Symfony automatically knows which locale
@@ -601,7 +614,7 @@ As your app grows, you'll eventually have a *lot* of routes! To see them all, ru
     ------------------------------ -------- -------------------------------------
      Name                           Method   Path
     ------------------------------ -------- -------------------------------------
-     app_lucky_number              ANY    /lucky/number/{max}
+     app_lucky_number               ANY      /lucky/number/{max}
      ...
     ------------------------------ -------- -------------------------------------
 

routing/external_resources.rst

@@ -19,7 +19,7 @@ This can be done by importing routing resources from the main routing file:
         # config/routes.yaml
         app_file:
             # loads routes from the given routing file stored in some bundle
-            resource: '@AcmeOtherBundle/Resources/config/routing.yaml'
+            resource: '@AcmeBundle/Resources/config/routing.yaml'
 
         app_annotations:
             # loads routes from the PHP annotations of the controllers found in that directory
@@ -46,7 +46,7 @@ This can be done by importing routing resources from the main routing file:
                 https://symfony.com/schema/routing/routing-1.0.xsd">
 
             <!-- loads routes from the given routing file stored in some bundle -->
-            <import resource="@AcmeOtherBundle/Resources/config/routing.yaml"/>
+            <import resource="@AcmeBundle/Resources/config/routing.yaml"/>
 
             <!-- loads routes from the PHP annotations of the controllers found in that directory -->
             <import resource="../src/Controller/" type="annotation"/>
@@ -65,7 +65,7 @@ This can be done by importing routing resources from the main routing file:
 
         return function (RoutingConfigurator $routes) {
             // loads routes from the given routing file stored in some bundle
-            $routes->import('@AcmeOtherBundle/Resources/config/routing.yaml');
+            $routes->import('@AcmeBundle/Resources/config/routing.yaml');
 
             // loads routes from the PHP annotations of the controllers found in that directory
             $routes->import('../src/Controller/', 'annotation');
@@ -74,7 +74,7 @@ This can be done by importing routing resources from the main routing file:
             $routes->import('../legacy/routing/', 'directory');
 
             // loads routes from the YAML or XML files found in some bundle directory
-            $routes->import('@AcmeOtherBundle/Resources/config/routing/public/', 'directory');
+            $routes->import('@AcmeOtherBundle/Resources/config/routing/', 'directory');
         };
 
 .. note::
@@ -88,8 +88,8 @@ Prefixing the URLs of Imported Routes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can also choose to provide a "prefix" for the imported routes. For example,
-suppose you want to prefix all application routes with ``/site`` (e.g.
-``/site/blog/{slug}`` instead of ``/blog/{slug}``):
+to prefix all application routes with ``/site`` (e.g. ``/site/blog/{slug}``
+instead of ``/blog/{slug}``):
 
 .. configuration-block::
 
@@ -166,8 +166,7 @@ be prefixed with the string ``/site``.
                 xsi:schemaLocation="http://symfony.com/schema/routing
                     https://symfony.com/schema/routing/routing-1.0.xsd">
 
-                <import
-                    resource="../src/Controller/"
+                <import resource="../src/Controller/"
                     type="annotation"
                     prefix="/site"
                     trailing-slash-on-root="false"/>
@@ -201,7 +200,7 @@ a controller class or imported from a configuration file:
         /**
          * @Route(name="blog_")
          */
-        class BlogController extends AbstractController
+        class BlogController
         {
             /**
              * @Route("/blog", name="index")
@@ -237,8 +236,7 @@ a controller class or imported from a configuration file:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <import
-                resource="../src/Controller/"
+            <import resource="../src/Controller/"
                 type="annotation"
                 name-prefix="blog_"/>
         </routes>

routing/optional_placeholders.rst

@@ -14,8 +14,7 @@ the available blog posts for this imaginary blog application:
         // src/Controller/BlogController.php
         use Symfony\Component\Routing\Annotation\Route;
 
-        // ...
-        class BlogController extends AbstractController
+        class BlogController
         {
             /**
              * @Route("/blog")