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

Author: welcoMattic

routing.rst

@@ -1343,8 +1343,12 @@ Route alias allow you to have multiple name for the same route:
     .. code-block:: yaml
 
         # config/routes.yaml
-        new_route_name:
-            alias: original_route_name
+        some_route_name:
+            path: /some-path
+            controller: App\Controller\SomeController::index
+
+        alias_to_some_route_name:
+            alias: some_route_name # refers to the name of the route declared above
 
     .. code-block:: xml
 
@@ -1355,7 +1359,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="alias_to_some_route_name" alias="some_route_name"/>
         </routes>
 
     .. code-block:: php
@@ -1364,10 +1370,13 @@ 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('alias_to_some_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 ``alias_to_some_route_name`` routes can
 be used in the application and will produce the same result.
 
 .. _routing-alias-deprecation:
@@ -1382,11 +1391,15 @@ you decided not to maintain it anymore), you can deprecate its definition:
 
     .. code-block:: yaml
 
-        new_route_name:
-            alias: original_route_name
+        some_route_name:
+            path: /some-path
+            controller: App\Controller\SomeController::index
+
+        alias_to_some_route_name:
+            alias: some_route_name # refers to the name of the route declared above
 
             # 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 "alias_to_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'
@@ -1405,9 +1418,11 @@ 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">
+            <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="alias_to_some_route_name" alias="some_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 "alias_to_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"/>
 
                 <!-- you can also define a custom deprecation message (%alias_id% placeholder is available) -->
@@ -1419,9 +1434,12 @@ you decided not to maintain it anymore), you can deprecate its definition:
 
     .. code-block:: php
 
-        $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('alias_to_some_route_name', 'some_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 "alias_to_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', '')
 
             // you can also define a custom deprecation message (%alias_id% placeholder is available)
@@ -1432,7 +1450,7 @@ you decided not to maintain it anymore), you can deprecate its definition:
             )
         ;
 
-In this example, every time the ``new_route_name`` alias is used, a deprecation
+In this example, every time the ``alias_to_some_route_name`` alias is used, a deprecation
 warning is triggered, advising you to stop using that alias.
 
 The message is actually a message template, which replaces occurrences of the