Document how optgroups work on 'select' form elements

Problem/Motivation

Form controls of type select will group options in HTML <optgroup> tags if the #options array contains a sub-array (the key for the sub-array will be used as the optgroup label). For example, in D7, the following code will output the control seen in the attached Screen Shot 2014-06-10 at 11.24.01.png:

/**
* Form constructor for the select control with option-groups example.
*
* @see user_login_form_validate()
* @see user_login_form_submit()
*
* @ingroup forms
*/
function form_example_select_optgroup($form, &$form_state) {
  $form['test_select'] = array(
    '#type' => 'select',
    '#title' => t('Selected'),
    '#options' => array(
      '1' => t('One'),
      t('Two') => array(
        '2.1' => t('Two point one'),
        '2.2' => t('Two point two'),
      ),
      '3' => t('Three'),
    ),
  );
}

... however, this behaviour is not documented in the Form API Reference for the select control nor the Form API Reference for the #options property.

Proposed resolution

Add documentation to the select control and the options property in the Form API Reference.

Remaining tasks

1. Write a patch for 8.x
2. Review and RTBC
3. Commit to 8.x
4. Write a patch for 7.x
5. Review and RTBC
6. Commit to 7.x

User interface changes

None.

API changes

None.