[Form] Fixed outstanding issues mentioned in the PR

CHANGELOG-2.1.md

@@ -168,7 +168,7 @@ To get the diff between two versions, go to https://github.com/symfony/symfony/c
 
  * [BC BREAK] greatly improved `ChoiceListInterface` and all of its
    implementations. `EntityChoiceList` was adapted, the methods `getEntities()`,
-   `getEntitiesByByKeys()`, `getIdentifier()` and `getIdentifierValues()` were
+   `getEntitiesByKeys()`, `getIdentifier()` and `getIdentifierValues()` were
    removed/made private. Instead of the first two you can use `getChoices()`
    and `getChoicesByValues()`, for the latter two no replacement exists.
    `ArrayChoiceList` was replaced by `SimpleChoiceList`.

UPGRADE-2.1.md

@@ -92,12 +92,12 @@ UPGRADE FROM 2.0 to 2.1
   choice field has changed
   
     Instead of using the choice value, a generated integer is now stored.
-   Again, take care if your Javascript reads this value. If your choice field
+    Again, take care if your Javascript reads this value. If your choice field
-   is a non-expanded single-choice field, or if the choices are guaranteed not
+    is a non-expanded single-choice field, or if the choices are guaranteed not
-   to contain the empty string '' (which is the case when you added it manually
+    to contain the empty string '' (which is the case when you added it manually
-   or when the field is a single-choice field and is not required), you can
+    or when the field is a single-choice field and is not required), you can
-   restore the old behaviour by setting the option "value_strategy" to
+    restore the old behaviour by setting the option "value_strategy" to
-   `ChoiceList::COPY_CHOICE`.
+    `ChoiceList::COPY_CHOICE`.
 
 * In the template of the choice type, the structure of the "choices" variable
   has changed

src/Symfony/Bridge/Doctrine/Form/ChoiceList/EntityChoiceList.php

@@ -73,8 +73,10 @@ class EntityChoiceList extends ObjectChoiceList
      * @param string                $class        The class name
      * @param string                $labelPath    The property path used for the label
      * @param EntityLoaderInterface $entityLoader An optional query builder
-     * @param array                 $entities      An array of choices
+     * @param array                 $entities     An array of choices
-     * @param string                $groupPath
+     * @param string                $groupPath    A property path pointing to the property used
+     *                                            to group the choices. Only allowed if
+     *                                            the choices are given as flat array.
      */
     public function __construct(ObjectManager $manager, $class, $labelPath = null, EntityLoaderInterface $entityLoader = null, $entities = null, $groupPath = null)
     {

src/Symfony/Bridge/Doctrine/Form/ChoiceList/EntityLoaderInterface.php

@@ -21,17 +21,19 @@ interface EntityLoaderInterface
     /**
      * Returns an array of entities that are valid choices in the corresponding choice list.
      *
-     * @return array
+     * @return array The entities.
      */
     function getEntities();
 
     /**
      * Returns an array of entities matching the given identifiers.
      *
-     * @param string $identifier
+     * @param string $identifier The identifier field of the object. This method
-     * @param array $values
+     *                           is not applicable for fields with multiple
+     *                           identifiers.
+     * @param array  $values     The values of the identifiers.
      *
-     * @return array
+     * @return array The entities.
      */
     function getEntitiesByIds($identifier, array $values);
 }

src/Symfony/Component/Form/Extension/Core/ChoiceList/ChoiceListInterface.php

@@ -51,6 +51,20 @@ interface ChoiceListInterface
      * Returns the choice views of the preferred choices as nested array with
      * the choice groups as top-level keys.
      *
+     * Example:
+     *
+     * <source>
+     * array(
+     *     'Group 1' => array(
+     *         10 => ChoiceView object,
+     *         20 => ChoiceView object,
+     *     ),
+     *     'Group 2' => array(
+     *         30 => ChoiceView object,
+     *     ),
+     * )
+     * </source>
+     *
      * @return array A nested array containing the views with the corresponding
      *               choice indices as keys on the lowest levels and the choice
      *               group names in the keys of the higher levels.
@@ -61,6 +75,20 @@ interface ChoiceListInterface
      * Returns the choice views of the choices that are not preferred as nested
      * array with the choice groups as top-level keys.
      *
+     * Example:
+     *
+     * <source>
+     * array(
+     *     'Group 1' => array(
+     *         10 => ChoiceView object,
+     *         20 => ChoiceView object,
+     *     ),
+     *     'Group 2' => array(
+     *         30 => ChoiceView object,
+     *     ),
+     * )
+     * </source>
+     *
      * @return array A nested array containing the views with the corresponding
      *               choice indices as keys on the lowest levels and the choice
      *               group names in the keys of the higher levels.

src/Symfony/Component/Form/Extension/Core/ChoiceList/SimpleChoiceList.php

@@ -120,12 +120,12 @@ class SimpleChoiceList extends ChoiceList
 
 
     /**
-    * Converts the choices to a valid PHP array keys.
+     * Converts the choices to valid PHP array keys.
      *
-    * @param array $choices The choices.
+     * @param array $choices The choices.
-    *
+     *
-    * @return array Valid PHP array keys.
+     * @return array Valid PHP array keys.
-    */
+     */
     protected function fixChoices(array $choices)
     {
         return $this->fixIndices($choices);

src/Symfony/Component/Form/Extension/Core/DataTransformer/ChoiceToValueTransformer.php

@@ -53,7 +53,7 @@ class ChoiceToValueTransformer implements DataTransformerInterface
         $choices = $this->choiceList->getChoicesForValues(array($value));
 
         if (count($choices) !== 1) {
-            throw new TransformationFailedException('The choice "' . $value . '" does not exist');
+            throw new TransformationFailedException('The choice "' . $value . '" does not exist or is not unique');
         }
 
         $choice = current($choices);