diff --git a/core/includes/form.inc b/core/includes/form.inc
index 2db36dd..5a0afef 100644
--- a/core/includes/form.inc
+++ b/core/includes/form.inc
@@ -861,23 +861,33 @@ function template_preprocess_select(&$variables) {
 }
 
 /**
- * Converts a select form element's options array into HTML.
+ * Converts an array of options into HTML, for use in select list form elements.
  *
- * This function support optgroups (when the elements of the #options array
- * are themselves arrays). The function calls itself recursively to obtain
- * the values for a optgroup.
+ * This function calls itself recursively to obtain the values for a optgroup.
  *
- * @param $element
- *   An associative array containing the properties of the element.
- * @param $choices
- *   Mixed: Either an associative array of items to list as choices, or an
- *   object with an 'option' member that is an associative array. This
- *   parameter is only used internally and should not be passed.
+ * @param array $element
+ *   An associative array containing the following key-value pairs:
+ *   - '#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)
+ *     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.
  *
- * @return
- *   An HTML string of options for the select form element. HTML will contain
- *   optgroup tags if it's $choices parameter contains nested arrays. An empty
- *   HTML string if $choices is not array or is empty array.
+ * @return string
+ *   An HTML string of options and optgroups for use in a select form element.
  */
 function form_select_options($element, $choices = NULL) {
   if (!isset($choices)) {