Issue #2486979 by metzlerd, ashutoshsngh, deepakaryan1988: Document Select/list elements

core/lib/Drupal/Core/Render/Element/Checkbox.php

@@ -13,6 +13,17 @@ use Drupal\Core\Render\Element;
 /**
  * Provides a form element for a single checkbox.
  *
+ * Properties:
+ * - #return_value: The value to return when the checkbox is checked.
+ *
+ * Usage example:
+ * @code
+ * $form['copy'] = array(
+ *   '#type' => 'checkbox',
+ *   '#title' => t('Send me a copy'),
+ * );
+ * @endcode
+ *
  * @see \Drupal\Core\Render\Element\Checkboxes
  *
  * @FormElement("checkbox")

core/lib/Drupal/Core/Render/Element/Checkboxes.php

@@ -12,9 +12,21 @@ use Drupal\Core\Form\FormStateInterface;
 /**
  * Provides a form element for a set of checkboxes.
  *
- * #options is an associative array, where the key is the #return_value of the
- * checkbox and the value is displayed. The #options array cannot have a 0 key,
- * as it would not be possible to discern checked and unchecked states.
+ * Properties:
+ * - #options: An associative array whose keys are the values returned for each
+ *   checkbox, and whose values are the labels next to each checkbox. The
+ *   #options array cannot have a 0 key, as it would not be possible to discern
+ *   checked and unchecked states.
+ *
+ * Usage example:
+ * @code
+ * $form['high_school']['tests_taken'] = array(
+ *   '#type' => 'checkboxes',
+ *   '#options' => array('SAT' => t('SAT'), 'ACT' => t('ACT'))),
+ *   '#title' => t('What standardized tests did you take?'),
+ *   ...
+ * );
+ * @endcode
  *
  * @see \Drupal\Core\Render\Element\Radios
  * @see \Drupal\Core\Render\Element\Checkbox

core/lib/Drupal/Core/Render/Element/LanguageSelect.php

@@ -12,6 +12,8 @@ use Drupal\Core\Language\LanguageInterface;
 /**
  * Provides a form element for selecting a language.
  *
+ * @see \Drupal\Core\Render\Element\Select
+ *
  * @FormElement("language_select")
  */
 class LanguageSelect extends FormElement {

core/lib/Drupal/Core/Render/Element/Radio.php

@@ -12,7 +12,11 @@ use Drupal\Core\Render\Element;
 /**
  * Provides a form element for a single radio button.
  *
+ * This is an internal element that is primarily used to render the radios form
+ * element. Refer to \Drupal\Core\Render\Element\Radios for more documentation.
+ *
  * @see \Drupal\Core\Render\Element\Radios
+ * @see \Drupal\Core\Render\Element\Checkbox
  *
  * @FormElement("radio")
  */

core/lib/Drupal/Core/Render/Element/Radios.php

@@ -13,8 +13,23 @@ use Drupal\Component\Utility\Html as HtmlUtility;
 /**
  * Provides a form element for a set of radio buttons.
  *
+ * Properties:
+ * - #options: An associative array, where the keys are the returned values for
+ *   each radio button, and the values are the labels next to each radio button.
+ *
+ * Usage example:
+ * @code
+ * $form['settings']['active'] = array(
+ *   '#type' => 'radios',
+ *   '#title' => t('Poll status'),
+ *   '#default_value' => 1
+ *   '#options' => array(0 => t('Closed'), 1 => t('Active'),
+ * );
+ * @endcode
+ *
  * @see \Drupal\Core\Render\Element\Checkboxes
  * @see \Drupal\Core\Render\Element\Radio
+ * @see \Drupal\Core\Render\Element\Select
  *
  * @FormElement("radios")
  */

core/lib/Drupal/Core/Render/Element/Select.php

@@ -13,8 +13,12 @@ use Drupal\Core\Render\Element;
 /**
  * Provides a form element for a drop-down menu or scrolling selection box.
  *
- * See #empty_option and #empty_value for an explanation of various settings for
- * a select element, including behavior if #required is TRUE or FALSE.
+ * Properties:
+ * - #options: An associative array, where the keys are the retured values for
+ *   each option, and the values are the options to be shown in the drop-down
+ *   list.
+ * - #empty_option: The label that will be displayed to denote no selection.
+ * - #empty_value: The value of the option that is used to denote no selection.
  *
  * @FormElement("select")
  */

core/lib/Drupal/Core/Render/Element/Tableselect.php

@@ -14,9 +14,14 @@ use Drupal\Component\Utility\Html as HtmlUtility;
 /**
  * Provides a form element for a table with radios or checkboxes in left column.
  *
- * Build the table headings and columns with the #headers property, and the rows
- * with the #options property. See https://www.drupal.org/node/94510 for a full
- * explanation.
+ * Properties:
+ * - #headers: Table headers used in the table.
+ * - #options: An associative array where each key is the value returned when
+ *   a user selects the radio button or checkbox, and each value is the row of
+ *   table data.
+ *
+ * Usage example:
+ * See https://www.drupal.org/node/945102 for an example and full explanation.
  *
  * @see \Drupal\Core\Render\Element\Table
  *

core/lib/Drupal/Core/Render/Element/Weight.php

@@ -12,8 +12,22 @@ use Drupal\Core\Form\FormStateInterface;
 /**
  * Provides a form element for input of a weight.
  *
- * Weights are integers used to indicate ordering, with larger numbers later
- * in the order.
+ * Weights are integers used to indicate ordering, with larger numbers later in
+ * the order.
+ *
+ * Properties:
+ * - #delta: The range of possible weight values used. A delta of 10 would
+ *   indicate possible weight values between -10 and 10.
+ *
+ * Usage example:
+ * @code
+ * $form['weight'] = array(
+ *   '#type' => 'weight',
+ *   '#title' => t('Weight'),
+ *   '#default_value' => $edit['weight'],
+ *   '#delta' => 10,
+ * );
+ * @endcode
  *
  * @FormElement("weight")
  */