diff --git a/core/includes/form.inc b/core/includes/form.inc
index 5c2ad3e..84f4b14 100644
--- a/core/includes/form.inc
+++ b/core/includes/form.inc
@@ -851,28 +851,38 @@ function template_preprocess_select(&$variables) {
 /**
  * Converts an array of options into HTML, for use in select list form elements.
  *
- * This function calls itself recursively to obtain the values for a optgroup.
+ * This function calls itself recursively to obtain the values for each optgroup
+ * within the list of options and when the function encounters an object with
+ * an 'options' property inside $element['#options'].
  *
  * @param array $element
  *   An associative array containing the following key-value pairs:
- *   - '#multiple': Optional boolean indicating if the user may select more than
+ *   - #multiple: Optional Boolean indicating if the user may select more than
  *     one item.
- *   - '#options': An array of options to render as HTML.
- *     A string or integer key mapped to a translated string is interpreted as a
- *     single HTML option element. Note that the key will be visible in the
- *     HTML and could be modified by malicious users, so don't put sensitive
- *     information in it and sanitize it before use.
- *     A translated string mapped to an array indicates a group of options. The
- *     array should contain the options you wish to group. Groups are output as
- *     HTML optgroup elements.
- *   - '#value': Optional integer, string or array representing which option(s)
+ *   - #options: A associative array of options to render as HTML. Each array
+ *     value can be a string, array, or an object with an 'option' property:
+ *     - A string or integer key mapped to a translated string is interpreted as
+ *     a single HTML option element. Do not use placeholders to sanitize data:
+ *     doing so will lead to double-escaping. Note that the key will be visible
+ *     in the HTML and could be modified by malicious users, so don't put
+ *     sensitive information in it and sanitize it before use.
+ *     - A translated string key mapped to an array indicates a group of
+ *     options. The translated string is used as the label attribute for the
+ *     optgroup. Do not use placeholders to sanitize data: doing so will lead to
+ *     double-escaping. The array should contain the options you wish to group.
+ *     Groups are output as HTML optgroup elements.
+ *     - If the function encounters a string or integer key mapped to an object
+ *     with an 'option' property, the key is ignored, the contents of the
+ *     option property are interpreted as $element['#options'], and the
+ *     resulting HTML is added to the output.
+ *   - #value: Optional integer, string, or array representing which option(s)
  *     to pre-select when the list is first displayed. The integer or string
  *     must match the key of an option in the '#options' list. If '#multiple' is
  *     TRUE, this can be an array of integers or strings.
- * @param array|object|null $choices
- *   Either an associative array of options, an object with an 'option' member
- *   that is an associative array, or NULL. This parameter is only used
- *   internally and should not be passed.
+ * @param array|null $choices
+ *   (optional) Either an associative array of options in the same format as
+ *   $element['options'] above, or NULL. This parameter is only used internally
+ *   and is not intended to be passed in to the initial function call.
  *
  * @return string
  *   An HTML string of options and optgroups for use in a select form element.