Drupal
/
drupal
mirror of https://git.drupalcode.org/project/drupal.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

merge-requests/26/head
Jennifer Hodgdon 2012-03-12 08:05:51 -07:00
parent f145e08cfd
commit b5dc528a66
5 changed files with 162 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
includes/date.inc
View File

@ -2,7 +2,7 @@
/**
* @file
* Initialize the list of date formats and their locales.
* Initializes the list of date formats and their locales.
*/
/**

22
includes/errors.inc
View File

@ -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'.
*/

104
includes/file.inc
View File

@ -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().
*/

163
includes/form.inc
View File

@ -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.
*/

4
includes/graph.inc
View File

@ -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.