[Form] Improved PHPDocs of choice lists

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

@@ -17,7 +17,16 @@
 use Symfony\Component\Form\Extension\Core\View\ChoiceView;
 
 /**
- * Base class for choice list implementations.
+ * A choice list for choices of arbitrary data types.
+ *
+ * Choices and labels are passed in two arrays. The indices of the choices
+ * and the labels should match.
+ *
+ * <code>
+ * $choices = array(true, false);
+ * $labels = array('Agree', 'Disagree');
+ * $choiceList = new ChoiceList($choices, $labels);
+ * </code>
  *
  * @author Bernhard Schussek <bschussek@gmail.<com>
  */

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

@@ -17,11 +17,17 @@
 use Symfony\Component\Form\Exception\InvalidPropertyException;
 
 /**
- * A choice list that can store object choices.
+ * A choice list for object choices.
  *
  * Supports generation of choice labels, choice groups, choice values and
- * choice indices by introspecting the properties of the object (or
- * associated objects).
+ * choice indices by calling getters of the object (or associated objects).
+ *
+ * <code>
+ * $choices = array($user1, $user2);
+ *
+ * // call getName() to determine the choice labels
+ * $choiceList = new ObjectChoiceList($choices, 'name');
+ * </code>
  *
  * @author Bernhard Schussek <bschussek@gmail.com>
  */

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

@@ -15,10 +15,39 @@
 use Symfony\Component\Form\Exception\UnexpectedTypeException;
 
 /**
- * A choice list that can store any choices that are allowed as PHP array keys.
+ * A choice list for choices of type string or integer.
  *
- * The value strategy of simple choice lists is fixed to ChoiceList::COPY_CHOICE,
- * since array keys are always valid choice values.
+ * Choices and their associated labels can be passed in a single array. Since
+ * choices are passed as array keys, only strings or integer choices are
+ * allowed.
+ *
+ * <code>
+ * $choiceList = new SimpleChoiceList(array(
+ *     'creditcard' => 'Credit card payment',
+ *     'cash' => 'Cash payment',
+ * ));
+ * </code>
+ *
+ * The default value generation strategy is `ChoiceList::COPY_CHOICE`, because
+ * choice values must be scalar, and the choices passed to this choice list
+ * are guaranteed to be scalar.
+ *
+ * The default index generation strategy is `ChoiceList::GENERATE`, so that
+ * your choices can also contain values that are illegal as indices. If your
+ * choices are guaranteed to start with a letter, digit or underscore and only
+ * contain letters, digits, underscores, hyphens and colons, you can set the
+ * strategy to `ChoiceList::COPY_CHOICE` instead.
+ *
+ * <code>
+ * $choices = array(
+ *     'creditcard' => 'Credit card payment',
+ *     'cash' => 'Cash payment',
+ * );
+ *
+ * // value generation: COPY_CHOICE (the default)
+ * // index generation: COPY_CHOICE (custom)
+ * $choiceList = new SimpleChoiceList($choices, array(), ChoiceList::COPY_CHOICE, ChoiceList::COPY_CHOICE);
+ * </code>
  *
  * @author Bernhard Schussek <bschussek@gmail.com>
  */