diff options
-rw-r--r-- | includes/date.inc | 2 | ||||
-rw-r--r-- | includes/errors.inc | 22 | ||||
-rw-r--r-- | includes/file.inc | 104 | ||||
-rw-r--r-- | includes/form.inc | 163 | ||||
-rw-r--r-- | includes/graph.inc | 4 |
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. |