[Form] Make difference between data and empty_data options more visisble

form/use_empty_data.rst

@@ -27,7 +27,14 @@ a ``data_class`` option for your form class, it will default to a new instance
 of that class. That instance will be created by calling the constructor
 with no arguments.
 
-If you want to override this default behavior, there are two ways to do this.
+If you want to override this default behavior, there are two ways to do this:
+
+* `Option 1: Instantiate a new Class`_
+* `Option 2: Provide a Closure`_
+
+If you didn't set the ``data_class`` option, you can pass the initial data as
+string or pass an array of strings (where the key matches the field name) when
+the form type is compound.
 
 Option 1: Instantiate a new Class
 ---------------------------------

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

@@ -1,19 +1,21 @@
 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::
+corresponding property of the form's domain data (e.g. if you bind an object to
+the form). If you want to override this initial value for the form or
+an individual field, you can set it in the data option::
+
 
     $builder->add('token', 'hidden', array(
         'data' => 'abcdef',
     ));
 
-.. note::
+.. caution::
 
-    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.
+    The ``data`` option *always* overrides the value taken from the domain data
+    (object) when rendering. This means the object value is also overriden when
+    the form edits an already persisted object, causing it to lose it's
+    persisted value when the form is submitted.

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

@@ -9,24 +9,35 @@ empty_data
 
 DEFAULT_PLACEHOLDER
 
-This option determines what value the field will return when the submitted
-value is empty.
-
-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::
-
-    $builder->add('gender', 'choice', array(
-        'choices' => array(
-            'm' => 'Male',
-            'f' => 'Female'
-        ),
-        'required'    => false,
-        'placeholder' => 'Choose your gender',
-        'empty_data'  => null
+This option determines what value the field will *return* when the submitted
+value is empty (or missing). It does not set an initial value if none is
+provided when the form is rendered in a view.
+
+This means it helps you handling form submission with blank fields. 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('name', null, array(
+        'required'   => false,
+        'empty_data' => 'John Doe',
     ));
 
+This will still render an empty text box, but upon submission the ``John Doe``
+value will be set. Use the ``data`` or ``placeholder`` options to show this
+initial value in the rendered form.
+
+If a form is compound, you can set ``empty_data`` as an array, object or
+closure. See the :doc:`/form/use_empty_data` article for more details about
+these options.
+
 .. note::
 
     If you want to set the ``empty_data`` option for your entire form class,
     see the :doc:`/form/use_empty_data` article.
+
+.. caution::
+
+    :doc:`Form data transformers </form/data_transformers>` will still be
+    applied to the ``empty_data`` value. This means that an empty string will
+    be cast to ``null``. Use a custom data transformer if you explicitly want
+    to return the empty string.