Issue #2283703 by pjonckiere, jhodgdon: Document how optgroups work on 'select' form elements

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

@@ -14,12 +14,30 @@ use Drupal\Core\Render\Element;
  * Provides a form element for a drop-down menu or scrolling selection box.
  *
  * Properties:
- * - #options: An associative array, where the keys are the retured values for
+ * - #options: An associative array, where the keys are the values for each
- *   each option, and the values are the options to be shown in the drop-down
+ *   option, and the values are the option labels to be shown in the drop-down
- *   list.
+ *   list. If a value is an array, it will be rendered similarly, but as an
+ *   optgroup. The key of the sub-array will be used as the label for the
+ *   optgroup. Nesting optgroups is not allowed.
  * - #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.
  *
+ * Usage example:
+ * @code
+ * $form['example_select'] = [
+ *   '#type' => 'select',
+ *   '#title' => t('Select element'),
+ *   '#options' => [
+ *     '1' => t('One'),
+ *     '2' => [
+ *       '2.1' => t('Two point one'),
+ *       '2.2' => t('Two point two'),
+ *     ],
+ *     '3' => t('Three'),
+ *   ],
+ * ];
+ * @endcode
+ *
  * @FormElement("select")
  */
 class Select extends FormElement {