Enhanced documentation to clearify the require option and added the o…

…ption for symfony/symfony#9773

reference/forms/types/collection.rst

@@ -19,13 +19,15 @@ forms, which is useful when creating forms that expose one-to-many relationships
 |             | - `allow_delete`_                                                           |
 |             | - `prototype`_                                                              |
 |             | - `prototype_name`_                                                         |
+|             | - `delete_empty`_                                                           |
 +-------------+-----------------------------------------------------------------------------+
 | Inherited   | - `label`_                                                                  |
 |             | - `label_attr`_                                                             |
 | options     | - `error_bubbling`_                                                         |
 |             | - `error_mapping`_                                                          |
 |             | - `by_reference`_                                                           |
 |             | - `empty_data`_                                                             |
+|             | - `required`_                                                               |
 |             | - `mapped`_                                                                 |
 +-------------+-----------------------------------------------------------------------------+
 | Parent type | :doc:`form </reference/forms/types/form>`                                   |
@@ -334,6 +336,16 @@ If you have several collections in your form, or worse, nested collections
 you may want to change the placeholder so that unrelated placeholders are not
 replaced with the same value.
 
+delete_empty
+~~~~~~~~~~~~~~
+
+**type**: ``Boolean`` **default**: ``false``
+
+If you want to explicitly remove entirely empty collection entries from your
+form you have to set this option to true. Existing collection entries will
+however only be deleted if you have `allow_delete`_ option enabled, otherwise
+the empty values will be kept.
+
 Inherited options
 -----------------
 
@@ -359,4 +371,6 @@ error_bubbling
 
 .. include:: /reference/forms/types/options/empty_data.rst.inc
 
+.. include:: /reference/forms/types/options/required.rst.inc
+
 .. include:: /reference/forms/types/options/mapped.rst.inc

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

@@ -8,17 +8,13 @@ choice is selected.
 
 The true default value of this option depends on the field options:
 
-* If ``compound`` is ``true`` and ``data_class`` is set, then ``new $data_class()``;
-* If ``compound`` is ``true`` and no ``data_class`` is set, then ``array()``;
-* If ``compound`` is ``false``, then ``null``.
+* If ``required`` is ``true`` and ``data_class`` is set, then ``new $data_class()``;
+* If ``required`` is ``true`` and no ``data_class`` is set, then ``array()``;
+* If ``required`` is ``false``, then ``null``.
 
-.. tip::
 
-    The ``compound`` option is set to ``true`` when the field actually represents
-    a collection of fields (e.g. a form of fields).
-
-For example, if you want the ``gender`` field to be set to ``null`` when no
-value is selected, you can do it like this:
+But you can customize this to your needs. For example, if you want the ``gender`` field to be
+set to explicitly ``null`` when no value is selected, you can do it like this:
 
 .. code-block:: php
 

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

@@ -10,4 +10,9 @@ This is superficial and independent from validation. At best, if you let Symfony
 guess your field type, then the value of this option will be guessed from
 your validation information.
 
-.. _`HTML5 required attribute`: http://diveintohtml5.info/forms.html
+.. _`HTML5 required attribute`: http://diveintohtml5.info/forms.html
+
+.. note::
+
+The required option does also affect the way how empty data of your form is
+being handled. For further details check the :doc:` empty_data</reference/forms/types/options/empty_data.rst.inc>` option.