From 656d45f06aa9208cce73aee1f6343477631ae47d Mon Sep 17 00:00:00 2001
From: Jerome TAMARELLE <jerome@tamarelle.net>
Date: Mon, 17 Nov 2014 14:53:37 +0100
Subject: [PATCH] [Form] Add doc for FormEvents

---
 src/Symfony/Component/Form/FormEvents.php | 31 +++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/src/Symfony/Component/Form/FormEvents.php b/src/Symfony/Component/Form/FormEvents.php
index 2bdd585251..54c72271c7 100644
--- a/src/Symfony/Component/Form/FormEvents.php
+++ b/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';