Index: modules/system/system.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.api.php,v
retrieving revision 1.142
diff -u -r1.142 system.api.php
--- modules/system/system.api.php	11 Mar 2010 21:23:06 -0000	1.142
+++ modules/system/system.api.php	16 Mar 2010 15:53:32 -0000
@@ -447,6 +447,7 @@
  *
  * @see hook_element_info_alter()
  * @see system_element_info()
+ * @see form_type_ELEMENT_value()
  */
 function hook_element_info() {
   $types['filter_format'] = array(
@@ -3221,3 +3222,42 @@
 /**
  * @} End of "addtogroup hooks".
  */
+
+/**
+ * Defines a value callback for a form element.
+ *
+ * If your module uses hook_elements() to define a form element, you can
+ * also define a callback function that will give the element a value during
+ * form submission. This function is not called if a #value element is supplied
+ * by the form constructor, or if a #value_callback element is supplied to
+ * override this default value callback.
+ *
+ * @param $element
+ *   Element array.
+ * @param $input
+ *   The posted value if there was one. FALSE if there is no input to process.
+ * @param $form_state
+ *   A keyed array containing the current state of the form.
+ *
+ * @return
+ *   The value for your element. You can return nothing to use the default
+ *   value.
+ *
+ * @see hook_element_info().
+ */
+function form_type_ELEMENT_value($element, $input, $form_state) {
+  // This example is from form_type_checkbox_value(), which is the default
+  // value callback for a checkbox form element.
+  if ($input !== FALSE) {
+    if (empty($element['#disabled'])) {
+      // Successful (checked) checkboxes are present with a value
+      // (possibly '0'). Return a numeric zero 0.
+      return isset($input) ? $element['#return_value'] : 0;
+    }
+    else {
+      // Disabled form controls are not submitted by the browser. Ignore any
+      // submitted value and always return default.
+      return $element['#default_value'];
+    }
+  }
+}
Index: includes/form.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/form.inc,v
retrieving revision 1.442
diff -u -r1.442 form.inc
--- includes/form.inc	13 Mar 2010 22:33:05 -0000	1.442
+++ includes/form.inc	16 Mar 2010 15:53:32 -0000
@@ -7,8 +7,8 @@
  * Functions that build an abstract representation of a HTML form.
  *
  * All modules should declare their form builder functions to be in this
- * group and each builder function should reference its validate and submit
- * functions using \@see. Conversely, validate and submit functions should
+ * group and each builder function should reference its validation and submit
+ * handlers using \@see. Conversely, validate and submit handlers should
  * reference the form builder function using \@see. For examples, of this see
  * system_modules_uninstall() or user_pass(), the latter of which has the
  * following in its doxygen documentation:
@@ -61,6 +61,7 @@
  *   drupal_get_form(), including the unique form constructor function. For
  *   example, the node_edit form requires that a node object is passed in here
  *   when it is called.
+ *
  * @return
  *   The form array.
  *
@@ -78,10 +79,10 @@
 }
 
 /**
- * Build and process a form based on a form id.
+ * Builds and processes a form based on a form id.
  *
  * The form may also be retrieved from the cache if the form was built in a
- * previous page-load. The form is then passed on for processing, validation
+ * previous page-load. The form is then passed on for processing, validation,
  * and submission if there is proper input.
  *
  * @param $form_id
@@ -155,7 +156,8 @@
  *   form submission may be found in drupal_redirect_form().
  *
  * @return
- *   The rendered form or NULL, depending upon the $form_state flags that were set.
+ *   The rendered form or NULL, depending upon the $form_state flags that were
+ *   set.
  *
  * @see drupal_redirect_form()
  */
@@ -267,7 +269,7 @@
 }
 
 /**
- * Retrieve default values for the $form_state array.
+ * Retrieves default values for the $form_state array.
  */
 function form_state_defaults() {
   return array(
@@ -307,6 +309,7 @@
  *   If the AHAH callback calling this function only alters part of the form,
  *   then pass in the existing form_build_id so we can re-cache with the same
  *   csid.
+ *
  * @return
  *   The newly built form.
  */
@@ -344,7 +347,7 @@
 }
 
 /**
- * Fetch a form from cache.
+ * Fetches a form from the cache.
  */
 function form_get_cache($form_build_id, &$form_state) {
   if ($cached = cache_get('form_' . $form_build_id, 'cache_form')) {
@@ -368,7 +371,7 @@
 }
 
 /**
- * Store a form in the cache.
+ * Stores a form in the cache.
  */
 function form_set_cache($form_build_id, $form, $form_state) {
   // 6 hours cache life time for forms should be plenty.
@@ -666,9 +669,10 @@
 }
 
 /**
- * Prepares a structured form array by adding required elements,
- * executing any hook_form_alter functions, and optionally inserting
- * a validation token to prevent tampering.
+ * Prepares a structured form array.
+ *
+ * Adds required elements, executes any hook_form_alter functions, and
+ * optionally inserts a validation token to prevent tampering.
  *
  * @param $form_id
  *   A unique string identifying the form for validation, submission,
@@ -755,8 +759,10 @@
 
 
 /**
- * Validates user-submitted form data from the $form_state using
- * the validate functions defined in a structured form array.
+ * Validates user-submitted form data.
+ *
+ * Validates the submitted form data using the validation handlers defined in
+ * the structured form array.
  *
  * @param $form_id
  *   A unique string identifying the form for validation, submission,
@@ -772,10 +778,12 @@
  * @param $form_state
  *   A keyed array containing the current state of the form. The current
  *   user-submitted data is stored in $form_state['values'], though
- *   form validation functions are passed an explicit copy of the
+ *   form validation handlers are passed an explicit copy of the
  *   values for the sake of simplicity. Validation handlers can also
  *   $form_state to pass information on to submit handlers. For example:
- *     $form_state['data_for_submission'] = $data;
+ *   @code
+ *   $form_state['data_for_submission'] = $data;
+ *   @endcode
  *   This technique is useful when validation requires file parsing,
  *   web service requests, or other expensive requests that should
  *   not be repeated in the submission step.
@@ -868,16 +876,18 @@
 }
 
 /**
- * Performs validation on form elements. First ensures required fields are
- * completed, #maxlength is not exceeded, and selected options were in the
- * list of options given to the user. Then calls user-defined validators.
+ * Performs validation on form elements.
+ *
+ * First ensures required fields are completed, #maxlength is not exceeded, and
+ * selected options were in the list of options given to the user. Then calls
+ * user-defined validation handlers.
  *
  * @param $elements
  *   An associative array containing the structure of the form.
  * @param $form_state
  *   A keyed array containing the current state of the form. The current
  *   user-submitted data is stored in $form_state['values'], though
- *   form validation functions are passed an explicit copy of the
+ *   form validation handlers are passed an explicit copy of the
  *   values for the sake of simplicity. Validation handlers can also
  *   $form_state to pass information on to submit handlers. For example:
  *     $form_state['data_for_submission'] = $data;
@@ -947,8 +957,8 @@
     else {
       // As an extra security measure, explicitly turn off error suppression.
       // Since this is also done at the end of this function, doing it here is
-      // only to handle the rare edge case where a validate handler invokes form
-      // processing of another form.
+      // only to handle the rare edge case where a validation handler invokes
+      // form processing of another form.
       drupal_static_reset('form_set_error:limit_validation_errors');
     }
     // Make sure a value is passed when the field is required.
@@ -961,12 +971,12 @@
       form_error($elements, $t('!name field is required.', array('!name' => $elements['#title'])));
     }
 
-    // Call user-defined form level validators.
+    // Call user-defined form-level validation handlers.
     if (isset($form_id)) {
       form_execute_handlers('validate', $elements, $form_state);
     }
-    // Call any element-specific validators. These must act on the element
-    // #value data.
+    // Call any element-specific validation handlers. These must act on the
+    // element #value data.
     elseif (isset($elements['#element_validate'])) {
       foreach ($elements['#element_validate'] as $function) {
         $function($elements, $form_state, $form_state['complete form']);
@@ -982,9 +992,10 @@
 }
 
 /**
- * A helper function used to execute custom validation and submission
- * handlers for a given form. Button-specific handlers are checked
- * first. If none exist, the function falls back to form-level handlers.
+ * Helper function: Executes validation and submission handlers.
+ *
+ * Button-specific handlers are checked first. If none exist, the function
+ * falls back to form-level handlers.
  *
  * @param $type
  *   The type of handler to execute. 'validate' or 'submit' are the
@@ -1136,14 +1147,14 @@
 }
 
 /**
- * Clear all errors against all form elements made by form_set_error().
+ * Clears all errors against all form elements made by form_set_error().
  */
 function form_clear_error() {
   drupal_static_reset('form_set_error');
 }
 
 /**
- * Return an associative array of all errors.
+ * Returns an associative array of all errors.
  */
 function form_get_errors() {
   $form = form_set_error();
@@ -1153,7 +1164,7 @@
 }
 
 /**
- * Return the error message filed against the form with the specified name.
+ * Returns the error message filed against a form element.
  */
 function form_get_error($element) {
   $form = form_set_error();
@@ -1168,16 +1179,18 @@
 }
 
 /**
- * Flag an element as having an error.
+ * Flags an element as having an error.
  */
 function form_error(&$element, $message = '') {
   form_set_error(implode('][', $element['#parents']), $message);
 }
 
 /**
- * Walk through the structured form array, adding any required
+ * Builds a form's elements.
+ *
+ * Walks through the structured form array, adding any required
  * properties to each element and mapping the incoming input
- * data to the proper elements. Also, execute any #process handlers
+ * data to the proper elements. Also, executes any #process handlers
  * attached to a specific element.
  *
  * @param $form_id
@@ -1319,8 +1332,9 @@
 }
 
 /**
- * Populate the #value and #name properties of input elements so they
- * can be processed and rendered.
+ * Populates the #value and #name properties of input elements.
+ *
+ * This allows the form elements to be processed and rendered.
  */
 function _form_builder_handle_input_element($form_id, &$element, &$form_state) {
   if (!isset($element['#name'])) {
@@ -1447,8 +1461,7 @@
 }
 
 /**
- * Helper function to handle the sometimes-convoluted logic of button
- * click detection.
+ * Helper function: handles the logic of button click detection.
  *
  * In Internet Explorer, if ONLY one submit button is present, AND the
  * enter key is used to submit the form, no form value is sent for it
@@ -1476,6 +1489,8 @@
 }
 
 /**
+ * Detects buttons for Internet Explorer form submission.
+ *
  * In IE, if only one submit button is present, AND the enter key is
  * used to submit the form, no form value is sent for it and our normal
  * button detection code will never detect a match. We call this
@@ -1562,18 +1577,21 @@
 }
 
 /**
- * Helper function to determine the value for an image button form element.
+ * Default value callback for the image button form element.
  *
- * @param $form
+ * @param $element
  *   The form element whose value is being populated.
  * @param $input
  *   The incoming input to populate the form element. If this is FALSE,
  *   the element's default value should be returned.
  * @param $form_state
  *   A keyed array containing the current state of the form.
+ *
  * @return
  *   The data that will appear in the $form_state['values'] collection
- *   for this element. Return nothing to use the default.
+ *   for this element, or nothing to use the default.
+ *
+ * @see form_type_ELEMENT_value
  */
 function form_type_image_button_value($form, $input, $form_state) {
   if ($input !== FALSE) {
@@ -1609,16 +1627,19 @@
 }
 
 /**
- * Helper function to determine the value for a checkbox form element.
+ * Default value callback for the checkbox form element.
  *
- * @param $form
+ * @param $element
  *   The form element whose value is being populated.
-*  @param $input
+ * @param $input
  *   The incoming input to populate the form element. If this is FALSE,
  *   the element's default value should be returned.
+ *
  * @return
  *   The data that will appear in the $element_state['values'] collection
- *   for this element. Return nothing to use the default.
+ *   for this element, or nothing to use the default.
+ *
+ * @see form_type_ELEMENT_value
  */
 function form_type_checkbox_value($element, $input = FALSE) {
   if ($input !== FALSE) {
@@ -1638,16 +1659,19 @@
 }
 
 /**
- * Helper function to determine the value for a checkboxes form element.
+ * Default value callback for the checkboxes form element.
  *
  * @param $element
  *   The form element whose value is being populated.
  * @param $input
  *   The incoming input to populate the form element. If this is FALSE,
  *   the element's default value should be returned.
+ *
  * @return
  *   The data that will appear in the $element_state['values'] collection
- *   for this element. Return nothing to use the default.
+ *   for this element, or nothing to use the default.
+ *
+ * @see form_type_ELEMENT_value
  */
 function form_type_checkboxes_value($element, $input = FALSE) {
   if ($input === FALSE) {
@@ -1667,17 +1691,19 @@
 }
 
 /**
- * Helper function to determine the value for a password_confirm form
- * element.
+ * Default value callback for the password_confirm form element.
  *
  * @param $element
  *   The form element whose value is being populated.
  * @param $input
  *   The incoming input to populate the form element. If this is FALSE,
  *   the element's default value should be returned.
+ *
  * @return
  *   The data that will appear in the $element_state['values'] collection
- *   for this element. Return nothing to use the default.
+ *   for this element, or nothing to use the default.
+ *
+ * @see form_type_ELEMENT_value
  */
 function form_type_password_confirm_value($element, $input = FALSE) {
   if ($input === FALSE) {
@@ -1687,16 +1713,19 @@
 }
 
 /**
- * Helper function to determine the value for a select form element.
+ * Default value callback for the select form element.
  *
  * @param $element
  *   The form element whose value is being populated.
  * @param $input
  *   The incoming input to populate the form element. If this is FALSE,
  *   the element's default value should be returned.
+ *
  * @return
  *   The data that will appear in the $element_state['values'] collection
- *   for this element. Return nothing to use the default.
+ *   for this element, or nothing to use the default.
+ *
+ * @see form_type_ELEMENT_value
  */
 function form_type_select_value($element, $input = FALSE) {
   if ($input !== FALSE) {
@@ -1718,16 +1747,19 @@
 }
 
 /**
- * Helper function to determine the value for a textfield form element.
+ * Default value callback for the textfield form element.
  *
  * @param $element
  *   The form element whose value is being populated.
  * @param $input
  *   The incoming input to populate the form element. If this is FALSE,
  *   the element's default value should be returned.
+ *
  * @return
  *   The data that will appear in the $element_state['values'] collection
- *   for this element. Return nothing to use the default.
+ *   for this element, or nothing to use the default.
+ *
+ * @see form_type_ELEMENT_value
  */
 function form_type_textfield_value($element, $input = FALSE) {
   if ($input !== FALSE && $input !== NULL) {
@@ -1738,16 +1770,19 @@
 }
 
 /**
- * Helper function to determine the value for form's token value.
+ * Default value callback for the token form element.
  *
  * @param $element
  *   The form element whose value is being populated.
  * @param $input
  *   The incoming input to populate the form element. If this is FALSE,
  *   the element's default value should be returned.
+ *
  * @return
  *   The data that will appear in the $element_state['values'] collection
- *   for this element. Return nothing to use the default.
+ *   for this element, or nothing to use the default.
+ *
+ * @see form_type_ELEMENT_value
  */
 function form_type_token_value($element, $input = FALSE) {
   if ($input !== FALSE) {
@@ -1756,16 +1791,16 @@
 }
 
 /**
- * Change submitted form values during form validation.
+ * Changes submitted form values during form validation.
  *
  * Use this function to change the submitted value of a form element in a form
- * validation function, so that the changed value persists in $form_state
+ * validation handler, so that the changed value persists in $form_state
  * through to the submission handlers.
  *
- * Note that form validation functions are specified in the '#validate'
+ * Note that form validation handlers are specified in the '#validate'
  * component of the form array (the value of $form['#validate'] is an array of
  * validation function names). If the form does not originate in your module,
- * you can implement hook_form_FORM_ID_alter() to add a validation function
+ * you can implement hook_form_FORM_ID_alter() to add a validation handler
  * to $form['#validate'].
  *
  * @param $element
@@ -1787,7 +1822,10 @@
 }
 
 /**
- * Helper function for form_set_value() and _form_builder_handle_input_element().
+ * Helper function: sets up form values.
+ *
+ * This is a helper function for form_set_value() and
+ * _form_builder_handle_input_element().
  *
  * We iterate over $parents and create nested arrays for them in $form_values if
  * needed. Then we insert the value into the last parent key.
@@ -1805,12 +1843,18 @@
   }
 }
 
+/**
+ * Flattens an object or nested array into a one-dimensional array.
+ */
 function form_options_flatten($array) {
   // Always reset static var when first entering the recursion.
   drupal_static_reset('_form_options_flatten');
   return _form_options_flatten($array);
 }
 
+/**
+ * Performs recursive flattening for form_options_flatten().
+ */
 function _form_options_flatten($array) {
   $return = &drupal_static(__FUNCTION__);
 
@@ -1830,22 +1874,22 @@
 }
 
 /**
- * Theme select form element.
+ * Themes a select form element.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
  *     Properties used: #title, #value, #options, #description, #extra,
  *     #multiple, #required, #name, #attributes, #size.
+ *   It is possible to group options together. To do this, change the format of
+ *   $variables['element']['#options'] to an associative array in which the
+ *   keys are group labels, and the values are associative arrays in the
+ *   normal options format.
  *
  * @return
  *   A themed HTML string representing the form element.
  *
  * @ingroup themeable
- *
- * It is possible to group options together; to do this, change the format of
- * $options to an associative array in which the keys are group labels, and the
- * values are associative arrays in the normal $options format.
  */
 function theme_select($variables) {
   $element = $variables['element'];
@@ -1856,7 +1900,7 @@
 }
 
 /**
- * Convert a select form element's options array into an HTML.
+ * Converts a select form element's options array into HTML.
  *
  * @param $element
  *   An associative array containing the properties of the element.
@@ -1864,6 +1908,7 @@
  *   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.
+ *
  * @return
  *   An HTML string of options for the select form element.
  */
@@ -1900,6 +1945,8 @@
 }
 
 /**
+ * Finds matching indexes in a select element.
+ *
  * Traverses a select element's #option array looking for any values
  * that hold the given key. Returns an array of indexes that match.
  *
@@ -1927,6 +1974,7 @@
  *   The select element to search.
  * @param $key
  *   The key to look for.
+ *
  * @return
  *   An array of indexes that match the given $key. Array will be
  *   empty if no elements were found. FALSE if optgroups were found.
@@ -1950,7 +1998,7 @@
 }
 
 /**
- * Theme a fieldset form element.
+ * Themes a fieldset form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -1985,7 +2033,7 @@
 }
 
 /**
- * Theme a radio button form element.
+ * Themes a radio button form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2012,7 +2060,7 @@
 }
 
 /**
- * Theme a set of radio button form elements.
+ * Themes a set of radio button form elements.
  *
  * @param $variables
  *   An associative array containing:
@@ -2037,7 +2085,7 @@
 }
 
 /**
- * Expand a password_confirm field into two text boxes.
+ * Expands a password_confirm field into two text boxes.
  */
 function form_process_password_confirm($element) {
   $element['pass1'] =  array(
@@ -2065,7 +2113,7 @@
 }
 
 /**
- * Validate password_confirm element.
+ * Validates a password_confirm element.
  */
 function password_confirm_validate($element, &$element_state) {
   $pass1 = trim($element['pass1']['#value']);
@@ -2090,7 +2138,7 @@
 }
 
 /**
- * Theme a date selection form element.
+ * Themes a date selection form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2109,7 +2157,7 @@
 }
 
 /**
- * Roll out a single date element.
+ * Rolls out a single date element.
  */
 function form_process_date($element) {
   // Default to current date
@@ -2165,7 +2213,7 @@
 }
 
 /**
- * Helper function for usage with drupal_map_assoc to display month names.
+ * Helper function: displays month names for drupal_map_assoc().
  */
 function map_month($month) {
   $months = &drupal_static(__FUNCTION__, array(
@@ -2186,7 +2234,9 @@
 }
 
 /**
- * If no default value is set for weight select boxes, use 0.
+ * Sets a default weight for weight select boxes.
+ *
+ * If no default value is set, use 0.
  */
 function weight_value(&$form) {
   if (isset($form['#default_value'])) {
@@ -2198,8 +2248,7 @@
 }
 
 /**
- * Roll out a single radios element to a list of radios,
- * using the options array as index.
+ * Converts a radios form element into a list of individual radios.
  */
 function form_process_radios($element) {
   if (count($element['#options']) > 0) {
@@ -2226,7 +2275,7 @@
 }
 
 /**
- * Theme a checkbox form element.
+ * Themes a checkbox form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2258,7 +2307,7 @@
 }
 
 /**
- * Theme a set of checkbox form elements.
+ * Themes a set of checkbox form elements.
  *
  * @param $variables
  *   An associative array containing:
@@ -2282,7 +2331,7 @@
 }
 
 /**
- * Add form_element theming to an element if title or description is set.
+ * Adds form_element theming to an element if title or description is set.
  *
  * This is used as a pre render function for checkboxes and radios.
  */
@@ -2303,6 +2352,9 @@
   return $element;
 }
 
+/**
+ * Processes checkboxes elements into individual checkbox elements.
+ */
 function form_process_checkboxes($element) {
   $value = is_array($element['#value']) ? $element['#value'] : array();
   $element['#tree'] = TRUE;
@@ -2336,6 +2388,7 @@
  *   container.
  * @param $form_state
  *   The $form_state array for the form this element belongs to.
+ *
  * @return
  *   The processed element.
  */
@@ -2354,6 +2407,7 @@
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
  *     Properties used: #id, #attributes, #children.
+ *
  * @return
  *   A themed HTML string representing the form element.
  *
@@ -2431,11 +2485,12 @@
 }
 
 /**
- * Create the correct amount of checkbox or radio elements to populate the table.
+ * Creates checkbox or radio elements to populate a tableselect table.
  *
  * @param $element
  *   An associative array containing the properties and children of the
  *   tableselect element.
+ *
  * @return
  *   The processed element.
  */
@@ -2501,8 +2556,7 @@
 }
 
 /**
- * Adds fieldsets to the specified group or adds group members to this
- * fieldset.
+ * Adds fieldsets to the specified group or group members to the fieldset.
  *
  * @param &$element
  *   An associative array containing the properties and children of the
@@ -2510,6 +2564,7 @@
  *   child elements are taken over into $form_state.
  * @param $form_state
  *   The $form_state array for the form this fieldset belongs to.
+ *
  * @return
  *   The processed element.
  */
@@ -2608,6 +2663,7 @@
  *   fieldset.
  * @param $form_state
  *   The $form_state array for the form this vertical tab widget belongs to.
+ *
  * @return
  *   The processed element.
  */
@@ -2642,8 +2698,8 @@
  *
  * @param $variables
  *   An associative array containing:
- *   - element: An associative array containing the properties and children of the
- *     fieldset. Properties used: #children.
+ *   - element: An associative array containing the properties and children of
+ *     the fieldset. Properties used: #children.
  *
  * @return
  *   A themed HTML string representing the form element.
@@ -2659,7 +2715,7 @@
 }
 
 /**
- * Theme a submit button form element.
+ * Themes a submit button form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2677,7 +2733,7 @@
 }
 
 /**
- * Theme a button form element.
+ * Themes a button form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2722,7 +2778,7 @@
 }
 
 /**
- * Theme a hidden form element.
+ * Themes a hidden form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2740,7 +2796,7 @@
 }
 
 /**
- * Theme a textfield form element.
+ * Themes a textfield form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2774,7 +2830,7 @@
 }
 
 /**
- * Theme a form.
+ * Themes a form.
  *
  * @param $variables
  *   An associative array containing:
@@ -2794,7 +2850,7 @@
 }
 
 /**
- * Theme a textarea form element.
+ * Themes a textarea form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2830,7 +2886,7 @@
 }
 
 /**
- * Theme a password form element.
+ * Themes a password form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2854,7 +2910,7 @@
 }
 
 /**
- * Expand weight elements into selects.
+ * Expands weight elements into selects.
  */
 function form_process_weight($element) {
   for ($n = (-1 * $element['#delta']); $n <= $element['#delta']; $n++) {
@@ -2868,7 +2924,7 @@
 }
 
 /**
- * Theme a file upload form element.
+ * Themes a file upload form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2891,7 +2947,7 @@
 }
 
 /**
- * Theme a form element.
+ * Themes a form element.
  *
  * Each form element is wrapped in a DIV with #type and #name classes. In
  * addition to the element itself, the div contains a label before or after
@@ -2987,11 +3043,12 @@
 }
 
 /**
- * Theme the marker for required form elements.
+ * Themes the marker for required form elements.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
+ *
  * @return
  *   A string representing the marker to identify required form elements.
  *
@@ -3008,11 +3065,12 @@
 }
 
 /**
- * Theme a form element label and required marker.
+ * Themes a form element label and required marker.
  *
  * Form element labels include the #title and a #required marker. The label is
  * associated with the element itself by the element #id. Labels may appear
- * before or after elements, depending on theme_form_element() and #title_display.
+ * before or after elements, depending on theme_form_element() and
+ * #title_display.
  *
  * This function will not be called for elements with no labels, depending on
  * #title_display. For elements that have an empty #title and are not required,
@@ -3026,6 +3084,7 @@
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
  *     Properties used: #required, #title, #id, #value, #description.
+ *
  * @return
  *   A string representing the form element label.
  *
@@ -3125,8 +3184,8 @@
  * @code
  * // Simple and artificial: load a node of a given type for a given user
  * function my_function_1($uid, $type, &$context) {
- *   // The $context array gathers batch context information about the execution (read),
- *   // as well as 'return values' for the current operation (write)
+ *   // The $context array gathers batch context information about the execution
+ *   // (read), as well as 'return values' for the current operation (write)
  *   // The following keys are provided :
  *   // 'results' (read / write): The array of results gathered so far by
  *   //   the batch processing, for the current operation to append its own.
@@ -3444,6 +3503,7 @@
  *
  * @param $batch_set
  *   The batch set.
+ *
  * @return
  *   The queue object.
  */