diff --git a/routing.rst b/routing.rst
index 4ab0dce2a82..43689e1940f 100644
--- a/routing.rst
+++ b/routing.rst
@@ -1307,8 +1307,34 @@ Route Aliasing
 
 Route alias allow you to have multiple name for the same route:
 
+.. note::
+
+    In next code examples in YAML, XML and PHP, ``original_route_name`` is an existing route,
+    ``new_route_name`` is a new route whose alias refers to ``original_route_name``.
+
+    In Attribute code example, ``original_route_name`` is NOT an existing route.
+    ``new_route_name`` is the new name of a route which was previously named ``original_route_name``.
+
 .. configuration-block::
 
+    .. code-block:: php-attributes
+
+        // src/Controller/DefaultController.php
+        namespace App\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+        use Symfony\Component\HttpFoundation\Response;
+        use Symfony\Component\Routing\Attribute\Route;
+
+        class DefaultController extends AbstractController
+        {
+            #[Route('/path', name: 'new_route_name', alias: ['original_route_name'])]
+            public function action(): Response
+            {
+                // ...
+            }
+        }
+
     .. code-block:: yaml
 
         # config/routes.yaml
@@ -1349,6 +1375,44 @@ you decided not to maintain it anymore), you can deprecate its definition:
 
 .. configuration-block::
 
+    .. code-block:: php-attributes
+
+        // src/Controller/DefaultController.php
+        namespace App\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+        use Symfony\Component\HttpFoundation\Response;
+        use Symfony\Component\Routing\Attribute\Route;
+
+        class DefaultController extends AbstractController
+        {
+            // 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.
+            #[Route('/path',
+                name: 'new_route_name',
+                alias: new DeprecatedAlias(aliasName: 'original_route_name', package: 'acme/package', version: '1.2')
+            )]
+            // you can also define a custom deprecation message (%alias_id% placeholder is available)
+            #[Route('/path',
+                name: 'new_route_name',
+                alias: new DeprecatedAlias(aliasName: 'original_route_name', package: 'acme/package', version: '1.2', message: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.')
+            )]
+            public function action(): Response
+            {
+                // ...
+            }
+
+            #[Route('/path', name: 'new_route_name', alias: [
+                new DeprecatedAlias('first_original_route_name', 'acme/package', '1.0'),
+                new DeprecatedAlias('second_original_route_name', 'acme/package', '2.0'),
+                new DeprecatedAlias('third_original_route_name', 'acme/package', '3.0'),
+            ])]
+            public function another_action()
+            {
+                // ...
+            }
+        }
+
     .. code-block:: yaml
 
         new_route_name: