feature #18685 move event listener method type hint docs to @Event annotations defau… (Haehnchen)

This PR was submitted for the 3.0 branch but it was merged into the 3.1-dev branch instead (closes #18685). Discussion ---------- move event listener method type hint docs to @Event annotations defau… | Q | A | ------------- | --- | Branch? | 3.0 | Bug fix? | no | New feature? | no | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | | License | MIT | Doc PR | reference to the documentation PR, if any I moved all `listener method receives a "*"` from php docs to "@Event". makes them parsable by PhpStorm Plugin without extract class names out of comments. This helps to prefill type hints on method creation. There is also a fallback for doccomments, but it would be much easier to provide a common structure eg for external libs. see also #18684, which adds some missing "@Events" External issue: https://github.com/Haehnchen/idea-php-symfony2-plugin/issues/493 ![phpstorm-events-method](https://cloud.githubusercontent.com/assets/1011712/14941660/e214f546-0fa3-11e6-8d2e-fa6fc7a6f201.png) Commits ------- f2c0446 move event listener method type hint docs to @Event annotations default value. makes it easily parsable by PhpStorm plugin
2016-05-03 20:48:46 +02:00 · 2016-05-03 20:48:46 +02:00 · 6857c36576
commit 6857c36576
parent cab3f45a77 f2c04464d8
5 changed files with 25 additions and 63 deletions
--- a/src/Symfony/Component/Console/ConsoleEvents.php
+++ b/src/Symfony/Component/Console/ConsoleEvents.php
@ -23,10 +23,7 @@ final class ConsoleEvents
     * executed by the console. It also allows you to modify the command, input and output
     * before they are handled to the command.
     *
-     * The event listener method receives a Symfony\Component\Console\Event\ConsoleCommandEvent
-     * instance.
-     *
-     * @Event
+     * @Event("Symfony\Component\Console\Event\ConsoleCommandEvent")
     *
     * @var string
     */
@ -36,10 +33,7 @@ final class ConsoleEvents
     * The TERMINATE event allows you to attach listeners after a command is
     * executed by the console.
     *
-     * The event listener method receives a Symfony\Component\Console\Event\ConsoleTerminateEvent
-     * instance.
-     *
-     * @Event
+     * @Event("Symfony\Component\Console\Event\ConsoleTerminateEvent")
     *
     * @var string
     */
@ -49,11 +43,9 @@ final class ConsoleEvents
     * The EXCEPTION event occurs when an uncaught exception appears.
     *
     * This event allows you to deal with the exception or
-     * to modify the thrown exception. The event listener method receives
-     * a Symfony\Component\Console\Event\ConsoleExceptionEvent
-     * instance.
+     * to modify the thrown exception.
     *
-     * @Event
+     * @Event("Symfony\Component\Console\Event\ConsoleExceptionEvent")
     *
     * @var string
     */
--- a/src/Symfony/Component/Form/FormEvents.php
+++ b/src/Symfony/Component/Form/FormEvents.php
@ -28,9 +28,8 @@ final class FormEvents
     * It can be used to:
     *  - Change data from the request, before submitting the data to the form.
     *  - Add or remove form fields, before submitting the data to the form.
-     * The event listener method receives a Symfony\Component\Form\FormEvent instance.
     *
-     * @Event
+     * @Event("Symfony\Component\Form\FormEvent")
     */
    const PRE_SUBMIT = 'form.pre_bind';

@ -39,9 +38,8 @@ final class FormEvents
     * transforms back the normalized data to the model and view data.
     *
     * It can be used to change data from the normalized representation of the data.
-     * The event listener method receives a Symfony\Component\Form\FormEvent instance.
     *
-     * @Event
+     * @Event("Symfony\Component\Form\FormEvent")
     */
    const SUBMIT = 'form.bind';

@ -50,9 +48,8 @@ final class FormEvents
     * once the model and view data have been denormalized.
     *
     * It can be used to fetch data after denormalization.
-     * The event listener method receives a Symfony\Component\Form\FormEvent instance.
     *
-     * @Event
+     * @Event("Symfony\Component\Form\FormEvent")
     */
    const POST_SUBMIT = 'form.post_bind';

@ -62,9 +59,8 @@ final class FormEvents
     * It can be used to:
     *  - Modify the data given during pre-population;
     *  - Modify a form depending on the pre-populated data (adding or removing fields dynamically).
-     * The event listener method receives a Symfony\Component\Form\FormEvent instance.
     *
-     * @Event
+     * @Event("Symfony\Component\Form\FormEvent")
     */
    const PRE_SET_DATA = 'form.pre_set_data';

@ -72,9 +68,8 @@ final class FormEvents
     * The FormEvents::POST_SET_DATA event is dispatched at the end of the Form::setData() method.
     *
     * This event is mostly here for reading data after having pre-populated the form.
-     * The event listener method receives a Symfony\Component\Form\FormEvent instance.
     *
-     * @Event
+     * @Event("Symfony\Component\Form\FormEvent")
     */
    const POST_SET_DATA = 'form.post_set_data';

--- a/src/Symfony/Component/HttpKernel/KernelEvents.php
+++ b/src/Symfony/Component/HttpKernel/KernelEvents.php
@ -23,11 +23,9 @@ final class KernelEvents
     * dispatching.
     *
     * This event allows you to create a response for a request before any
-     * other code in the framework is executed. The event listener method
-     * receives a Symfony\Component\HttpKernel\Event\GetResponseEvent
-     * instance.
+     * other code in the framework is executed.
     *
-     * @Event
+     * @Event("Symfony\Component\HttpKernel\Event\GetResponseEvent")
     *
     * @var string
     */
@ -37,11 +35,9 @@ final class KernelEvents
     * The EXCEPTION event occurs when an uncaught exception appears.
     *
     * This event allows you to create a response for a thrown exception or
-     * to modify the thrown exception. The event listener method receives
-     * a Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent
-     * instance.
+     * to modify the thrown exception.
     *
-     * @Event
+     * @Event("Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent")
     *
     * @var string
     */
@ -52,11 +48,9 @@ final class KernelEvents
     * is not a Response instance.
     *
     * This event allows you to create a response for the return value of the
-     * controller. The event listener method receives a
-     * Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent
-     * instance.
+     * controller.
     *
-     * @Event
+     * @Event("Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent")
     *
     * @var string
     */
@ -67,10 +61,9 @@ final class KernelEvents
     * handling a request.
     *
     * This event allows you to change the controller that will handle the
-     * request. The event listener method receives a
-     * Symfony\Component\HttpKernel\Event\FilterControllerEvent instance.
+     * request.
     *
-     * @Event
+     * @Event("Symfony\Component\HttpKernel\Event\FilterControllerEvent")
     *
     * @var string
     */
@ -94,10 +87,9 @@ final class KernelEvents
     * replying to a request.
     *
     * This event allows you to modify or replace the response that will be
-     * replied. The event listener method receives a
-     * Symfony\Component\HttpKernel\Event\FilterResponseEvent instance.
+     * replied.
     *
-     * @Event
+     * @Event("Symfony\Component\HttpKernel\Event\FilterResponseEvent")
     *
     * @var string
     */
@ -107,10 +99,8 @@ final class KernelEvents
     * The TERMINATE event occurs once a response was sent.
     *
     * This event allows you to run expensive post-response jobs.
-     * The event listener method receives a
-     * Symfony\Component\HttpKernel\Event\PostResponseEvent instance.
     *
-     * @Event
+     * @Event("Symfony\Component\HttpKernel\Event\PostResponseEvent")
     *
     * @var string
     */
@ -121,10 +111,8 @@ final class KernelEvents
     *
     * This event allows you to reset the global and environmental state of
     * the application, when it was changed during the request.
-     * The event listener method receives a
-     * Symfony\Component\HttpKernel\Event\FinishRequestEvent instance.
     *
-     * @Event
+     * @Event("Symfony\Component\HttpKernel\Event\FinishRequestEvent")
     *
     * @var string
     */
--- a/src/Symfony/Component/Security/Core/AuthenticationEvents.php
+++ b/src/Symfony/Component/Security/Core/AuthenticationEvents.php
@ -17,10 +17,7 @@ final class AuthenticationEvents
     * The AUTHENTICATION_SUCCESS event occurs after a user is authenticated
     * by one provider.
     *
-     * The event listener method receives a
-     * Symfony\Component\Security\Core\Event\AuthenticationEvent instance.
-     *
-     * @Event
+     * @Event("Symfony\Component\Security\Core\Event\AuthenticationEvent")
     *
     * @var string
     */
@ -30,11 +27,7 @@ final class AuthenticationEvents
     * The AUTHENTICATION_FAILURE event occurs after a user cannot be
     * authenticated by any of the providers.
     *
-     * The event listener method receives a
-     * Symfony\Component\Security\Core\Event\AuthenticationFailureEvent
-     * instance.
-     *
-     * @Event
+     * @Event("Symfony\Component\Security\Core\Event\AuthenticationFailureEvent")
     *
     * @var string
     */
--- a/src/Symfony/Component/Security/Http/SecurityEvents.php
+++ b/src/Symfony/Component/Security/Http/SecurityEvents.php
@ -17,10 +17,7 @@ final class SecurityEvents
     * The INTERACTIVE_LOGIN event occurs after a user is logged in
     * interactively for authentication based on http, cookies or X509.
     *
-     * The event listener method receives a
-     * Symfony\Component\Security\Http\Event\InteractiveLoginEvent instance.
-     *
-     * @Event
+     * @Event("Symfony\Component\Security\Http\Event\InteractiveLoginEvent")
     *
     * @var string
     */
@ -30,10 +27,7 @@ final class SecurityEvents
     * The SWITCH_USER event occurs before switch to another user and
     * before exit from an already switched user.
     *
-     * The event listener method receives a
-     * Symfony\Component\Security\Http\Event\SwitchUserEvent instance.
-     *
-     * @Event
+     * @Event("Symfony\Component\Security\Http\Event\SwitchUserEvent")
     *
     * @var string
     */