minor #12496 [Form] Add doc for FormEvents (GromNaN)

This PR was merged into the 2.3 branch.

Discussion
----------

[Form] Add doc for FormEvents

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | no
| Fixed tickets | n/a
| License       | MIT
| Doc PR        | n/a

Provide the same level of phpdoc for form events than we have for other event classes.

http://api.symfony.com/2.3/Symfony/Component/HttpKernel/KernelEvents.html
http://api.symfony.com/2.3/Symfony/Component/Form/FormEvents.html

Commits
-------

656d45f [Form] Add doc for FormEvents

src/Symfony/Component/Form/FormEvents.php

@@ -16,26 +16,57 @@ namespace Symfony\Component\Form;
 final class FormEvents
 {
     /**
+     * The PRE_SUBMIT event is dispatched at the beginning of the Form::submit() method.
+     *
+     * 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
      */
     const PRE_SUBMIT = 'form.pre_bind';
 
     /**
+     * The SUBMIT event is dispatched just before the Form::submit() method
+     * 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
      */
     const SUBMIT = 'form.bind';
 
     /**
+     * The FormEvents::POST_SUBMIT event is dispatched after the Form::submit()
+     * 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
      */
     const POST_SUBMIT = 'form.post_bind';
 
     /**
+     * The FormEvents::PRE_SET_DATA event is dispatched at the beginning of the Form::setData() method.
+     *
+     * 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
      */
     const PRE_SET_DATA = 'form.pre_set_data';
 
     /**
+     * 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
      */
     const POST_SET_DATA = 'form.post_set_data';