[WIP] [2.7+] explicit differences between 'data' & 'empty_data' options in FormType

reference/forms/types/options/data.rst.inc

@@ -1,19 +1,24 @@
 data
 ~~~~
 
-**type**: ``mixed`` **default**: Defaults to field of the underlying object (if there is one)
+**type**: ``mixed`` **default**: Defaults to field of the underlying structure.
 
-When you create a form, each field initially displays the value of the
-corresponding property of the form's domain object (if an object is bound
-to the form). If you want to override the initial value for the form or
-just an individual field, you can set it in the data option::
+When you attach a form type to a form, it becomes a field that initially maps
+the value of the corresponding property or key of the form's domain data. If
+you want to override the initial value which will be rendered in the view for
+the form or any nested field, you can set it in the data option::
 
     $builder->add('token', 'hidden', array(
         'data' => 'abcdef',
     ));
 
+    // Is the same as
+    $resolver->setDefault('data' => array('token' => 'abcdef'));
+
 .. note::
 
     The default values for form fields are taken directly from the underlying
-    data structure (e.g. an entity or an array). The ``data`` option overrides
-    this default value.
+    data structure matching the field's name with a property of an object or a
+    key of an array. The ``data`` option overrides this default value.
+    It means that when the data passed to the form is an object you want to
+    edit, the `data` option will also override the value already set.

reference/forms/types/options/empty_data.rst.inc

@@ -1,7 +1,7 @@
 empty_data
 ~~~~~~~~~~
 
-**type**: ``mixed``
+**type**: ``string`` or ``array`` when the form is compound
 
 .. This file should only be included with start-after or end-before that's
    set to this placeholder value. Its purpose is to let us include only
@@ -10,23 +10,31 @@ empty_data
 DEFAULT_PLACEHOLDER
 
 This option determines what value the field will return when the submitted
-value is empty.
+value is empty (or missing). It does not set an initial value if none is
+provided when the form is rendered in a view (see ``data`` or ``placeholder``
+options).
 
-But you can customize this to your needs. For example, if you want the
-``gender`` choice field to be explicitly set to ``null`` when no value is
-selected, you can do it like this::
+It helps you handling form submission and you can customize this to your needs.
+For example, if you want the ``name`` field to be explicitly set to ``John Doe``
+when no value is selected, you can do it like this::
 
-    $builder->add('gender', 'choice', array(
-        'choices' => array(
-            'm' => 'Male',
-            'f' => 'Female'
-        ),
+    $builder->add('name', null, array(
         'required'    => false,
-        'empty_value' => 'Choose your gender',
-        'empty_data'  => null
+        'empty_data'  => 'John Doe',
     ));
 
+If a form is compound, you can set ``empty_data`` as an array with field names
+as keys and submitted values as string values (or arrays if nested fields are
+also compound).
+
 .. note::
 
     If you want to set the ``empty_data`` option for your entire form class,
     see the cookbook article :doc:`/cookbook/form/use_empty_data`.
+
+.. caution::
+
+    When using `empty_data` as an empty string, the form will always return
+    ``null``. If you need to get an empty string to be returned, you should
+    use a data transformer, see the cookbook article
+    :doc:`cookbook/form/data_transformers`.