[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`.

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

@@ -74,7 +74,9 @@ class EntityChoiceList extends ObjectChoiceList
      * @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 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,7 +120,7 @@ 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.
      *

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);