minor #30534 [Form] Fixed some phpdocs (Jules Pietri)

This PR was merged into the 3.4 branch.

Discussion
----------

[Form] Fixed some phpdocs

| Q             | A
| ------------- | ---
| Branch?       | 3.4
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | ~
| License       | MIT
| Doc PR        | symfony/symfony-docs#6393

ref symfony/symfony-docs#6144, symfony/symfony-docs#6297, #14050

Commits
-------

b9162e8 [Form] Fixed some phpdocs

src/Symfony/Component/Form/ChoiceList/ArrayChoiceList.php

@@ -15,9 +15,10 @@
  * A list of choices with arbitrary data types.
  *
  * The user of this class is responsible for assigning string values to the
- * choices. Both the choices and their values are passed to the constructor.
- * Each choice must have a corresponding value (with the same array key) in
- * the value array.
+ * choices annd for their uniqueness.
+ * Both the choices and their values are passed to the constructor.
+ * Each choice must have a corresponding value (with the same key) in
+ * the values array.
  *
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
@@ -43,12 +44,6 @@ class ArrayChoiceList implements ChoiceListInterface
      * @var int[]|string[]
      */
     protected $originalKeys;
-
-    /**
-     * The callback for creating the value for a choice.
-     *
-     * @var callable
-     */
     protected $valueCallback;
 
     /**
@@ -212,6 +207,8 @@ protected function flatten(array $choices, $value, &$choicesByValues, &$keysByVa
     /**
      * Checks whether the given choices can be cast to strings without
      * generating duplicates.
+     * This method is responsible for preventing conflict between scalar values
+     * and the empty value.
      *
      * @param array      $choices The choices
      * @param array|null $cache   The cache for previously checked entries. Internal
@@ -232,6 +229,7 @@ private function castableToString(array $choices, array &$cache = [])
                 return false;
             }
 
+            // prevent having false casted to the empty string by isset()
             $choice = false === $choice ? '0' : (string) $choice;
 
             if (isset($cache[$choice])) {

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

@@ -35,7 +35,25 @@ public function getChoices();
     /**
      * Returns the values for the choices.
      *
-     * The values are strings that do not contain duplicates.
+     * The values are strings that do not contain duplicates:
+     *
+     *     $form->add('field', 'choice', [
+     *         'choices' => [
+     *             'Decided' => ['Yes' => true, 'No' => false],
+     *             'Undecided' => ['Maybe' => null],
+     *         ],
+     *     ]);
+     *
+     * In this example, the result of this method is:
+     *
+     *     [
+     *         'Yes' => '0',
+     *         'No' => '1',
+     *         'Maybe' => '2',
+     *     ]
+     *
+     * Null and false MUST NOT conflict when being casted to string.
+     * For this some default incremented values SHOULD be computed.
      *
      * @return string[] The choice values
      */
@@ -62,6 +80,12 @@ public function getValues();
      *         'Undecided' => ['Maybe' => '2'],
      *     ]
      *
+     * Nested arrays do not make sense in a view format unless
+     * they are used as a convenient way of grouping.
+     * If the implementation does not intend to support grouped choices,
+     * this method SHOULD be equivalent to {@link getValues()}.
+     * The $groupBy callback parameter SHOULD be used instead.
+     *
      * @return string[] The choice values
      */
     public function getStructuredValues();

src/Symfony/Component/Form/ChoiceList/Factory/ChoiceListFactoryInterface.php

@@ -28,8 +28,8 @@ interface ChoiceListFactoryInterface
      * The choices should be passed in the values of the choices array.
      *
      * Optionally, a callable can be passed for generating the choice values.
-     * The callable receives the choice as first and the array key as the second
-     * argument.
+     * The callable receives the choice as only argument.
+     * Null may be passed when the choice list contains the empty value.
      *
      * @param iterable      $choices The choices
      * @param callable|null $value   The callable generating the choice
@@ -43,8 +43,8 @@ public function createListFromChoices($choices, $value = null);
      * Creates a choice list that is loaded with the given loader.
      *
      * Optionally, a callable can be passed for generating the choice values.
-     * The callable receives the choice as first and the array key as the second
-     * argument.
+     * The callable receives the choice as only argument.
+     * Null may be passed when the choice list contains the empty value.
      *
      * @param ChoiceLoaderInterface $loader The choice loader
      * @param callable|null         $value  The callable generating the choice

src/Symfony/Component/Form/ChoiceList/Loader/ChoiceLoaderInterface.php

@@ -28,8 +28,8 @@ interface ChoiceLoaderInterface
      * Loads a list of choices.
      *
      * Optionally, a callable can be passed for generating the choice values.
-     * The callable receives the choice as first and the array key as the second
-     * argument.
+     * The callable receives the choice as only argument.
+     * Null may be passed when the choice list contains the empty value.
      *
      * @param callable|null $value The callable which generates the values
      *                             from choices
@@ -45,8 +45,8 @@ public function loadChoiceList($value = null);
      * corresponding values in the given array.
      *
      * Optionally, a callable can be passed for generating the choice values.
-     * The callable receives the choice as first and the array key as the second
-     * argument.
+     * The callable receives the choice as only argument.
+     * Null may be passed when the choice list contains the empty value.
      *
      * @param string[]      $values An array of choice values. Non-existing
      *                              values in this array are ignored
@@ -63,8 +63,8 @@ public function loadChoicesForValues(array $values, $value = null);
      * corresponding choices in the given array.
      *
      * Optionally, a callable can be passed for generating the choice values.
-     * The callable receives the choice as first and the array key as the second
-     * argument.
+     * The callable receives the choice as only argument.
+     * Null may be passed when the choice list contains the empty value.
      *
      * @param array         $choices An array of choices. Non-existing choices in
      *                               this array are ignored