[PSR-19] Proposal for adding route tag

proposed/phpdoc-tags.md

@@ -21,18 +21,19 @@ PSR-19: PHPDoc tags
   - [5.5.  @generated](#55-generated)
   - [5.6.  @internal](#56-internal)
   - [5.7.  @link](#57-link)
-  - [5.8.  @method](#58-method)
-  - [5.9.  @package](#59-package)
-  - [5.10. @param](#510-param)
-  - [5.11. @property](#511-property)
-  - [5.12. @return](#512-return)
-  - [5.13. @see](#513-see)
-  - [5.14. @since](#514-since)
-  - [5.15. @throws](#515-throws)
-  - [5.16. @todo](#516-todo)
-  - [5.17. @uses](#517-uses)
-  - [5.18. @var](#518-var)
-  - [5.19. @version](#519-version)
+  - [5.8.  @route](#58-route)
+  - [5.9.  @method](#59-method)
+  - [5.10. @package](#510-package)
+  - [5.11. @param](#511-param)
+  - [5.12. @property](#512-property)
+  - [5.13. @return](#513-return)
+  - [5.14. @see](#514-see)
+  - [5.15. @since](#515-since)
+  - [5.16. @throws](#516-throws)
+  - [5.17. @todo](#517-todo)
+  - [5.18. @uses](#518-uses)
+  - [5.19. @var](#519-var)
+  - [5.20. @version](#520-version)
 
 ## 1. Introduction
 
@@ -501,7 +502,63 @@ function count()
 }
 ```
 
-### 5.8. @method
+### 5.8. @route
+
+The `@route` tag indicates the HTTP endpoint(s) associated with the
+"class", "method", or "action" it is documented on.
+
+#### Syntax
+
+    @route [HTTP_METHODS] [PATH]
+
+Where:
+- `HTTP_METHODS` — one or more HTTP methods (GET, POST, PUT, DELETE, etc.), separated by `|`.
+- `PATH` — the route path relative to the application root.
+
+#### Description
+
+The `@route` tag can be used to document the route(s) that a class or
+method handles, typically in controllers or action classes.  
+This provides developers and tools with clear metadata about HTTP endpoints, improving readability, IDE navigation, and API documentation generation.
+
+This tag is intended for internal reference and documentation purposes.  
+It does **not** enforce routing behavior, which remains the responsibility of the framework or application.
+
+#### Examples
+
+```php
+/**
+ * Handles creation of a resource.
+ *
+ * @route POST /resource/create
+ */
+class ResourceCreateAction
+{
+    // ...
+}
+
+/**
+ * Retrieves a list of resources.
+ *
+ * @route GET /resource/list
+ */
+class ResourceListAction
+{
+    // ...
+}
+
+/**
+ * Updates or processes a resource.
+ *
+ * @route PUT|PATCH /resource/{id}/update
+ */
+class ResourceUpdateAction
+{
+    // ...
+}
+```
+
+### 5.9. @method
 
 The @method allows a class to know which 'magic' methods are callable.
 
@@ -551,7 +608,7 @@ class Child extends Parent
 }
 ```
 
-### 5.9. @package
+### 5.10. @package
 
 The @package tag is used to categorize "Structural Elements" into logical
 subdivisions.
@@ -588,7 +645,7 @@ This tag MUST NOT occur more than once in a "DocBlock".
  */
 ```
 
-### 5.10. @param
+### 5.11. @param
 
 The @param tag is used to document a single parameter of a function or method.
 
@@ -631,7 +688,7 @@ function count(array $items)
 }
 ```
 
-### 5.11. @property
+### 5.12. @property
 
 The `@property` tag is used to declare which "magic" properties are supported.
 
@@ -680,7 +737,7 @@ class User
 }
 ```
 
-### 5.12. @return
+### 5.13. @return
 
 The @return tag is used to document the return value of functions or methods.
 
@@ -723,7 +780,7 @@ function getLabel()
 }
 ```
 
-### 5.13. @see
+### 5.14. @see
 
 The @see tag indicates a reference from the associated "Structural Elements" to
 a website or other "Structural Elements".
@@ -763,7 +820,7 @@ function count()
 }
 ```
 
-### 5.14. @since
+### 5.15. @since
 
 The @since tag is used to denote _when_ an element was introduced or modified,
 using some description of "versioning" to that element.
@@ -813,7 +870,7 @@ class Foo
 }
 ```
 
-### 5.15. @throws
+### 5.16. @throws
 
 The @throws tag is used to indicate whether "Structural Elements" throw a
 specific type of Throwable (exception or error).
@@ -856,7 +913,7 @@ function count($items)
 }
 ```
 
-### 5.16. @todo
+### 5.17. @todo
 
 The @todo tag is used to indicate whether any development activities should
 still be executed on associated "Structural Elements".
@@ -888,7 +945,7 @@ function count()
 }
 ```
 
-### 5.17. @uses
+### 5.18. @uses
 
 Indicates whether the current "Structural Element" consumes the
 "Structural Element", or project file, that is provided as target.
@@ -937,7 +994,7 @@ function executeMyView()
 }
 ```
 
-### 5.18. @var
+### 5.19. @var
 
 You may use the @var tag to document the "Type" of the following
 "Structural Elements":
@@ -1056,7 +1113,7 @@ class Foo
 }
 ```
 
-### 5.19. @version
+### 5.20. @version
 
 The @version tag is used to denote some description of "versioning" to an
 element.