[#3098] Tweaks to entity "choices" options

Biggest thing was to make it clear that choices is a valid thing to set when using the
entity type, but it's not the most common way of providing options.

Author: weaverryan

reference/forms/types/entity.rst

@@ -18,8 +18,8 @@ objects from the database.
 |             | - `query_builder`_                                               |
 |             | - `em`_                                                          |
 +-------------+------------------------------------------------------------------+
-| Overridden  | - `choices`                                                      |
-| Options     | - `choice_list`                                                  |
+| Overridden  | - `choices`_                                                     |
+| Options     | - `choice_list`_                                                 |
 +-------------+------------------------------------------------------------------+
 | Inherited   | - `required`_                                                    |
 | options     | - `label`_                                                       |
@@ -55,17 +55,6 @@ as either a ``select`` tag, a set or radio buttons or a series of checkboxes
 If the entity object does not have a ``__toString()`` method the ``property`` option
 is needed.
 
-Using Choices
-~~~~~~~~~~~~~
-
-If you want to limit the entities which are available as choices you can provide
-them by calling the getter function of an entity:
-
-    $builder->add('users', 'entity', array(
-        'class' => 'AcmeHelloBundle:User',
-        'choices' => $group->getUsers(),
-    ));
-
 Using a Custom Query for the Entities
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -84,6 +73,22 @@ option. The easiest way to use the option is as follows::
         },
     ));
 
+.. _reference-forms-entity-choices:
+
+Using Choices
+~~~~~~~~~~~~~
+
+If you already have the exact collection of entities that you want included
+in the choice element, you can simply pass them via the ``choices`` key.
+For example, if you have a ``$group`` variable (passed into your form perhaps
+as a form option) and ``getUsers`` returns a collection of ``User`` entities,
+then you can supply the ``choices`` option directly::
+
+    $builder->add('users', 'entity', array(
+        'class' => 'AcmeHelloBundle:User',
+        'choices' => $group->getUsers(),
+    ));
+
 .. include:: /reference/forms/types/options/select_how_rendered.rst.inc
 
 Field Options
@@ -143,17 +148,21 @@ Overridden Options
 choices
 ~~~~~~~
 
-**type**:  array || ``\Traversable`` **default**: all entities
+**type**:  array || ``\Traversable`` **default**: ``null``
 
-If the choices are provided only these will be available. The choices need to
-be a traversable collection such as the
-``Doctrine\Common\Collections\ArrayCollection`` containing only entities of the
-specified class.
+Instead of allowing the `class`_ and `query_builder`_ options to fetch the
+entities to include for you, you can pass the ``choices`` option directly.
+See :ref:`reference-forms-entity-choices`.
 
 choice_list
 ~~~~~~~~~~~
 
-**default**: ``null``
+**default**: :class:`Symfony\\Bridge\\Doctrine\\Form\\ChoiceList\\EntityChoiceList`
+
+The purpose of the ``entity`` type is to create and configure this ``EntityChoiceList``
+for you, by using all of the above options. If you need to override this
+option, you may just consider using the :doc:`/reference/forms/types/choice`
+directly.
 
 Inherited options
 -----------------