Issue #1317620 by xjm, Albert Volkman: Fix up API docs for includes directory files d-g

5 files changed, 162 insertions, 133 deletions

diff --git a/includes/date.inc b/includes/date.inc
index 27634f9e3..01ab131b3 100644
--- a/includes/date.inc
+++ b/includes/date.inc
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Initialize the list of date formats and their locales.
+ * Initializes the list of date formats and their locales.
  */
 
 /**
diff --git a/includes/errors.inc b/includes/errors.inc
index cb708d860..f62bf06a5 100644
--- a/includes/errors.inc
+++ b/includes/errors.inc
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Functions for error handling
+ * Functions for error handling.
  */
 
 /**
@@ -21,7 +21,8 @@ define('ERROR_REPORTING_DISPLAY_SOME', 1);
 define('ERROR_REPORTING_DISPLAY_ALL', 2);
 
 /**
- * Map PHP error constants to watchdog severity levels.
+ * Maps PHP error constants to watchdog severity levels.
+ *
  * The error constants are documented at
  * http://php.net/manual/en/errorfunc.constants.php
  *
@@ -52,7 +53,7 @@ function drupal_error_levels() {
 }
 
 /**
- * Custom PHP error handler.
+ * Provides custom PHP error handling.
  *
  * @param $error_level
  *   The level of the error raised.
@@ -63,7 +64,8 @@ function drupal_error_levels() {
  * @param $line
  *   The line number the error was raised at.
  * @param $context
- *   An array that points to the active symbol table at the point the error occurred.
+ *   An array that points to the active symbol table at the point the error
+ *   occurred.
  */
 function _drupal_error_handler_real($error_level, $message, $filename, $line, $context) {
   if ($error_level & error_reporting()) {
@@ -90,10 +92,11 @@ function _drupal_error_handler_real($error_level, $message, $filename, $line, $c
 }
 
 /**
- * Decode an exception, especially to retrive the correct caller.
+ * Decodes an exception and retrieves the correct caller.
  *
  * @param $exception
  *   The exception object that was thrown.
+ *
  * @return
  *   An error in the format expected by _drupal_log_error().
  */
@@ -136,7 +139,7 @@ function _drupal_decode_exception($exception) {
 }
 
 /**
- * Render an error message for an exception without any possibility of a further exception occurring.
+ * Renders an exception error message without further exceptions.
  *
  * @param $exception
  *   The exception object that was thrown.
@@ -171,12 +174,12 @@ function error_displayable($error = NULL) {
 }
 
 /**
- * Log a PHP error or exception, display an error page in fatal cases.
+ * Logs a PHP error or exception and displays an error page in fatal cases.
  *
  * @param $error
  *   An array with the following keys: %type, !message, %function, %file, %line
- *   and severity_level. All the parameters are plain-text, with the exception of
- *   !message, which needs to be a safe HTML string.
+ *   and severity_level. All the parameters are plain-text, with the exception
+ *   of !message, which needs to be a safe HTML string.
  * @param $fatal
  *   TRUE if the error is fatal.
  */
@@ -263,6 +266,7 @@ function _drupal_log_error($error, $fatal = FALSE) {
  *
  * @param $backtrace
  *   A standard PHP backtrace.
+ *
  * @return
  *   An associative array with keys 'file', 'line' and 'function'.
  */
diff --git a/includes/file.inc b/includes/file.inc
index 7fd6c71c9..7ec13f32e 100644
--- a/includes/file.inc
+++ b/includes/file.inc
@@ -70,11 +70,7 @@ define('FILE_EXISTS_ERROR', 2);
 define('FILE_STATUS_PERMANENT', 1);
 
 /**
- * Methods to manage a registry of stream wrappers.
- */
-
-/**
- * Drupal stream wrapper registry.
+ * Provides Drupal stream wrapper registry.
  *
  * A stream wrapper is an abstraction of a file system that allows Drupal to
  * use the same set of methods to access both local files and remote resources.
@@ -206,7 +202,7 @@ function file_uri_scheme($uri) {
 }
 
 /**
- * Check that the scheme of a stream URI is valid.
+ * Checks that the scheme of a stream URI is valid.
  *
  * Confirms that there is a registered stream handler for the provided scheme
  * and that it is callable. This is useful if you want to confirm a valid
@@ -232,7 +228,7 @@ function file_stream_wrapper_valid_scheme($scheme) {
 
 
 /**
- * Returns the part of an URI after the schema.
+ * Returns the part of a URI after the schema.
  *
  * @param $uri
  *   A stream, referenced as "scheme://target".
@@ -252,7 +248,7 @@ function file_uri_target($uri) {
 }
 
 /**
- * Get the default file stream implementation.
+ * Gets the default file stream implementation.
  *
  * @return
  *   'public', 'private' or any other file scheme defined as the default.
@@ -322,7 +318,7 @@ function file_stream_wrapper_get_instance_by_uri($uri) {
 }
 
 /**
- * Returns a reference to the stream wrapper class responsible for a given scheme.
+ * Returns a reference to the stream wrapper class responsible for a scheme.
  *
  * This helper method returns a stream instance using a scheme. That is, the
  * passed string does not contain a "://". For example, "public" is a scheme
@@ -357,7 +353,6 @@ function file_stream_wrapper_get_instance_by_scheme($scheme) {
  * Creates a web-accessible URL for a stream to an external or local file.
  *
  * Compatibility: normal paths and stream wrappers.
- * @see http://drupal.org/node/515192
  *
  * There are two kinds of local files:
  * - "managed files", i.e. those stored by a Drupal-compatible stream wrapper.
@@ -375,6 +370,8 @@ function file_stream_wrapper_get_instance_by_scheme($scheme) {
  *   If the provided string already contains a preceding 'http', 'https', or
  *   '/', nothing is done and the same string is returned. If a stream wrapper
  *   could not be found to generate an external URL, then FALSE is returned.
+ *
+ * @see http://drupal.org/node/515192
  */
 function file_create_url($uri) {
   // Allow the URI to be altered, e.g. to serve a file from a CDN or static
@@ -417,7 +414,7 @@ function file_create_url($uri) {
 }
 
 /**
- * Check that the directory exists and is writable.
+ * Checks that the directory exists and is writable.
  *
  * Directories need to have execute permissions to be considered a directory by
  * FTP servers, etc.
@@ -459,7 +456,7 @@ function file_prepare_directory(&$directory, $options = FILE_MODIFY_PERMISSIONS)
 }
 
 /**
- * If missing, create a .htaccess file in each Drupal files directory.
+ * Creates a .htaccess file in each Drupal files directory if it is missing.
  */
 function file_ensure_htaccess() {
   file_create_htaccess('public://', FALSE);
@@ -470,7 +467,7 @@ function file_ensure_htaccess() {
 }
 
 /**
- * Creates an .htaccess file in the given directory.
+ * Creates a .htaccess file in the given directory.
  *
  * @param $directory
  *   The directory.
@@ -526,19 +523,19 @@ function file_create_htaccess($directory, $private = TRUE) {
  * @return
  *   An array of file objects, indexed by fid.
  *
+ * @todo Remove $conditions in Drupal 8.
+ *
  * @see hook_file_load()
  * @see file_load()
  * @see entity_load()
  * @see EntityFieldQuery
- *
- * @todo Remove $conditions in Drupal 8.
  */
 function file_load_multiple($fids = array(), $conditions = array()) {
   return entity_load('file', $fids, $conditions);
 }
 
 /**
- * Load a file object from the database.
+ * Loads a single file object from the database.
  *
  * @param $fid
  *   A file ID.
@@ -555,7 +552,7 @@ function file_load($fid) {
 }
 
 /**
- * Save a file object to the database.
+ * Saves a file object to the database.
  *
  * If the $file->fid is not set a new record will be added.
  *
@@ -797,7 +794,7 @@ function file_copy(stdClass $source, $destination = NULL, $replace = FILE_EXISTS
 }
 
 /**
- * Determine whether the URI has a valid scheme for file API operations.
+ * Determines whether the URI has a valid scheme for file API operations.
  *
  * There must be a scheme and it must be a Drupal-provided scheme like
  * 'public', 'private', 'temporary', or an extension provided with
@@ -926,7 +923,7 @@ function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXIST
 }
 
 /**
- * Given a relative path, construct a URI into Drupal's default files location.
+ * Constructs a URI to Drupal's default files location given a relative path.
  */
 function file_build_uri($path) {
   $uri = file_default_scheme() . '://' . $path;
@@ -934,8 +931,7 @@ function file_build_uri($path) {
 }
 
 /**
- * Determines the destination path for a file depending on how replacement of
- * existing files should be handled.
+ * Determines the destination path for a file.
  *
  * @param $destination
  *   A string specifying the desired final URI or filepath.
@@ -972,7 +968,7 @@ function file_destination($destination, $replace) {
 }
 
 /**
- * Move a file to a new location and update the file's database entry.
+ * Moves a file to a new location and update the file's database entry.
  *
  * Moving a file is performed by copying the file to the new location and then
  * deleting the original.
@@ -1052,8 +1048,7 @@ function file_move(stdClass $source, $destination = NULL, $replace = FILE_EXISTS
 }
 
 /**
- * Move a file to a new location without calling any hooks or making any
- * changes to the database.
+ * Moves a file to a new location without database changes or hook invocation.
  *
  * @param $source
  *   A string specifying the filepath or URI of the original file.
@@ -1082,7 +1077,7 @@ function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXIST
 }
 
 /**
- * Modify a filename as needed for security purposes.
+ * Modifies a filename as needed for security purposes.
  *
  * Munging a file name prevents unknown file extensions from masking exploit
  * files. When web servers such as Apache decide how to process a URL request,
@@ -1146,7 +1141,7 @@ function file_munge_filename($filename, $extensions, $alerts = TRUE) {
 }
 
 /**
- * Undo the effect of file_munge_filename().
+ * Undoes the effect of file_munge_filename().
  *
  * @param $filename
  *   String with the filename to be unmunged.
@@ -1159,7 +1154,7 @@ function file_unmunge_filename($filename) {
 }
 
 /**
- * Create a full file path from a directory and filename.
+ * Creates a full file path from a directory and filename.
  *
  * If a file with the specified name already exists, an alternative will be
  * used.
@@ -1214,7 +1209,7 @@ function file_create_filename($basename, $directory) {
 }
 
 /**
- * Delete a file and its database record.
+ * Deletes a file and its database record.
  *
  * If the $force parameter is not TRUE, file_usage_list() will be called to
  * determine if the file is being used by any modules. If the file is being
@@ -1269,8 +1264,7 @@ function file_delete(stdClass $file, $force = FALSE) {
 }
 
 /**
- * Delete a file without calling any hooks or making any changes to the
- * database.
+ * Deletes a file without database changes or hook invocations.
  *
  * This function should be used when the file to be deleted does not have an
  * entry recorded in the files table.
@@ -1306,7 +1300,7 @@ function file_unmanaged_delete($path) {
 }
 
 /**
- * Recursively delete all files and directories in the specified filepath.
+ * Deletes all files and directories in the specified filepath recursively.
  *
  * If the specified path is a directory then the function will call itself
  * recursively to process the contents. Once the contents have been removed the
@@ -1344,7 +1338,7 @@ function file_unmanaged_delete_recursive($path) {
 }
 
 /**
- * Determine total disk space used by a single user or the whole filesystem.
+ * Determines total disk space used by a single user or the whole filesystem.
  *
  * @param $uid
  *   Optional. A user id, specifying NULL returns the total space used by all
@@ -1581,7 +1575,6 @@ function file_save_upload($source, $validators = array(), $destination = FALSE,
  * or open_basedir are enabled, so this function fills that gap.
  *
  * Compatibility: normal paths and stream wrappers.
- * @see http://drupal.org/node/515192
  *
  * @param $filename
  *   The filename of the uploaded file.
@@ -1592,6 +1585,7 @@ function file_save_upload($source, $validators = array(), $destination = FALSE,
  *   TRUE on success, or FALSE on failure.
  *
  * @see move_uploaded_file()
+ * @see http://drupal.org/node/515192
  * @ingroup php_wrappers
  */
 function drupal_move_uploaded_file($filename, $uri) {
@@ -1612,7 +1606,7 @@ function drupal_move_uploaded_file($filename, $uri) {
 }
 
 /**
- * Check that a file meets the criteria specified by the validators.
+ * Checks that a file meets the criteria specified by the validators.
  *
  * After executing the validator callbacks specified hook_file_validate() will
  * also be called to allow other modules to report errors about the file.
@@ -1647,10 +1641,11 @@ function file_validate(stdClass &$file, $validators = array()) {
 }
 
 /**
- * Check for files with names longer than we can store in the database.
+ * Checks for files with names longer than we can store in the database.
  *
  * @param $file
  *   A Drupal file object.
+ *
  * @return
  *   An array. If the file name is too long, it will contain an error message.
  */
@@ -1667,7 +1662,7 @@ function file_validate_name_length(stdClass $file) {
 }
 
 /**
- * Check that the filename ends with an allowed extension.
+ * Checks that the filename ends with an allowed extension.
  *
  * @param $file
  *   A Drupal file object.
@@ -1691,7 +1686,7 @@ function file_validate_extensions(stdClass $file, $extensions) {
 }
 
 /**
- * Check that the file's size is below certain limits.
+ * Checks that the file's size is below certain limits.
  *
  * This check is not enforced for the user #1.
  *
@@ -1730,7 +1725,7 @@ function file_validate_size(stdClass $file, $file_limit = 0, $user_limit = 0) {
 }
 
 /**
- * Check that the file is recognized by image_get_info() as an image.
+ * Checks that the file is recognized by image_get_info() as an image.
  *
  * @param $file
  *   A Drupal file object.
@@ -1752,7 +1747,7 @@ function file_validate_is_image(stdClass $file) {
 }
 
 /**
- * Verify that image dimensions are within the specified maximum and minimum.
+ * Verifies that image dimensions are within the specified maximum and minimum.
  *
  * Non-image files will be ignored. If a image toolkit is available the image
  * will be scaled to fit within the desired maximum dimensions.
@@ -1810,7 +1805,7 @@ function file_validate_image_resolution(stdClass $file, $maximum_dimensions = 0,
 }
 
 /**
- * Save a string to the specified destination and create a database file entry.
+ * Saves a file to the specified destination and creates a database entry.
  *
  * @param $data
  *   A string containing the contents of the file.
@@ -1874,7 +1869,7 @@ function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAM
 }
 
 /**
- * Save a string to the specified destination without invoking file API.
+ * Saves a string to the specified destination without invoking file API.
  *
  * This function is identical to file_save_data() except the file will not be
  * saved to the {file_managed} table and none of the file_* hooks will be
@@ -1885,7 +1880,8 @@ function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAM
  * @param $destination
  *   A string containing the destination location. This must be a stream wrapper
  *   URI. If no value is provided, a randomized name will be generated and the
- *   file will be saved using Drupal's default files scheme, usually "public://".
+ *   file will be saved using Drupal's default files scheme, usually
+ *   "public://".
  * @param $replace
  *   Replace behavior when the destination file already exists:
  *   - FILE_EXISTS_REPLACE - Replace the existing file.
@@ -1911,7 +1907,7 @@ function file_unmanaged_save_data($data, $destination = NULL, $replace = FILE_EX
 }
 
 /**
- * Transfer file using HTTP to client.
+ * Transfers a file to the client using HTTP.
  *
  * Pipes a file through Drupal to the client.
  *
@@ -1953,7 +1949,7 @@ function file_transfer($uri, $headers) {
  * exists but no modules responded drupal_access_denied() will be returned.
  * If the file does not exist drupal_not_found() will be returned.
  *
- * @see hook_file_download()
+ * @see system_menu()
  */
 function file_download() {
   // Merge remainder of arguments from GET['q'], into relative file path.
@@ -2063,7 +2059,7 @@ function file_scan_directory($dir, $mask, $options = array(), $depth = 0) {
 }
 
 /**
- * Determine the maximum file upload size by querying the PHP settings.
+ * Determines the maximum file upload size by querying the PHP settings.
  *
  * @return
  *   A file size limit in bytes based on the PHP upload_max_filesize and
@@ -2087,7 +2083,7 @@ function file_upload_max_size() {
 }
 
 /**
- * Determine an Internet Media Type, or MIME type from a filename.
+ * Determines an Internet Media Type or MIME type from a filename.
  *
  * @param $uri
  *   A string containing the URI, path, or filename.
@@ -2116,7 +2112,7 @@ function file_get_mimetype($uri, $mapping = NULL) {
 }
 
 /**
- * Set the permissions on a file or directory.
+ * Sets the permissions on a file or directory.
  *
  * This function will use the 'file_chmod_directory' and 'file_chmod_file'
  * variables for the default modes for directories and uploaded/generated
@@ -2222,10 +2218,11 @@ function drupal_unlink($uri, $context = NULL) {
  *   The absolute local filesystem path (with no symbolic links), or FALSE on
  *   failure.
  *
+ * @todo This function is deprecated, and should be removed wherever possible.
+ *
  * @see DrupalStreamWrapperInterface::realpath()
  * @see http://php.net/manual/function.realpath.php
  * @ingroup php_wrappers
- * @todo: This function is deprecated, and should be removed wherever possible.
  */
 function drupal_realpath($uri) {
   // If this URI is a stream, pass it off to the appropriate stream wrapper.
@@ -2252,7 +2249,6 @@ function drupal_realpath($uri) {
  * PHP's dirname() as a fallback.
  *
  * Compatibility: normal paths and stream wrappers.
- * @see http://drupal.org/node/515192
  *
  * @param $uri
  *   A URI or path.
@@ -2261,6 +2257,7 @@ function drupal_realpath($uri) {
  *   A string containing the directory name.
  *
  * @see dirname()
+ * @see http://drupal.org/node/515192
  * @ingroup php_wrappers
  */
 function drupal_dirname($uri) {
@@ -2310,7 +2307,6 @@ function drupal_basename($uri, $suffix = NULL) {
  * is not provided, this function will make sure that Drupal's is used.
  *
  * Compatibility: normal paths and stream wrappers.
- * @see http://drupal.org/node/515192
  *
  * @param $uri
  *   A URI or pathname.
@@ -2325,6 +2321,7 @@ function drupal_basename($uri, $suffix = NULL) {
  *   Boolean TRUE on success, or FALSE on failure.
  *
  * @see mkdir()
+ * @see http://drupal.org/node/515192
  * @ingroup php_wrappers
  */
 function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) {
@@ -2341,7 +2338,7 @@ function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) {
 }
 
 /**
- * Remove a directory.
+ * Removes a directory.
  *
  * PHP's rmdir() is broken on Windows, as it can fail to remove a directory
  * when it has a read-only flag set.
@@ -2378,7 +2375,6 @@ function drupal_rmdir($uri, $context = NULL) {
  * given a filepath.
  *
  * Compatibility: normal paths and stream wrappers.
- * @see http://drupal.org/node/515192
  *
  * @param $directory
  *   The directory where the temporary filename will be created.
@@ -2390,6 +2386,7 @@ function drupal_rmdir($uri, $context = NULL) {
  *   The new temporary filename, or FALSE on failure.
  *
  * @see tempnam()
+ * @see http://drupal.org/node/515192
  * @ingroup php_wrappers
  */
 function drupal_tempnam($directory, $prefix) {
@@ -2412,7 +2409,7 @@ function drupal_tempnam($directory, $prefix) {
 }
 
 /**
- * Get the path of system-appropriate temporary directory.
+ * Gets the path of system-appropriate temporary directory.
  */
 function file_directory_temp() {
   $temporary_directory = variable_get('file_temporary_path', NULL);
@@ -2469,6 +2466,7 @@ function file_directory_temp() {
  *
  * @param $file
  *   A file object.
+ *
  * @return
  *   An associative array of headers, as expected by file_transfer().
  */
diff --git a/includes/form.inc b/includes/form.inc
index 6ad6921d7..dfac67d8b 100644
--- a/includes/form.inc
+++ b/includes/form.inc
@@ -1,4 +1,8 @@
 <?php
+ /**
+ * @file
+ * Functions for form and batch generation and processing.
+ */
 
 /**
  * @defgroup forms Form builder functions
@@ -90,7 +94,11 @@
  */
 
 /**
- * Wrapper for drupal_build_form() for use when $form_state is not needed.
+ * Returns a renderable form array for a given form ID.
+ *
+ * This function should be used instead of drupal_build_form() when $form_state
+ * is not needed (i.e., when initially rendering the form) and is often
+ * used as a menu callback.
  *
  * @param $form_id
  *   The unique string identifying the desired form. If a function with that
@@ -124,7 +132,7 @@ function drupal_get_form($form_id) {
 }
 
 /**
- * Build and process a form based on a form id.
+ * Builds and process 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
@@ -207,8 +215,8 @@ function drupal_get_form($form_id) {
  *     validation functions and submit functions use this array for nearly all
  *     their decision making. (Note that
  *     @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7#tree #tree @endlink
- *     determines whether the values are a flat array or an array whose structure
- *     parallels the $form array.)
+ *     determines whether the values are a flat array or an array whose
+ *     structure parallels the $form array.)
  *   - input: The array of values as they were submitted by the user. These are
  *     raw and unvalidated, so should not be used without a thorough
  *     understanding of security implications. In almost all cases, code should
@@ -377,7 +385,7 @@ function drupal_build_form($form_id, &$form_state) {
 }
 
 /**
- * Retrieve default values for the $form_state array.
+ * Retrieves default values for the $form_state array.
  */
 function form_state_defaults() {
   return array(
@@ -483,7 +491,7 @@ function drupal_rebuild_form($form_id, &$form_state, $old_form = NULL) {
 }
 
 /**
- * Fetch a form from cache.
+ * Fetches a form from cache.
  */
 function form_get_cache($form_build_id, &$form_state) {
   if ($cached = cache_get('form_' . $form_build_id, 'cache_form')) {
@@ -514,7 +522,7 @@ function form_get_cache($form_build_id, &$form_state) {
 }
 
 /**
- * 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.
@@ -564,7 +572,7 @@ function form_state_keys_no_cache() {
 }
 
 /**
- * Loads an include file and makes sure it is loaded whenever the form is processed.
+ * Ensures an include file is loaded loaded whenever the form is processed.
  *
  * Example:
  * @code
@@ -930,9 +938,10 @@ function drupal_process_form($form_id, &$form, &$form_state) {
 }
 
 /**
- * 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,
@@ -1060,8 +1069,7 @@ function drupal_prepare_form($form_id, &$form, &$form_state) {
 
 
 /**
- * Validates user-submitted form data from the $form_state using
- * the validate functions defined in a structured form array.
+ * Validates user-submitted form data in the $form_state array.
  *
  * @param $form_id
  *   A unique string identifying the form for validation, submission,
@@ -1235,9 +1243,11 @@ function drupal_redirect_form($form_state) {
 }
 
 /**
- * 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 validators.
  *
  * @param $elements
  *   An associative array containing the structure of the form.
@@ -1389,9 +1399,10 @@ function _form_validate(&$elements, &$form_state, $form_id = NULL) {
 }
 
 /**
- * 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.
+ * Executes 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.
  *
  * @param $type
  *   The type of handler to execute. 'validate' or 'submit' are the
@@ -1513,8 +1524,6 @@ function form_execute_handlers($type, &$form, &$form_state) {
  * doing anything with that data that requires it to be valid, PHP errors
  * would be triggered if the input processing and validation steps were fully
  * skipped.
- * @see http://drupal.org/node/370537
- * @see http://drupal.org/node/763376
  *
  * @param $name
  *   The name of the form element. If the #parents property of your form
@@ -1530,6 +1539,9 @@ function form_execute_handlers($type, &$form, &$form_state) {
  * @return
  *   Return value is for internal use only. To get a list of errors, use
  *   form_get_errors() or form_get_error().
+ *
+ * @see http://drupal.org/node/370537
+ * @see http://drupal.org/node/763376
  */
 function form_set_error($name = NULL, $message = '', $limit_validation_errors = NULL) {
   $form = &drupal_static(__FUNCTION__, array());
@@ -1575,14 +1587,14 @@ function form_set_error($name = NULL, $message = '', $limit_validation_errors =
 }
 
 /**
- * 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();
@@ -1610,16 +1622,18 @@ function form_get_error($element) {
 }
 
 /**
- * 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 properties to
- * each element and mapping the incoming input data to the proper elements.
- * Also, execute any #process handlers attached to a specific element.
+ * Builds and processes all elements in the structured form array.
+ *
+ * Adds any required properties to each element, maps the incoming input data
+ * to the proper elements, and 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
@@ -1891,8 +1905,7 @@ function form_builder($form_id, &$element, &$form_state) {
 }
 
 /**
- * Populate the #value and #name properties of input elements so they
- * can be processed and rendered.
+ * Adds the #name and #value properties of an input element before rendering.
  */
 function _form_builder_handle_input_element($form_id, &$element, &$form_state) {
   if (!isset($element['#name'])) {
@@ -2031,7 +2044,7 @@ function _form_builder_handle_input_element($form_id, &$element, &$form_state) {
 }
 
 /**
- * Helper function to handle the convoluted logic of button click detection.
+ * Detects if an element triggered the form submission via Ajax.
  *
  * This detects button or non-button controls that trigger a form submission via
  * Ajax or some other scriptable environment. These environments can set the
@@ -2051,7 +2064,7 @@ function _form_element_triggered_scripted_submission($element, &$form_state) {
 }
 
 /**
- * Helper function to handle the convoluted logic of button click detection.
+ * Determines if a given button triggered the form submission.
  *
  * 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
@@ -2146,7 +2159,7 @@ function form_state_values_clean(&$form_state) {
 }
 
 /**
- * Helper function to determine the value for an image button form element.
+ * Determines the value for an image button form element.
  *
  * @param $form
  *   The form element whose value is being populated.
@@ -2155,6 +2168,7 @@ function form_state_values_clean(&$form_state) {
  *   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.
@@ -2193,13 +2207,14 @@ function form_type_image_button_value($form, $input, $form_state) {
 }
 
 /**
- * Helper function to determine the value for a checkbox form element.
+ * Determines the value for a checkbox form element.
  *
  * @param $form
  *   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.
@@ -2233,13 +2248,14 @@ function form_type_checkbox_value($element, $input = FALSE) {
 }
 
 /**
- * Helper function to determine the value for a checkboxes form element.
+ * Determines the value for a 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.
@@ -2273,13 +2289,14 @@ function form_type_checkboxes_value($element, $input = FALSE) {
 }
 
 /**
- * Helper function to determine the value for a tableselect form element.
+ * Determines the value for a tableselect 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.
@@ -2308,14 +2325,14 @@ function form_type_tableselect_value($element, $input = FALSE) {
 }
 
 /**
- * Helper function to determine the value for a password_confirm form
- * element.
+ * Determines the value for a 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.
@@ -2328,13 +2345,14 @@ function form_type_password_confirm_value($element, $input = FALSE) {
 }
 
 /**
- * Helper function to determine the value for a select form element.
+ * Determines the value for a 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.
@@ -2368,13 +2386,14 @@ function form_type_select_value($element, $input = FALSE) {
 }
 
 /**
- * Helper function to determine the value for a textfield form element.
+ * Determines the value for a 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.
@@ -2388,13 +2407,14 @@ function form_type_textfield_value($element, $input = FALSE) {
 }
 
 /**
- * Helper function to determine the value for form's token value.
+ * Determines the value for form's token value.
  *
  * @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.
@@ -2406,7 +2426,7 @@ function form_type_token_value($element, $input = FALSE) {
 }
 
 /**
- * Changes submitted form values in $form_state.
+ * 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
@@ -2458,11 +2478,9 @@ function form_options_flatten($array) {
 }
 
 /**
- * Helper function for form_options_flatten().
+ * Iterates over an array and returns a flat array with duplicate keys removed.
  *
- * Iterates over arrays which may share common values and produces a flat
- * array that has removed duplicate keys. Also handles cases where objects
- * are passed as array values.
+ * This function also handles cases where objects are passed as array values.
  */
 function _form_options_flatten($array) {
   $return = &drupal_static(__FUNCTION__);
@@ -2572,7 +2590,7 @@ function theme_select($variables) {
 }
 
 /**
- * Converts 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.
@@ -2580,6 +2598,7 @@ function theme_select($variables) {
  *   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.
  */
@@ -2616,8 +2635,7 @@ function form_select_options($element, $choices = NULL) {
 }
 
 /**
- * Traverses a select element's #option array looking for any values
- * that hold the given key. Returns an array of indexes that match.
+ * Returns the indexes of a select element's options matching a given key.
  *
  * This function is useful if you need to modify the options that are
  * already in a form element; for example, to remove choices which are
@@ -2643,6 +2661,7 @@ function form_select_options($element, $choices = NULL) {
  *   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.
@@ -2779,7 +2798,7 @@ function form_process_password_confirm($element) {
 }
 
 /**
- * Validate password_confirm element.
+ * Validates a password_confirm element.
  */
 function password_confirm_validate($element, &$element_state) {
   $pass1 = trim($element['pass1']['#value']);
@@ -2830,7 +2849,7 @@ function theme_date($variables) {
 }
 
 /**
- * Roll out a single date element.
+ * Expands a date element into year, month, and day select elements.
  */
 function form_process_date($element) {
   // Default to current date
@@ -2886,7 +2905,7 @@ function form_process_date($element) {
 }
 
 /**
- * Validates the date type to stop dates like February 30, 2006.
+ * Validates the date type to prevent invalid dates (e.g., February 30, 2006).
  */
 function date_validate($element) {
   if (!checkdate($element['#value']['month'], $element['#value']['day'], $element['#value']['year'])) {
@@ -2916,7 +2935,7 @@ function map_month($month) {
 }
 
 /**
- * If no default value is set for weight select boxes, use 0.
+ * Sets the value for a weight element, with zero as a default.
  */
 function weight_value(&$form) {
   if (isset($form['#default_value'])) {
@@ -2928,8 +2947,7 @@ function weight_value(&$form) {
 }
 
 /**
- * Roll out a single radios element to a list of radios,
- * using the options array as index.
+ * Expands a radios element into individual radio elements.
  */
 function form_process_radios($element) {
   if (count($element['#options']) > 0) {
@@ -3012,7 +3030,7 @@ function theme_checkboxes($variables) {
 }
 
 /**
- * Add form_element theming to an element if title or description is set.
+ * Adds form element theming to an element if its title or description is set.
  *
  * This is used as a pre render function for checkboxes and radios.
  */
@@ -3059,6 +3077,9 @@ function form_process_checkbox($element, $form_state) {
   return $element;
 }
 
+/**
+ * Processes a checkboxes form element.
+ */
 function form_process_checkboxes($element) {
   $value = is_array($element['#value']) ? $element['#value'] : array();
   $element['#tree'] = TRUE;
@@ -3120,6 +3141,7 @@ function form_process_actions($element, &$form_state) {
  *   container.
  * @param $form_state
  *   The $form_state array for the form this element belongs to.
+ *
  * @return
  *   The processed element.
  */
@@ -3230,11 +3252,12 @@ function theme_tableselect($variables) {
 }
 
 /**
- * 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.
  */
@@ -3398,7 +3421,7 @@ function form_process_machine_name($element, &$form_state) {
 }
 
 /**
- * Form element validation handler for #type 'machine_name'.
+ * Form element validation handler for machine_name elements.
  *
  * Note that #maxlength is validated by _form_validate() already.
  */
@@ -3436,8 +3459,7 @@ function form_validate_machine_name(&$element, &$form_state) {
 }
 
 /**
- * Adds fieldsets to the specified group or adds group members to this
- * fieldset.
+ * Arranges fieldsets into groups.
  *
  * @param $element
  *   An associative array containing the properties and children of the
@@ -3445,6 +3467,7 @@ function form_validate_machine_name(&$element, &$form_state) {
  *   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.
  */
@@ -3548,6 +3571,7 @@ function form_pre_render_fieldset($element) {
  *   fieldset.
  * @param $form_state
  *   The $form_state array for the form this vertical tab widget belongs to.
+ *
  * @return
  *   The processed element.
  */
@@ -3582,8 +3606,8 @@ function form_process_vertical_tabs($element, &$form_state) {
  *
  * @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.
  *
  * @ingroup themeable
  */
@@ -3792,7 +3816,7 @@ function theme_password($variables) {
 }
 
 /**
- * Expand weight elements into selects.
+ * Expands a weight element into a select element.
  */
 function form_process_weight($element) {
   $element['#is_weight'] = TRUE;
@@ -3976,7 +4000,8 @@ function theme_form_required_marker($variables) {
  *
  * 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,
@@ -4055,7 +4080,7 @@ function _form_set_class(&$element, $class = array()) {
 }
 
 /**
- * Helper form element validator: integer.
+ * Form element validation handler for integer elements.
  */
 function element_validate_integer($element, &$form_state) {
   $value = $element['#value'];
@@ -4065,7 +4090,7 @@ function element_validate_integer($element, &$form_state) {
 }
 
 /**
- * Helper form element validator: integer > 0.
+ * Form element validation handler for integer elements that must be positive.
  */
 function element_validate_integer_positive($element, &$form_state) {
   $value = $element['#value'];
@@ -4075,7 +4100,7 @@ function element_validate_integer_positive($element, &$form_state) {
 }
 
 /**
- * Helper form element validator: number.
+ * Form element validation handler for number elements.
  */
 function element_validate_number($element, &$form_state) {
   $value = $element['#value'];
@@ -4091,7 +4116,7 @@ function element_validate_number($element, &$form_state) {
 /**
  * @defgroup batch Batch operations
  * @{
- * Create and process batch operations.
+ * Creates and processes batch operations.
  *
  * Functions allowing forms processing to be spread out over several page
  * requests, thus ensuring that the processing does not get interrupted
@@ -4422,6 +4447,7 @@ function &batch_get() {
  *   The batch array.
  * @param $set_id
  *   The id of the set to process.
+ *
  * @return
  *   The name and class of the queue are added by reference to the batch set.
  */
@@ -4451,6 +4477,7 @@ function _batch_populate_queue(&$batch, $set_id) {
  *
  * @param $batch_set
  *   The batch set.
+ *
  * @return
  *   The queue object.
  */
diff --git a/includes/graph.inc b/includes/graph.inc
index 7fcc57a45..9ef86a145 100644
--- a/includes/graph.inc
+++ b/includes/graph.inc
@@ -7,7 +7,7 @@
 
 
 /**
- * Perform a depth first sort on a directed acyclic graph.
+ * Performs a depth-first sort on a directed acyclic graph.
  *
  * @param $graph
  *   A three dimensional associated array, with the first keys being the names
@@ -72,7 +72,7 @@ function drupal_depth_first_search(&$graph) {
 }
 
 /**
- * Helper function to perform a depth first sort.
+ * Performs a depth-first sort on a graph.
  *
  * @param $graph
  *   A three dimensional associated graph array.