Index: modules/system/system.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.api.php,v
retrieving revision 1.179
diff -u -r1.179 system.api.php
--- modules/system/system.api.php	10 Jul 2010 01:59:02 -0000	1.179
+++ modules/system/system.api.php	25 Jul 2010 18:55:22 -0000
@@ -500,6 +500,7 @@
  *
  * @see hook_element_info_alter()
  * @see system_element_info()
+ * @see form_type_ELEMENT_value()
  */
 function hook_element_info() {
   $types['filter_format'] = array(
@@ -3988,3 +3989,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.478
diff -u -r1.478 form.inc
--- includes/form.inc	17 Jul 2010 18:52:39 -0000	1.478
+++ includes/form.inc	25 Jul 2010 18:55:20 -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:
@@ -182,10 +182,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
@@ -262,7 +262,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()
  */
@@ -374,7 +375,7 @@
 }
 
 /**
- * Retrieve default values for the $form_state array.
+ * Retrieves default values for the $form_state array.
  */
 function form_state_defaults() {
   return array(
@@ -465,7 +466,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')) {
@@ -496,7 +497,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.
@@ -798,9 +799,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,
@@ -884,8 +886,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,
@@ -901,10 +905,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.
@@ -997,16 +1003,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;
@@ -1103,12 +1111,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']);
@@ -1124,9 +1132,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
@@ -1308,14 +1317,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();
@@ -1325,7 +1334,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();
@@ -1340,16 +1349,18 @@
 }
 
 /**
- * Flag an element as having an error.
+ * Flags a form 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 properties to
+ * 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 attached to a specific element.
+ * Also, executes any #process handlers attached to a specific element.
  *
  * This is one of the three primary functions that recursively iterates a form
  * array. This one does it for completing the form building process. The other
@@ -1618,8 +1629,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'])) {
@@ -1774,7 +1786,7 @@
 }
 
 /**
- * Helper function to handle the convoluted logic of button click detection.
+ * Helper function: handles the logic of button click detection.
  *
  * This detects button or non-button controls that trigger a form submission via
  * AJAX or some other scriptable environment. These environments can set the
@@ -1794,7 +1806,7 @@
 }
 
 /**
- * Helper function to handle the convoluted logic of button click detection.
+ * Helper function: handles the logic of button click detection.
  *
  * This detects button controls that trigger a form submission by being clicked
  * and having the click processed by the browser rather than being captured by
@@ -1889,18 +1901,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) {
@@ -1936,16 +1951,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) {
@@ -1958,16 +1976,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) {
@@ -1984,17 +2005,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) {
@@ -2004,16 +2027,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) {
@@ -2035,16 +2061,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) {
@@ -2055,16 +2084,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) {
@@ -2073,16 +2105,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
@@ -2104,7 +2136,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.
@@ -2142,7 +2177,7 @@
 }
 
 /**
- * Helper function for form_options_flatten().
+ * Performs recursive flattening for form_options_flatten().
  *
  * Iterates over arrays which may share common values and produces a flat
  * array that has removed duplicate keys. Also handles cases where objects
@@ -2198,6 +2233,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.
  */
@@ -2234,6 +2270,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.
  *
@@ -2261,6 +2299,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.
@@ -2364,7 +2403,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(
@@ -2392,7 +2431,7 @@
 }
 
 /**
- * Validate password_confirm element.
+ * Validates a password_confirm element.
  */
 function password_confirm_validate($element, &$element_state) {
   $pass1 = trim($element['pass1']['#value']);
@@ -2433,7 +2472,7 @@
 }
 
 /**
- * Roll out a single date element.
+ * Rolls out a single date element.
  */
 function form_process_date($element) {
   // Default to current date
@@ -2489,7 +2528,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(
@@ -2510,7 +2549,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'])) {
@@ -2522,8 +2563,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) {
@@ -2601,7 +2641,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.
  */
@@ -2621,6 +2661,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;
@@ -2670,6 +2713,7 @@
  *   container.
  * @param $form_state
  *   The $form_state array for the form this element belongs to.
+ *
  * @return
  *   The processed element.
  */
@@ -2764,11 +2808,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.
  */
@@ -2831,8 +2876,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
@@ -2840,6 +2884,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.
  */
@@ -2941,6 +2986,7 @@
  *   fieldset.
  * @param $form_state
  *   The $form_state array for the form this vertical tab widget belongs to.
+ *
  * @return
  *   The processed element.
  */
@@ -3168,7 +3214,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++) {
@@ -3435,8 +3481,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.
@@ -3754,6 +3800,7 @@
  *
  * @param $batch_set
  *   The batch set.
+ *
  * @return
  *   The queue object.
  */