fix(route-alias): Clarify route aliases examples with explicit route names

Author: welcoMattic

Diff for: routing.rst

@@ -1338,13 +1338,56 @@ Route Aliasing
 
 Route alias allow you to have multiple name for the same route:
 
+Let's say you have a route called ``some_route_name``
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        some_route_name:
+            path: /some-path
+            controller: App\Controller\SomeController::index
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="some_route_name" path="/some-path" controller="App\Controller\SomeController::index"/>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return static function (RoutingConfigurator $routes): void {
+            $routes->add('some_route_name', '/some-path')
+                    ->controller('App\Controller\SomeController::index');
+        };
+
+Now, let's say you want to create a new route called ``new_route_name``
+that acts exactly the same as ``some_route_name``.
+
+Instead of duplicating the original route, you can create an alias for it. You can do this as follows:
+
 .. configuration-block::
 
     .. code-block:: yaml
 
         # config/routes.yaml
+        some_route_name:
+            path: /some-path
+            controller: App\Controller\SomeController::index
+
         new_route_name:
-            alias: original_route_name
+            # "alias" option refers to the name of the route declared above
+            alias: some_route_name
 
     .. code-block:: xml
 
@@ -1355,7 +1398,9 @@ Route alias allow you to have multiple name for the same route:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="new_route_name" alias="original_route_name"/>
+            <route id="some_route_name" path="/some-path" controller="App\Controller\SomeController::index"/>
+            <!-- "alias" attribute value refers to the name of the route declared above -->
+            <route id="new_route_name" alias="some_route_name"/>
         </routes>
 
     .. code-block:: php
@@ -1364,38 +1409,58 @@ Route alias allow you to have multiple name for the same route:
         use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
         return static function (RoutingConfigurator $routes): void {
-            $routes->alias('new_route_name', 'original_route_name');
+            $routes->add('some_route_name', '/some_route_path')
+                    ->controller('App\Controller\SomeController::index');
+            // second argument refers to the name of the route declared above
+            $routes->alias('new_route_name', 'some_route_name');
         };
 
-In this example, both ``original_route_name`` and ``new_route_name`` routes can
+In this example, both ``some_route_name`` and ``new_route_name`` routes can
 be used in the application and will produce the same result.
 
 .. _routing-alias-deprecation:
 
 Deprecating Route Aliases
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If some route alias should no longer be used (because it is outdated or
-you decided not to maintain it anymore), you can deprecate its definition:
+Route aliases can be used to provide backward compatibility for routes that
+have been renamed.
+
+Now, let's say you want to replace the ``some_route_name`` route in favor of
+``new_route_name`` and mark the old one as deprecated.
+
+In the previous example, the alias was ``new_route_name`` was pointing to
+``some_route_name`` route.
+
+As you want to deprecate the ``some_route_name`` route, so let's invert the alias as follows
+to be able to mark it as deprecated using the ``deprecated`` option:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
+        # Move the concrete route definition under ``new_route_name``
         new_route_name:
-            alias: original_route_name
+            path: /some-path
+            controller: App\Controller\SomeController::index
+
+        # Define the alias and the deprecation under the ``some_route_name`` definition
+        some_route_name:
+            alias: new_route_name
 
             # this outputs the following generic deprecation message:
-            # Since acme/package 1.2: The "new_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
+            # Since acme/package 1.2: The "some_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
             deprecated:
                 package: 'acme/package'
                 version: '1.2'
 
+            # or
+
             # you can also define a custom deprecation message (%alias_id% placeholder is available)
             deprecated:
                 package: 'acme/package'
                 version: '1.2'
-                message: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
+                message: 'The "%alias_id%" route alias is deprecated. Please use "new_route_name" instead.'
 
     .. code-block:: xml
 
@@ -1405,35 +1470,46 @@ you decided not to maintain it anymore), you can deprecate its definition:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="new_route_name" alias="original_route_name">
+            <!-- Move the concrete route definition under ``new_route_name`` -->
+            <route id="new_route_name" path="/some-path" controller="App\Controller\SomeController::index"/>
+
+            <!-- Define the alias and the deprecation under the ``some_route_name`` definition -->
+            <route id="some_route_name" alias="new_route_name">
                 <!-- this outputs the following generic deprecation message:
-                     Since acme/package 1.2: The "new_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future. -->
+                     Since acme/package 1.2: The "some_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future. -->
                 <deprecated package="acme/package" version="1.2"/>
 
+                <!-- or -->
+
                 <!-- you can also define a custom deprecation message (%alias_id% placeholder is available) -->
                 <deprecated package="acme/package" version="1.2">
-                    The "%alias_id%" route alias is deprecated. Do not use it anymore.
+                    The "%alias_id%" route alias is deprecated. Please use "new_route_name" instead.
                 </deprecated>
             </route>
         </routes>
 
     .. code-block:: php
 
-        $routes->alias('new_route_name', 'original_route_name')
+        $routes->add('new_route_name', '/some-path')
+                ->controller('App\Controller\SomeController::index');
+
+        $routes->alias('some_route_name', 'new_route_name')
             // this outputs the following generic deprecation message:
-            // Since acme/package 1.2: The "new_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
+            // Since acme/package 1.2: The "some_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
             ->deprecate('acme/package', '1.2', '')
 
+            // or
+
             // you can also define a custom deprecation message (%alias_id% placeholder is available)
             ->deprecate(
                 'acme/package',
                 '1.2',
-                'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
+                'The "%alias_id%" route alias is deprecated. Please use "new_route_name" instead.'
             )
         ;
 
-In this example, every time the ``new_route_name`` alias is used, a deprecation
-warning is triggered, advising you to stop using that alias.
+In this example, every time the ``some_route_name`` alias is used, a deprecation
+warning is triggered, advising you to stop using this route and prefer using ``new_route_name``.
 
 The message is actually a message template, which replaces occurrences of the
 ``%alias_id%`` placeholder by the route alias name. You **must** have