diff --git a/includes/actions.inc b/includes/actions.inc index 760de83..9318591 100644 --- a/includes/actions.inc +++ b/includes/actions.inc @@ -48,6 +48,7 @@ * Passed along to the callback. * @param $a2 * Passed along to the callback. + * * @return * An associative array containing the results of the functions that * perform the actions, keyed on action ID. @@ -149,6 +150,7 @@ function actions_do($action_ids, $object = NULL, $context = NULL, $a1 = NULL, $a * * @param $reset * Reset the action info static cache. + * * @return * An associative array keyed on action function name, with the same format * as the return value of hook_action_info(), containing all @@ -176,10 +178,10 @@ function actions_list($reset = FALSE) { * function and the actions returned by actions_list() are partially * synchronized. Non-configurable actions from hook_action_info() * implementations are put into the database when actions_synchronize() is - * called, which happens when admin/config/system/actions is visited. Configurable - * actions are not added to the database until they are configured in the - * user interface, in which case a database row is created for each - * configuration of each action. + * called, which happens when admin/config/system/actions is visited. + * Configurable actions are not added to the database until they are + * configured in the user interface, in which case a database row is created + * for each configuration of each action. * * @return * Associative array keyed by numeric action ID. Each value is an associative @@ -205,6 +207,7 @@ function actions_get_all_actions() { * An associative array with function names or action IDs as keys * and associative arrays with keys 'label', 'type', etc. as values. * This is usually the output of actions_list() or actions_get_all_actions(). + * * @return * An associative array whose keys are hashes of the input array keys, and * whose corresponding values are associative arrays with components @@ -225,12 +228,14 @@ function actions_actions_map($actions) { /** * Given a hash of an action array key, returns the key (function or ID). * - * Faster than actions_actions_map() when you only need the function name or ID. + * Faster than actions_actions_map() when you only need the function name or + * ID. * * @param $hash * Hash of a function name or action ID array key. The array key * is a key into the return value of actions_list() (array key is the action * function name) or actions_get_all_actions() (array key is the action ID). + * * @return * The corresponding array key, or FALSE if no match is found. */ @@ -332,6 +337,7 @@ function actions_synchronize($delete_orphans = FALSE) { * to Jim'. * @param $aid * The ID of this action. If omitted, a new action is created. + * * @return * The ID of the action. */ @@ -361,6 +367,7 @@ function actions_save($function, $type, $params, $label, $aid = NULL) { * * @param $aid * The ID of the action to retrieve. + * * @return * The appropriate action row from the database as an object. */ diff --git a/includes/ajax.inc b/includes/ajax.inc index cda55b4..d6b85ab 100644 --- a/includes/ajax.inc +++ b/includes/ajax.inc @@ -24,7 +24,8 @@ * ajax_form_callback() and a defined #ajax['callback'] function. * However, you may optionally specify a different path to request or a * different callback function to invoke, which can return updated HTML or can - * also return a richer set of @link ajax_commands Ajax framework commands @endlink. + * also return a richer set of + * @link ajax_commands Ajax framework commands @endlink. * * Standard form handling is as follows: * - A form element has a #ajax property that includes #ajax['callback'] and @@ -46,8 +47,8 @@ * function named by #ajax['callback'], which returns the form element that * has been updated and needs to be returned to the browser, or * alternatively, an array of custom Ajax commands. - * - The page delivery callback for 'system/ajax', ajax_deliver(), renders the - * element returned by #ajax['callback'], and returns the JSON string + * - The page delivery callback for 'system/ajax', ajax_deliver(), renders + * the element returned by #ajax['callback'], and returns the JSON string * created by ajax_render() to the browser. * - The browser unserializes the returned JSON string into an array of * command objects and executes each command, resulting in the old page @@ -126,8 +127,8 @@ * to a menu page callback that returns data using ajax_render(). Defaults to * 'system/ajax', which invokes ajax_form_callback(), eventually calling * the function named in #ajax['callback']. If you use a custom - * path, you must set up the menu entry and handle the entire callback in your - * own code. + * path, you must set up the menu entry and handle the entire callback in + * your own code. * - #ajax['wrapper']: The CSS ID of the area to be replaced by the content * returned by the #ajax['callback'] function. The content returned from * the callback will replace the entire element named by #ajax['wrapper']. @@ -147,17 +148,18 @@ * Defaults to 'click' for #ajax on #type 'submit', 'button', and * 'image_button'. Multiple events may be specified separated by spaces. * For example, when binding #ajax behaviors to form buttons, pressing the - * ENTER key within a textfield triggers the 'click' event of the form's first - * submit button. Triggering Ajax in this situation leads to problems, like - * breaking autocomplete textfields. Because of that, Ajax behaviors are bound - * to the 'mousedown' event on form buttons by default. However, binding to - * 'mousedown' rather than 'click' means that it is possible to trigger a - * click by pressing the mouse, holding the mouse button down until the Ajax - * request is complete and the button is re-enabled, and then releasing the - * mouse button. For this case, 'prevent' can be set to 'click', so an - * additional event handler is bound to prevent such a click from triggering a - * non-Ajax form submission. This also prevents a textfield's ENTER press - * triggering a button's non-Ajax form submission behavior. + * ENTER key within a textfield triggers the 'click' event of the form's + * first *submit button. Triggering Ajax in this situation leads to + * problems, like breaking autocomplete textfields. Because of that, Ajax + * behaviors are bound to the 'mousedown' event on form buttons by default. + * However, binding to 'mousedown' rather than 'click' means that it is + * possible to trigger a click by pressing the mouse, holding the mouse + * button down until the Ajax request is complete and the button is + * re-enabled, and then releasing the mouse button. For this case, 'prevent' + * can be set to 'click', so an additional event handler is bound to + * prevent such a click from triggering a non-Ajax form submission. This + * also prevents a textfield's ENTER press triggering a button's non-Ajax + * form submission behavior. * - #ajax['method']: The jQuery method to use to place the new HTML. * Defaults to 'replaceWith'. May be: 'replaceWith', 'append', 'prepend', * 'before', 'after', or 'html'. See the @@ -188,11 +190,12 @@ * be converted to a JSON object and returned to the client, which will then * iterate over the array and process it like a macro language. * - * Each command item is an associative array which will be converted to a command - * object on the JavaScript side. $command_item['command'] is the type of - * command, e.g. 'alert' or 'replace', and will correspond to a method in the - * Drupal.ajax[command] space. The command array may contain any other data - * that the command needs to process, e.g. 'method', 'selector', 'settings', etc. + * Each command item is an associative array which will be converted to a + * command object on the JavaScript side. $command_item['command'] is the type + * of command, e.g. 'alert' or 'replace', and will correspond to a method in + * the Drupal.ajax[command] space. The command array may contain any other + * data that the command needs to process, e.g. 'method', 'selector', + * 'settings', etc. * * Commands are usually created with a couple of helper functions, so they * look like this: @@ -222,7 +225,7 @@ */ /** - * Render a commands array into JSON. + * Renders a commands array into JSON. * * @param $commands * A list of macro commands generated by the use of ajax_command_*() @@ -301,7 +304,7 @@ function ajax_render($commands = array()) { } /** - * Get a form submitted via #ajax during an Ajax callback. + * Gets a form submitted via #ajax during an Ajax callback. * * This will load a form from the form cache used during Ajax operations. It * pulls the form info from $_POST. @@ -348,11 +351,13 @@ function ajax_get_form() { } /** - * Menu callback; handles Ajax requests for the #ajax Form API property. + * Page callback: Handles Ajax requests for the #ajax Form API property. + * + * Path: system/ajax * * This rebuilds the form from cache and invokes the defined #ajax['callback'] - * to return an Ajax command structure for JavaScript. In case no 'callback' has - * been defined, nothing will happen. + * to return an Ajax command structure for JavaScript. In case no 'callback' + * has been defined, nothing will happen. * * The Form API #ajax property can be set both for buttons and other input * elements. @@ -361,6 +366,8 @@ function ajax_get_form() { * #ajax['path']. If processing is required that cannot be accomplished with * a callback, re-implement this function and set #ajax['path'] to the * enhanced function. + * + * @see system_menu() */ function ajax_form_callback() { list($form, $form_state) = ajax_get_form(); @@ -381,21 +388,29 @@ function ajax_form_callback() { } /** - * Theme callback for Ajax requests. + * Theme callback: Returns the correct theme for an Ajax request. + * + * Paths: + * - system/ajax + * - file/ajax + * - file/progress * * Many different pages can invoke an Ajax request to system/ajax or another * generic Ajax path. It is almost always desired for an Ajax response to be - * rendered using the same theme as the base page, because most themes are built - * with the assumption that they control the entire page, so if the CSS for two - * themes are both loaded for a given page, they may conflict with each other. - * For example, Bartik is Drupal's default theme, and Seven is Drupal's default - * administration theme. Depending on whether the "Use the administration theme - * when editing or creating content" checkbox is checked, the node edit form may - * be displayed in either theme, but the Ajax response to the Field module's - * "Add another item" button should be rendered using the same theme as the rest - * of the page. Therefore, system_menu() sets the 'theme callback' for - * 'system/ajax' to this function, and it is recommended that modules - * implementing other generic Ajax paths do the same. + * rendered using the same theme as the base page, because most themes are + * built with the assumption that they control the entire page, so if the CSS + * for two themes are both loaded for a given page, they may conflict with + * each other. For example, Bartik is Drupal's default theme, and Seven is + * Drupal's default administration theme. Depending on whether the "Use the + * administration theme when editing or creating content" checkbox is checked, + * the node edit form may be displayed in either theme, but the Ajax response + * to the Field module's "Add another item" button should be rendered using + * the same theme as the rest of the page. Therefore, system_menu() sets the + * 'theme callback' for 'system/ajax' to this function, and it is recommended + * that modules implementing other generic Ajax paths do the same. + * + * @see system_menu() + * @see file_menu() */ function ajax_base_page_theme() { if (!empty($_POST['ajax_page_state']['theme']) && !empty($_POST['ajax_page_state']['theme_token'])) { @@ -414,7 +429,7 @@ function ajax_base_page_theme() { } /** - * Package and send the result of a page callback to the browser as an Ajax response. + * Packages and sends the result of a page callback as an Ajax response. * * This function is the equivalent of drupal_deliver_html_page(), but for Ajax * requests. Like that function, it: @@ -547,7 +562,7 @@ function ajax_prepare_response($page_callback_result) { } /** - * Perform end-of-Ajax-request tasks. + * Performs end-of-Ajax-request tasks. * * This function is the equivalent of drupal_page_footer(), but for Ajax * requests. @@ -570,7 +585,7 @@ function ajax_footer() { } /** - * Form element process callback to handle #ajax. + * Form element processing handler to handle the #ajax form property. * * @param $element * An associative array containing the properties of the element. @@ -589,7 +604,7 @@ function ajax_process_form($element, &$form_state) { } /** - * Add Ajax information about an element to the page to communicate with JavaScript. + * Adds Ajax information about an element to communicate with JavaScript. * * If #ajax['path'] is set on an element, this additional JavaScript is added * to the page header to attach the Ajax behaviors. See ajax.js for more @@ -912,8 +927,8 @@ function ajax_command_prepend($selector, $html, $settings = NULL) { * Creates a Drupal Ajax 'insert/append' command. * * The 'insert/append' command instructs the client to use jQuery's append() - * method to append the given HTML content to the inside of each element matched - * by the given selector. + * method to append the given HTML content to the inside of each element + * matched by the given selector. * * This command is implemented by Drupal.ajax.prototype.commands.insert() * defined in misc/ajax.js. @@ -1036,8 +1051,8 @@ function ajax_command_remove($selector) { /** * Creates a Drupal Ajax 'changed' command. * - * This command instructs the client to mark each of the elements matched by the - * given selector as 'ajax-changed'. + * This command instructs the client to mark each of the elements matched by + * the given selector as 'ajax-changed'. * * This command is implemented by Drupal.ajax.prototype.commands.changed() * defined in misc/ajax.js. diff --git a/includes/archiver.inc b/includes/archiver.inc index fec053b..fedda05 100644 --- a/includes/archiver.inc +++ b/includes/archiver.inc @@ -6,12 +6,12 @@ */ /** - * Common interface for all Archiver classes. + * Defines the common interface for all Archiver classes. */ interface ArchiverInterface { /** - * Constructor for a new archiver instance. + * Constructs a new archiver instance. * * @param $file_path * The full system path of the archive to manipulate. Only local files @@ -21,28 +21,30 @@ interface ArchiverInterface { public function __construct($file_path); /** - * Add the specified file or directory to the archive. + * Adds the specified file or directory to the archive. * * @param $file_path * The full system path of the file or directory to add. Only local files * and directories are supported. + * * @return ArchiverInterface * The called object. */ public function add($file_path); /** - * Remove the specified file from the archive. + * Removes the specified file from the archive. * * @param $path * The file name relative to the root of the archive to remove. + * * @return ArchiverInterface * The called object. */ public function remove($path); /** - * Extract multiple files in the archive to the specified path. + * Extracts multiple files in the archive to the specified path. * * @param $path * A full system path of the directory to which to extract files. @@ -50,13 +52,14 @@ interface ArchiverInterface { * Optionally specify a list of files to be extracted. Files are * relative to the root of the archive. If not specified, all files * in the archive will be extracted + * * @return ArchiverInterface * The called object. */ public function extract($path, Array $files = array()); /** - * List all files in the archive. + * Lists all files in the archive. * * @return * An array of file names relative to the root of the archive. diff --git a/includes/authorize.inc b/includes/authorize.inc index 862992f..5ee359d 100644 --- a/includes/authorize.inc +++ b/includes/authorize.inc @@ -6,7 +6,11 @@ */ /** - * Build the form for choosing a FileTransfer type and supplying credentials. + * Form constructor for the file transfer authorization form. + * + * Allows the user to choose a FileTransfer type and supply credentials. + * + * @ingroup forms */ function authorize_filetransfer_form($form, &$form_state) { global $base_url, $is_https; @@ -127,10 +131,11 @@ function authorize_filetransfer_form($form, &$form_state) { } /** - * Generate the Form API array for the settings for a given connection backend. + * Generates the Form API array for a given connection backend's settings. * * @param $backend * The name of the backend (e.g. 'ftp', 'ssh', etc). + * * @return * Form API array of connection settings for the given backend. * @@ -151,7 +156,7 @@ function _authorize_filetransfer_connection_settings($backend) { } /** - * Recursively fill in the default settings on a file transfer connection form. + * Recursively sets the default settings on a file transfer connection form. * * The default settings for the file transfer connection forms are saved in * the database. The settings are stored as a nested array in the case of a @@ -165,8 +170,6 @@ function _authorize_filetransfer_connection_settings($backend) { * The key for our current form element, if any. * @param array $defaults * The default settings for the file transfer backend we're operating on. - * @return - * Nothing, this function just sets $element['#default_value'] if needed. */ function _authorize_filetransfer_connection_settings_set_defaults(&$element, $key, array $defaults) { // If we're operating on a form element which isn't a fieldset, and we have @@ -186,7 +189,7 @@ function _authorize_filetransfer_connection_settings_set_defaults(&$element, $ke } /** - * Validate callback for the filetransfer authorization form. + * Form validation handler for the authorize_filetransfer_form(). * * @see authorize_filetransfer_form() */ @@ -218,7 +221,7 @@ function authorize_filetransfer_form_validate($form, &$form_state) { } /** - * Submit callback when a file transfer is being authorized. + * Form submission handler for authorize_filetransfer_form(). * * @see authorize_filetransfer_form() */ @@ -280,7 +283,7 @@ function authorize_filetransfer_form_submit($form, &$form_state) { } /** - * Run the operation specified in $_SESSION['authorize_operation'] + * Runs the operation specified in $_SESSION['authorize_operation']. * * @param $filetransfer * The FileTransfer object to use for running the operation. @@ -298,12 +301,13 @@ function authorize_run_operation($filetransfer) { } /** - * Get a FileTransfer class for a specific transfer method and settings. + * Gets a FileTransfer class for a specific transfer method and settings. * * @param $backend * The FileTransfer backend to get the class for. * @param $settings * Array of settings for the FileTransfer. + * * @return * An instantiated FileTransfer object for the requested method and settings, * or FALSE if there was an error finding or instantiating it. diff --git a/includes/batch.inc b/includes/batch.inc index 513a8f9..3e41a7f 100644 --- a/includes/batch.inc +++ b/includes/batch.inc @@ -1,6 +1,5 @@ $this->name))->fetchObject(); if ($item) { @@ -29,7 +39,7 @@ class BatchQueue extends SystemQueue { } /** - * Retrieve all remaining items in the queue. + * Retrieves all remaining items in the queue. * * This is specific to Batch API and is not part of the DrupalQueueInterface, */ @@ -44,10 +54,21 @@ class BatchQueue extends SystemQueue { } /** - * Batch queue implementation used for non-progressive batches. + * Defines a batch queue for non-progressive batches. */ class BatchMemoryQueue extends MemoryQueue { + /** + * Overrides MemoryQueue::claimItem(). + * + * @param $lease_time + * (optional) How long the processing is expected to take in seconds. After + * this lease expires, the item will be reset and another consumer can + * claim the item. Defaults to 0. + * + * @return + * A batch item object, or FALSE if no item could be claimed. + */ public function claimItem($lease_time = 0) { if (!empty($this->queue)) { reset($this->queue); @@ -57,9 +78,9 @@ class BatchMemoryQueue extends MemoryQueue { } /** - * Retrieve all remaining items in the queue. + * Retrieves all remaining items in the queue. * - * This is specific to Batch API and is not part of the DrupalQueueInterface, + * This is specific to Batch API and is not part of the DrupalQueueInterface. */ public function getAllItems() { $result = array(); diff --git a/includes/bootstrap.inc b/includes/bootstrap.inc index a7257c7..d2613c6 100644 --- a/includes/bootstrap.inc +++ b/includes/bootstrap.inc @@ -42,12 +42,12 @@ define('CACHE_TEMPORARY', -1); * @{ * Logging severity levels as defined in RFC 3164. * - * The WATCHDOG_* constant definitions correspond to the logging severity levels - * defined in RFC 3164, section 4.1.1. PHP supplies predefined LOG_* constants - * for use in the syslog() function, but their values on Windows builds do not - * correspond to RFC 3164. The associated PHP bug report was closed with the - * comment, "And it's also not a bug, as Windows just have less log levels," - * and "So the behavior you're seeing is perfectly normal." + * The WATCHDOG_* constant definitions correspond to the logging severity + * levels defined in RFC 3164, section 4.1.1. PHP supplies predefined LOG_* + * constants for use in the syslog() function, but their values on Windows + * builds do not correspond to RFC 3164. The associated PHP bug report was + * closed with the comment, "And it's also not a bug, as Windows just have + * less log levels," and "So the behavior you're seeing is perfectly normal." * * @see http://www.faqs.org/rfcs/rfc3164.html * @see http://bugs.php.net/bug.php?id=18090 @@ -137,8 +137,7 @@ define('DRUPAL_BOOTSTRAP_PAGE_HEADER', 5); define('DRUPAL_BOOTSTRAP_LANGUAGE', 6); /** - * Final bootstrap phase: Drupal is fully loaded; validate and fix - * input data. + * Final bootstrap phase: Drupal is fully loaded; validate and fix input data. */ define('DRUPAL_BOOTSTRAP_FULL', 7); @@ -153,8 +152,9 @@ define('DRUPAL_ANONYMOUS_RID', 1); define('DRUPAL_AUTHENTICATED_RID', 2); /** - * The number of bytes in a kilobyte. For more information, visit - * http://en.wikipedia.org/wiki/Kilobyte. + * The number of bytes in a kilobyte. + * + * For more information, visit http://en.wikipedia.org/wiki/Kilobyte. */ define('DRUPAL_KILOBYTE', 1024); @@ -303,7 +303,7 @@ abstract class DrupalCacheArray implements ArrayAccess { protected $storage = array(); /** - * Constructor. + * Constructs a DrupalCacheArray object. * * @param $cid * The cid for the array being cached. @@ -319,10 +319,16 @@ abstract class DrupalCacheArray implements ArrayAccess { } } + /** + * Overrides ArrayAccess::offsetExists(). + */ public function offsetExists($offset) { return $this->offsetGet($offset) !== NULL; } + /** + * Overrides ArrayAccess::offsetGet(). + */ public function offsetGet($offset) { if (isset($this->storage[$offset]) || array_key_exists($offset, $this->storage)) { return $this->storage[$offset]; @@ -332,10 +338,16 @@ abstract class DrupalCacheArray implements ArrayAccess { } } + /** + * Overrides ArrayAccess::offsetSet(). + */ public function offsetSet($offset, $value) { $this->storage[$offset] = $value; } + /** + * Overrides ArrayAccess::offsetUnset(). + */ public function offsetUnset($offset) { unset($this->storage[$offset]); } @@ -375,7 +387,7 @@ abstract class DrupalCacheArray implements ArrayAccess { abstract protected function resolveCacheMiss($offset); /** - * Immediately write a value to the persistent cache. + * Writes a value to the persistent cache immediately. * * @param $cid * The cache ID. @@ -401,6 +413,9 @@ abstract class DrupalCacheArray implements ArrayAccess { } } + /** + * Destructs the DrupalCacheArray object. + */ public function __destruct() { $data = array(); foreach ($this->keysToPersist as $offset => $persist) { @@ -415,8 +430,10 @@ abstract class DrupalCacheArray implements ArrayAccess { } /** - * Start the timer with the specified name. If you start and stop the same - * timer multiple times, the measured intervals will be accumulated. + * Starts the timer with the specified name. + * + * If you start and stop the same timer multiple times, the measured intervals + * will be accumulated. * * @param $name * The name of the timer. @@ -429,7 +446,7 @@ function timer_start($name) { } /** - * Read the current timer value without stopping the timer. + * Reads the current timer value without stopping the timer. * * @param $name * The name of the timer. @@ -453,7 +470,7 @@ function timer_read($name) { } /** - * Stop the timer with the specified name. + * Stops the timer with the specified name. * * @param $name * The name of the timer. @@ -485,8 +502,9 @@ function timer_stop($name) { * * Finds a matching configuration directory by stripping the website's * hostname from left to right and pathname from right to left. The first - * configuration file found will be used and the remaining ones will be ignored. - * If no configuration file is found, return a default value '$confdir/default'. + * configuration file found will be used and the remaining ones will be + * ignored. If no configuration file is found, return a default value + * '$confdir/default'. * * With a site located at http://www.example.com:8080/mysite/test/, the file, * settings.php, is searched for in the following directories: @@ -602,7 +620,7 @@ function find_conf_path($http_host, $script_name, $require_settings = TRUE) { } /** - * Set appropriate server variables needed for command line scripts to work. + * Sets appropriate server variables needed for command line scripts to work. * * This function can be called by command line scripts before bootstrapping * Drupal, to ensure that the page loads with the desired server parameters. @@ -664,7 +682,7 @@ function drupal_override_server_variables($variables = array()) { } /** - * Initialize PHP environment. + * Initializes PHP environment. */ function drupal_environment_initialize() { if (!isset($_SERVER['HTTP_REFERER'])) { @@ -723,7 +741,7 @@ function drupal_environment_initialize() { } /** - * Validate that a hostname (for example $_SERVER['HTTP_HOST']) is safe. + * Validates that a hostname (for example $_SERVER['HTTP_HOST']) is safe. * * @return * TRUE if only containing valid characters, or FALSE otherwise. @@ -733,8 +751,7 @@ function drupal_valid_http_host($host) { } /** - * Loads the configuration and sets the base URL, cookie domain, and - * session name correctly. + * Sets the base URL, cookie domain, and session name from configuration. */ function drupal_settings_initialize() { global $base_url, $base_path, $base_root; @@ -820,9 +837,10 @@ function drupal_settings_initialize() { } /** - * Returns and optionally sets the filename for a system item (module, - * theme, etc.). The filename, whether provided, cached, or retrieved - * from the database, is only returned if the file exists. + * Returns and optionally sets the filename for a system resource. + * + * The filename, whether provided, cached, or retrieved from the database, is + * only returned if the file exists. * * This function plays a key role in allowing Drupal's resources (modules * and themes) to be located in different places depending on a site's @@ -919,11 +937,11 @@ function drupal_get_filename($type, $name, $filename = NULL) { } /** - * Load the persistent variable table. + * Loads the persistent variable table. * * The variable table is composed of values that have been saved in the table - * with variable_set() as well as those explicitly specified in the configuration - * file. + * with variable_set() as well as those explicitly specified in the + * configuration file. */ function variable_initialize($conf = array()) { // NOTE: caching the variables improves performance by 20% when serving @@ -1030,7 +1048,7 @@ function variable_del($name) { } /** - * Retrieve the current page from the cache. + * Retrieves the current page from the cache. * * Note: we do not serve cached pages to authenticated users, or to anonymous * users when $_SESSION is non-empty. $_SESSION may contain status messages @@ -1062,7 +1080,7 @@ function drupal_page_get_cache($check_only = FALSE) { } /** - * Determine the cacheability of the current page. + * Determines the cacheability of the current page. * * @param $allow_caching * Set to FALSE if you want to prevent this page to get cached. @@ -1081,7 +1099,7 @@ function drupal_page_is_cacheable($allow_caching = NULL) { } /** - * Invoke a bootstrap hook in all bootstrap modules that implement it. + * Invokes a bootstrap hook in all bootstrap modules that implement it. * * @param $hook * The name of the bootstrap hook to invoke. @@ -1103,8 +1121,9 @@ function bootstrap_invoke_all($hook) { } /** - * Includes a file with the provided type and name. This prevents - * including a theme, engine, module, etc., more than once. + * Includes a file with the provided type and name. + * + * This prevents including a theme, engine, module, etc., more than once. * * @param $type * The type of item to load (i.e. theme, theme_engine, module). @@ -1136,7 +1155,7 @@ function drupal_load($type, $name) { } /** - * Set an HTTP response header for the current page. + * Sets an HTTP response header for the current page. * * Note: When sending a Content-Type header, always include a 'charset' type, * too. This is necessary to avoid security bugs (e.g. UTF-7 XSS). @@ -1172,11 +1191,12 @@ function drupal_add_http_header($name, $value, $append = FALSE) { } /** - * Get the HTTP response headers for the current page. + * Gets the HTTP response headers for the current page. * * @param $name * An HTTP header name. If omitted, all headers are returned as name/value * pairs. If an array value is FALSE, the header has been unset. + * * @return * A string containing the header value, or FALSE if the header has been set, * or NULL if the header has not been set. @@ -1193,6 +1213,8 @@ function drupal_get_http_header($name = NULL) { } /** + * Sets the preferred name for the HTTP header. + * * Header names are case-insensitive, but for maximum compatibility they should * follow "common form" (see RFC 2617, section 4.2). */ @@ -1206,9 +1228,10 @@ function _drupal_set_preferred_header_name($name = NULL) { } /** - * Send the HTTP response headers previously set using drupal_add_http_header(). - * Add default headers, unless they have been replaced or unset using - * drupal_add_http_header(). + * Sends the HTTP response headers that were previously set, adding defaults. + * + * Headers are set in drupal_add_http_header(). Default headers are not set + * if they have been replaced or unset using drupal_add_http_header(). * * @param $default_headers * An array of headers as name/value pairs. @@ -1243,7 +1266,7 @@ function drupal_send_headers($default_headers = array(), $only_default = FALSE) } /** - * Set HTTP headers in preparation for a page response. + * Sets HTTP headers in preparation for a page response. * * Authenticated users are always given a 'no-cache' header, and will fetch a * fresh page on every request. This prevents authenticated users from seeing @@ -1262,9 +1285,9 @@ function drupal_send_headers($default_headers = array(), $only_default = FALSE) * header, the request only contains an If-Modified-Since header. The date will * be recent, because with authenticated users the Last-Modified header always * refers to the time of the request. If the user accesses Drupal via a proxy - * server, and the proxy already has a cached copy of the anonymous page with an - * older Last-Modified date, the proxy may respond with 304 Not Modified, making - * the client think that the anonymous and authenticated pageviews are + * server, and the proxy already has a cached copy of the anonymous page with + * an older Last-Modified date, the proxy may respond with 304 Not Modified, + * making the client think that the anonymous and authenticated pageviews are * identical. * * @see drupal_page_set_cache() @@ -1286,7 +1309,7 @@ function drupal_page_header() { } /** - * Set HTTP headers in preparation for a cached page response. + * Sets HTTP headers in preparation for a cached page response. * * The headers allow as much as possible in proxies and browsers without any * particular knowledge about the pages. Modules can override these headers @@ -1389,7 +1412,7 @@ function drupal_serve_page_from_cache(stdClass $cache) { } /** - * Define the critical hooks that force modules to always be loaded. + * Defines the critical hooks that force modules to always be loaded. */ function bootstrap_hooks() { return array('boot', 'exit', 'watchdog', 'language_init'); @@ -1506,7 +1529,7 @@ function t($string, array $args = array(), array $options = array()) { } /** - * Replace placeholders with sanitized values in a string. + * Replaces placeholders with sanitized values in a string. * * @param $string * A string containing placeholders. @@ -1548,7 +1571,7 @@ function format_string($string, array $args = array()) { } /** - * Encode special characters in a plain-text string for display as HTML. + * Encodes special characters in a plain-text string for display as HTML. * * Also validates strings as UTF-8 to prevent cross site scripting attacks on * Internet Explorer 6. @@ -1587,6 +1610,7 @@ function check_plain($text) { * * @param $text * The text to check. + * * @return * TRUE if the text is valid UTF-8, FALSE if not. */ @@ -1628,7 +1652,7 @@ function request_uri() { } /** - * Log an exception. + * Logs an exception. * * This is a wrapper function for watchdog() which automatically decodes an * exception. @@ -1669,7 +1693,7 @@ function watchdog_exception($type, Exception $exception, $message = NULL, $varia } /** - * Log a system message. + * Logs a system message. * * @param $type * The category to which this message belongs. Can be any string, but the @@ -1729,7 +1753,7 @@ function watchdog($type, $message, $variables = array(), $severity = WATCHDOG_NO } /** - * Set a message which reflects the status of the performed operation. + * Sets a message which reflects the status of the performed operation. * * If the function is called with no arguments, this function returns all set * messages without clearing them. @@ -1765,12 +1789,13 @@ function drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE) { } /** - * Return all messages that have been set. + * Returns all messages that have been set. * * @param $type * (optional) Only return messages of this type. * @param $clear_queue * (optional) Set to FALSE if you do not want to clear the messages queue + * * @return * An associative array, the key is the message type, the value an array * of messages. If the $type parameter is passed, you get only that type, @@ -1798,7 +1823,9 @@ function drupal_get_messages($type = NULL, $clear_queue = TRUE) { } /** - * Get the title of the current page, for display on the page and in the title bar. + * Gets the title of the current page. + * + * The title is displayed on the page and in the title bar. * * @return * The current page's title. @@ -1815,7 +1842,9 @@ function drupal_get_title() { } /** - * Set the title of the current page, for display on the page and in the title bar. + * Sets the title of the current page. + * + * The title is displayed on the page and in the title bar. * * @param $title * Optional string value to assign to the page title; or if set to NULL @@ -1840,7 +1869,7 @@ function drupal_set_title($title = NULL, $output = CHECK_PLAIN) { } /** - * Check to see if an IP address has been blocked. + * Checks to see if an IP address has been blocked. * * Blocked IP addresses are stored in the database by default. However for * performance reasons we allow an override in settings.php. This allows us @@ -1849,6 +1878,7 @@ function drupal_set_title($title = NULL, $output = CHECK_PLAIN) { * * @param $ip * IP address to check. + * * @return bool * TRUE if access is denied, FALSE if access is allowed. */ @@ -1874,7 +1904,7 @@ function drupal_is_denied($ip) { } /** - * Handle denied users. + * Handles denied users. * * @param $ip * IP address to check. Prints a message and exits if access is denied. @@ -1893,7 +1923,8 @@ function drupal_block_denied($ip) { * * This function is better than simply calling mt_rand() or any other built-in * PHP function because it can return a long string of bytes (compared to < 4 - * bytes normally from mt_rand()) and uses the best available pseudo-random source. + * bytes normally from mt_rand()) and uses the best available pseudo-random + * source. * * @param $count * The number of characters (bytes) to return in the string. @@ -1940,7 +1971,7 @@ function drupal_random_bytes($count) { } /** - * Calculate a base-64 encoded, URL-safe sha-256 hmac. + * Calculates a base-64 encoded, URL-safe sha-256 hmac. * * @param $data * String to be validated with the hmac. @@ -1958,7 +1989,7 @@ function drupal_hmac_base64($data, $key) { } /** - * Calculate a base-64 encoded, URL-safe sha-256 hash. + * Calculates a base-64 encoded, URL-safe sha-256 hash. * * @param $data * String to be hashed. @@ -2062,20 +2093,23 @@ function drupal_anonymous_user() { } /** - * A string describing a phase of Drupal to load. Each phase adds to the - * previous one, so invoking a later phase automatically runs the earlier - * phases too. The most important usage is that if you want to access the - * Drupal database from a script without loading anything else, you can - * include bootstrap.inc, and call drupal_bootstrap(DRUPAL_BOOTSTRAP_DATABASE). + * Ensures Drupal is bootstrapped to the specified phase. + * + * The bootstrap phase is a string describing a phase of Drupal to load. Each + * phase adds to the previous one, so invoking a later phase automatically + * runs the earlier phases as well. The most important usage is that if you + * want to access the Drupal database from a script without loading anything + * else, you can include bootstrap.inc, and call + * drupal_bootstrap(DRUPAL_BOOTSTRAP_DATABASE). * * @param $phase * A constant. Allowed values are the DRUPAL_BOOTSTRAP_* constants. * @param $new_phase * A boolean, set to FALSE if calling drupal_bootstrap from inside a * function called from drupal_bootstrap (recursion). + * * @return * The most recently completed phase. - * */ function drupal_bootstrap($phase = NULL, $new_phase = TRUE) { // Not drupal_static(), because does not depend on any run-time information. @@ -2154,7 +2188,7 @@ function drupal_bootstrap($phase = NULL, $new_phase = TRUE) { } /** - * Return the time zone of the current user. + * Returns the time zone of the current user. */ function drupal_get_user_timezone() { global $user; @@ -2169,7 +2203,7 @@ function drupal_get_user_timezone() { } /** - * Custom PHP error handler. + * Provides custom PHP error handling. * * @param $error_level * The level of the error raised. @@ -2180,7 +2214,8 @@ function drupal_get_user_timezone() { * @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($error_level, $message, $filename, $line, $context) { require_once DRUPAL_ROOT . '/includes/errors.inc'; @@ -2188,7 +2223,7 @@ function _drupal_error_handler($error_level, $message, $filename, $line, $contex } /** - * Custom PHP exception handler. + * Provides custom PHP exception handling. * * Uncaught exceptions are those not enclosed in a try/catch block. They are * always fatal: the execution of the script will stop as soon as the exception @@ -2216,7 +2251,7 @@ function _drupal_exception_handler($exception) { } /** - * Bootstrap configuration: Setup script environment and load settings.php. + * Sets up script environment and loads settings.php. */ function _drupal_bootstrap_configuration() { // Set the Drupal custom error handler. @@ -2231,7 +2266,7 @@ function _drupal_bootstrap_configuration() { } /** - * Bootstrap page cache: Try to serve a page from cache. + * Attempts to serve a page from cache. */ function _drupal_bootstrap_page_cache() { global $user; @@ -2287,7 +2322,7 @@ function _drupal_bootstrap_page_cache() { } /** - * Bootstrap database: Initialize database system and register autoload functions. + * Initializes database system and registers autoload functions. */ function _drupal_bootstrap_database() { // Redirect the user to the installation script if Drupal has not been @@ -2339,7 +2374,7 @@ function _drupal_bootstrap_database() { } /** - * Bootstrap variables: Load system variables and all enabled bootstrap modules. + * Loads system variables and all enabled bootstrap modules. */ function _drupal_bootstrap_variables() { global $conf; @@ -2356,7 +2391,7 @@ function _drupal_bootstrap_variables() { } /** - * Bootstrap page header: Invoke hook_boot(), initialize locking system, and send default HTTP headers. + * Invokes hook_boot(), initializes locking system, and sends HTTP headers. */ function _drupal_bootstrap_page_header() { bootstrap_invoke_all('boot'); @@ -2379,8 +2414,7 @@ function drupal_get_bootstrap_phase() { } /** - * Checks the current User-Agent string to see if this is an internal request - * from SimpleTest. If so, returns the test prefix for this test. + * Returns the test prefix if this is an internal request from SimpleTest. * * @return * Either the simpletest prefix (the string "simpletest" followed by any @@ -2416,7 +2450,7 @@ function drupal_valid_test_ua() { } /** - * Generate a user agent string with a HMAC and timestamp for simpletest. + * Generates a user agent string with a HMAC and timestamp for simpletest. */ function drupal_generate_test_ua($prefix) { global $drupal_hash_salt; @@ -2454,9 +2488,10 @@ function drupal_maintenance_theme() { * simple 404 page and exit. * * This function is called from drupal_deliver_html_page() at the time when a - * a normal 404 page is generated, but it can also optionally be called directly - * from settings.php to prevent a Drupal bootstrap on these pages. See - * documentation in settings.php for the benefits and drawbacks of using this. + * a normal 404 page is generated, but it can also optionally be called + * directly from settings.php to prevent a Drupal bootstrap on these pages. + * See documentation in settings.php for the benefits and drawbacks of using + * this. * * Paths to dynamically-generated content, such as image styles, should also be * accounted for in this function. @@ -2476,7 +2511,7 @@ function drupal_fast_404() { } /** - * Return TRUE if a Drupal installation is currently being attempted. + * Returns TRUE if a Drupal installation is currently being attempted. */ function drupal_installation_attempted() { return defined('MAINTENANCE_MODE') && MAINTENANCE_MODE == 'install'; @@ -2519,7 +2554,7 @@ function get_t() { } /** - * Initialize all the defined language types. + * Initializes all the defined language types. */ function drupal_language_initialize() { global $language; @@ -2548,7 +2583,7 @@ function drupal_language_initialize() { } /** - * The built-in language types. + * Returns a list of the built-in language types. * * @return * An array of key-values pairs where the key is the language type and the @@ -2563,7 +2598,7 @@ function drupal_language_types() { } /** - * Return true if there is more than one language enabled. + * Returns TRUE if there is more than one language enabled. */ function drupal_multilingual() { // The "language_count" variable stores the number of enabled languages to @@ -2573,7 +2608,7 @@ function drupal_multilingual() { } /** - * Return an array of the available language types. + * Returns an array of the available language types. */ function language_types() { return array_keys(variable_get('language_types', drupal_language_types())); @@ -2636,7 +2671,7 @@ function language_list($field = 'language') { } /** - * Default language used on the site. + * Returns the default language used on the site. * * @return * A language object. @@ -2669,7 +2704,8 @@ function language_default() { * base_path() returns "/drupalfolder/". * - http://example.com/path/alias (which is a path alias for node/306) returns * "path/alias" as opposed to the internal path. - * - http://example.com/index.php returns an empty string (meaning: front page). + * - http://example.com/index.php returns an empty string (meaning: the front + * page). * - http://example.com/index.php?page=1 returns an empty string. * * @return @@ -2720,16 +2756,16 @@ function request_path() { } /** - * Return a component of the current Drupal path. + * Returns a component of the current Drupal path. * * When viewing a page at the path "admin/structure/types", for example, arg(0) * returns "admin", arg(1) returns "structure", and arg(2) returns "types". * - * Avoid use of this function where possible, as resulting code is hard to read. - * In menu callback functions, attempt to use named arguments. See the explanation - * in menu.inc for how to construct callbacks that take arguments. When attempting - * to use this function to load an element from the current path, e.g. loading the - * node on a node page, please use menu_get_object() instead. + * Avoid use of this function where possible, as resulting code is hard to + * read. In menu callback functions, attempt to use named arguments. See the + * explanation in menu.inc for how to construct callbacks that take arguments. + * When attempting to use this function to load an element from the current + * path, e.g. loading the node on a node page, use menu_get_object() instead. * * @param $index * The index of the component, where each component is separated by a '/' @@ -2769,6 +2805,8 @@ function arg($index = NULL, $path = NULL) { } /** + * Returns the IP address of the client machine. + * * If Drupal is behind a reverse proxy, we use the X-Forwarded-For header * instead of $_SERVER['REMOTE_ADDR'], which would be the IP address of * the proxy server, and not the client's. The actual header name can be @@ -2818,7 +2856,7 @@ function ip_address() { */ /** - * Get the schema definition of a table, or the whole database schema. + * Gets the schema definition of a table, or the whole database schema. * * The returned schema will include any modifications made by any * module that implements hook_schema_alter(). @@ -2854,11 +2892,23 @@ function drupal_get_schema($table = NULL, $rebuild = FALSE) { */ class SchemaCache extends DrupalCacheArray { + /** + * Constructs a SchemaCache object. + */ public function __construct() { // Cache by request method. parent::__construct('schema:runtime:' . ($_SERVER['REQUEST_METHOD'] == 'GET'), 'cache'); } + /** + * Resolves a cache miss. + * + * @param $offset + * The offset that was requested. + * + * @return + * The value of the offset, or NULL if no value was found. + */ protected function resolveCacheMiss($offset) { $complete_schema = drupal_get_complete_schema(); $value = isset($complete_schema[$offset]) ? $complete_schema[$offset] : NULL; @@ -2869,7 +2919,7 @@ class SchemaCache extends DrupalCacheArray { } /** - * Get the whole database schema. + * Gets the whole database schema. * * The returned schema will include any modifications made by any * module that implements hook_schema_alter(). @@ -2939,13 +2989,14 @@ function drupal_get_complete_schema($rebuild = FALSE) { */ /** - * Confirm that an interface is available. + * Confirms that an interface is available. * * This function is rarely called directly. Instead, it is registered as an * spl_autoload() handler, and PHP calls it for us when necessary. * * @param $interface * The name of the interface to check or load. + * * @return * TRUE if the interface is currently available, FALSE otherwise. */ @@ -2954,13 +3005,14 @@ function drupal_autoload_interface($interface) { } /** - * Confirm that a class is available. + * Confirms that a class is available. * * This function is rarely called directly. Instead, it is registered as an * spl_autoload() handler, and PHP calls it for us when necessary. * * @param $class * The name of the class to check or load. + * * @return * TRUE if the class is currently available, FALSE otherwise. */ @@ -2969,7 +3021,7 @@ function drupal_autoload_class($class) { } /** - * Helper to check for a resource in the registry. + * Checks for a resource in the registry. * * @param $type * The type of resource we are looking up, or one of the constants @@ -2978,6 +3030,7 @@ function drupal_autoload_class($class) { * @param $name * The name of the resource, or NULL if either of the REGISTRY_* constants * is passed in. + * * @return * TRUE if the resource was found, FALSE if not. * NULL if either of the REGISTRY_* constants is passed in as $type. @@ -3049,7 +3102,7 @@ function _registry_check_code($type, $name = NULL) { } /** - * Rescan all enabled modules and rebuild the registry. + * Rescans all enabled modules and rebuilds the registry. * * Rescans all code in modules or includes directories, storing the location of * each interface or class in the database. @@ -3060,7 +3113,7 @@ function registry_rebuild() { } /** - * Update the registry based on the latest files listed in the database. + * Updates the registry based on the latest files listed in the database. * * This function should be used when system_rebuild_module_data() does not need * to be called, because it is already known that the list of files in the @@ -3078,7 +3131,7 @@ function registry_update() { */ /** - * Central static variable storage. + * Provides central static variable storage. * * All functions requiring a static variable to persist or cache data within * a single page request are encouraged to use this function unless it is @@ -3145,8 +3198,8 @@ function registry_update() { * counts. These functions can use a more cumbersome, but faster variant of * calling drupal_static(). It works by storing the reference returned by * drupal_static() in the calling function's own static variable, thereby - * removing the need to call drupal_static() for each iteration of the function. - * Conceptually, it replaces: + * removing the need to call drupal_static() for each iteration of the + * function. Conceptually, it replaces: * @code * $foo = &drupal_static(__FUNCTION__); * @endcode @@ -3155,9 +3208,9 @@ function registry_update() { * // Unfortunately, this does not work. * static $foo = &drupal_static(__FUNCTION__); * @endcode - * However, the above line of code does not work, because PHP only allows static - * variables to be initializied by literal values, and does not allow static - * variables to be assigned to references. + * However, the above line of code does not work, because PHP only allows + * static variables to be initializied by literal values, and does not allow + * static variables to be assigned to references. * - http://php.net/manual/en/language.variables.scope.php#language.variables.scope.static * - http://php.net/manual/en/language.variables.scope.php#language.variables.scope.references * The example below shows the syntax needed to work around both limitations. @@ -3177,16 +3230,16 @@ function registry_update() { * @endcode * * @param $name - * Globally unique name for the variable. For a function with only one static, - * variable, the function name (e.g. via the PHP magic __FUNCTION__ constant) - * is recommended. For a function with multiple static variables add a - * distinguishing suffix to the function name for each one. + * Globally unique name for the variable. For a function with only one + * static variable, the function name (e.g. via the PHP magic __FUNCTION__ + * constant) is recommended. For a function with multiple static variables, + * add a distinguishing suffix to the function name for each one. * @param $default_value * Optional default value. * @param $reset - * TRUE to reset a specific named variable, or all variables if $name is NULL. - * Resetting every variable should only be used, for example, for running - * unit tests with a clean environment. Should be used only though via + * TRUE to reset a specific named variable, or all variables if $name is + * NULL. Resetting every variable should only be used, for example, for + * running unit tests with a clean environment. Should be used only via * function drupal_static_reset() and the return value should not be used in * this case. * @@ -3229,7 +3282,7 @@ function &drupal_static($name, $default_value = NULL, $reset = FALSE) { } /** - * Reset one or all centrally stored static variable(s). + * Resets one or all centrally stored static variable(s). * * @param $name * Name of the static variable to reset. Omit to reset all variables. @@ -3239,7 +3292,7 @@ function drupal_static_reset($name = NULL) { } /** - * Detect whether the current script is running in a command-line environment. + * Detects whether the current script is running in a command-line environment. */ function drupal_is_cli() { return (!isset($_SERVER['SERVER_SOFTWARE']) && (php_sapi_name() == 'cli' || (is_numeric($_SERVER['argc']) && $_SERVER['argc'] > 0))); @@ -3247,7 +3300,8 @@ function drupal_is_cli() { /** * Formats text for emphasized display in a placeholder inside a sentence. - * Used automatically by t(). + * + * Used automatically by format_string(). * * @param $text * The text to format (plain-text). @@ -3260,7 +3314,7 @@ function drupal_placeholder($text) { } /** - * Register a function for execution on shutdown. + * Registers a function for execution on shutdown. * * Wrapper for register_shutdown_function() that catches thrown exceptions to * avoid "Exception thrown without a stack frame in Unknown". @@ -3295,7 +3349,7 @@ function &drupal_register_shutdown_function($callback = NULL) { } /** - * Internal function used to execute registered shutdown functions. + * Executes registered shutdown functions. */ function _drupal_shutdown_function() { $callbacks = &drupal_register_shutdown_function(); diff --git a/includes/cache-install.inc b/includes/cache-install.inc index 8bcf8b7..4c2e511 100644 --- a/includes/cache-install.inc +++ b/includes/cache-install.inc @@ -15,17 +15,30 @@ * normal operations would have a negative impact on performance. */ class DrupalFakeCache extends DrupalDatabaseCache implements DrupalCacheInterface { + + /** + * Overrides DrupalDatabaseCache::get(). + */ function get($cid) { return FALSE; } + /** + * Overrides DrupalDatabaseCache::getMultiple(). + */ function getMultiple(&$cids) { return array(); } + /** + * Overrides DrupalDatabaseCache::set(). + */ function set($cid, $data, $expire = CACHE_PERMANENT) { } + /** + * Overrides DrupalDatabaseCache::deletePrefix(). + */ function deletePrefix($cid) { try { if (class_exists('Database')) { @@ -36,6 +49,9 @@ class DrupalFakeCache extends DrupalDatabaseCache implements DrupalCacheInterfac } } + /** + * Overrides DrupalDatabaseCache::clear(). + */ function clear($cid = NULL, $wildcard = FALSE) { // If there is a database cache, attempt to clear it whenever possible. The // reason for doing this is that the database cache can accumulate data @@ -62,6 +78,9 @@ class DrupalFakeCache extends DrupalDatabaseCache implements DrupalCacheInterfac } } + /** + * Overrides DrupalDatabaseCache::isEmpty(). + */ function isEmpty() { return TRUE; } diff --git a/includes/cache.inc b/includes/cache.inc index fcf3e5e..0bd074c 100644 --- a/includes/cache.inc +++ b/includes/cache.inc @@ -1,19 +1,25 @@ bin = $bin; } + /** + * Overrides DrupalCacheInterface::get(). + */ function get($cid) { $cids = array($cid); $cache = $this->getMultiple($cids); return reset($cache); } + /** + * Overrides DrupalCacheInterface::getMultiple(). + */ function getMultiple(&$cids) { try { // Garbage collection necessary when enforcing a minimum cache lifetime. @@ -446,13 +504,14 @@ class DrupalDatabaseCache implements DrupalCacheInterface { } /** - * Prepare a cached item. + * Prepares a cached item. * * Checks that items are either permanent or did not expire, and unserializes * data as appropriate. * * @param $cache * An item loaded from cache_get() or cache_get_multiple(). + * * @return * The item with data unserialized as appropriate or FALSE if there is no * valid item to load. @@ -481,6 +540,9 @@ class DrupalDatabaseCache implements DrupalCacheInterface { return $cache; } + /** + * Overrides DrupalCacheInterface::set(). + */ function set($cid, $data, $expire = CACHE_PERMANENT) { $fields = array( 'serialized' => 0, @@ -507,12 +569,18 @@ class DrupalDatabaseCache implements DrupalCacheInterface { } } + /** + * Overrides DrupalCacheInterface::delete(). + */ function delete($cid) { db_delete($this->bin) ->condition('cid', $cid) ->execute(); } + /** + * Overrides DrupalCacheInterface::deleteMultiple(). + */ function deleteMultiple(Array $cids) { // Delete in chunks when a large array is passed. do { @@ -523,16 +591,25 @@ class DrupalDatabaseCache implements DrupalCacheInterface { while (count($cids)); } + /** + * Overrides DrupalCacheInterface::deletePrefix(). + */ function deletePrefix($prefix) { db_delete($this->bin) ->condition('cid', db_like($prefix) . '%', 'LIKE') ->execute(); } + /** + * Overrides DrupalCacheInterface::flush(). + */ function flush() { db_truncate($this->bin)->execute(); } + /** + * Overrides DrupalCacheInterface::expire(). + */ function expire() { if (variable_get('cache_lifetime', 0)) { // We store the time in the current user's $user->cache variable which @@ -565,6 +642,9 @@ class DrupalDatabaseCache implements DrupalCacheInterface { } } + /** + * Overrides DrupalCacheInterface::garbageCollection(). + */ function garbageCollection() { global $user; @@ -582,6 +662,9 @@ class DrupalDatabaseCache implements DrupalCacheInterface { } } + /** + * Overrides DrupalCacheInterface::clear(). + */ function clear($cid = NULL, $wildcard = FALSE) { global $user; @@ -606,6 +689,9 @@ class DrupalDatabaseCache implements DrupalCacheInterface { } } + /** + * Overrides DrupalCacheInterface::isEmpty(). + */ function isEmpty() { $this->garbageCollection(); $query = db_select($this->bin); diff --git a/includes/common.inc b/includes/common.inc index 5f7cdb8..b91c50d 100644 --- a/includes/common.inc +++ b/includes/common.inc @@ -19,10 +19,10 @@ * For example, for improved or more secure UTF8-handling, or RFC-compliant * handling of URLs in Drupal. * - * For ease of use and memorizing, all these wrapper functions use the same name - * as the original PHP function, but prefixed with "drupal_". Beware, however, - * that not all wrapper functions support the same arguments as the original - * functions. + * For ease of use and memorizing, all these wrapper functions use the same + * name as the original PHP function, but prefixed with "drupal_". Beware, + * however, that not all wrapper functions support the same arguments as the + * original functions. * * You should always use these wrapper functions in your code. * @@ -70,8 +70,9 @@ define('CSS_DEFAULT', 0); define('CSS_THEME', 100); /** - * The default group for JavaScript libraries, settings or jQuery plugins added - * to the page. + * The default group for JavaScript libraries and settings added to the page. + * + * Includes jQuery plugins. */ define('JS_LIBRARY', -100); @@ -86,8 +87,9 @@ define('JS_DEFAULT', 0); define('JS_THEME', 100); /** - * Error code indicating that the request made by drupal_http_request() exceeded - * the specified timeout. + * Error code indicating that the request exceeded the specified timeout. + * + * @see drupal_http_request() */ define('HTTP_REQUEST_TIMEOUT', -1); @@ -110,7 +112,9 @@ define('HTTP_REQUEST_TIMEOUT', -1); */ /** - * The block should not get cached. This setting should be used: + * The block should not get cached. + * + * This setting should be used: * - for simple blocks (notably those that do not perform any db query), * where querying the db cache would be more expensive than directly generating * the content. @@ -119,22 +123,25 @@ define('HTTP_REQUEST_TIMEOUT', -1); define('DRUPAL_NO_CACHE', -1); /** - * The block is handling its own caching in its hook_block_view(). From the - * perspective of the block cache system, this is equivalent to DRUPAL_NO_CACHE. - * Useful when time based expiration is needed or a site uses a node access - * which invalidates standard block cache. + * The block is handling its own caching in its hook_block_view(). + * + * From the perspective of the block cache system, this is equivalent to + * DRUPAL_NO_CACHE. Useful when time based expiration is needed or a site uses + * a node access which invalidates standard block cache. */ define('DRUPAL_CACHE_CUSTOM', -2); /** - * The block or element can change depending on the roles the user viewing the - * page belongs to. This is the default setting for blocks, used when the block - * does not specify anything. + * The block or element can change depending on the user's roles. + * + * This is the default setting for blocks, used when the block does not + * specify anything. */ define('DRUPAL_CACHE_PER_ROLE', 0x0001); /** - * The block or element can change depending on the user viewing the page. + * The block or element can change depending on the user. + * * This setting can be resource-consuming for sites with large number of users, * and thus should only be used when DRUPAL_CACHE_PER_ROLE is not sufficient. */ @@ -146,12 +153,12 @@ define('DRUPAL_CACHE_PER_USER', 0x0002); define('DRUPAL_CACHE_PER_PAGE', 0x0004); /** - * The block or element is the same for every user on every page where it is visible. + * The block or element is the same for every user and page that it is visible. */ define('DRUPAL_CACHE_GLOBAL', 0x0008); /** - * Add content to a specified region. + * Adds content to a specified region. * * @param $region * Page region the content is added to. @@ -168,7 +175,7 @@ function drupal_add_region_content($region = NULL, $data = NULL) { } /** - * Get assigned content for a given region. + * Gets assigned content for a given region. * * @param $region * A specified region to fetch content for. If NULL, all regions will be @@ -194,13 +201,13 @@ function drupal_get_region_content($region = NULL, $delimiter = ' ') { } /** - * Get the name of the currently active install profile. + * Gets the name of the currently active install profile. * * When this function is called during Drupal's initial installation process, * the name of the profile that's about to be installed is stored in the global * installation state. At all other times, the standard Drupal systems variable - * table contains the name of the current profile, and we can call variable_get() - * to determine what one is active. + * table contains the name of the current profile, and we can call + * variable_get() to determine what one is active. * * @return $profile * The name of the install profile. @@ -220,11 +227,11 @@ function drupal_get_profile() { /** - * Set the breadcrumb trail for the current page. + * Sets the breadcrumb trail for the current page. * * @param $breadcrumb - * Array of links, starting with "home" and proceeding up to but not including - * the current page. + * Array of links, starting with "home" and proceeding up to but not + * including the current page. */ function drupal_set_breadcrumb($breadcrumb = NULL) { $stored_breadcrumb = &drupal_static(__FUNCTION__); @@ -236,7 +243,7 @@ function drupal_set_breadcrumb($breadcrumb = NULL) { } /** - * Get the breadcrumb trail for the current page. + * Gets the breadcrumb trail for the current page. */ function drupal_get_breadcrumb() { $breadcrumb = drupal_set_breadcrumb(); @@ -249,8 +256,7 @@ function drupal_get_breadcrumb() { } /** - * Returns a string containing RDF namespace declarations for use in XML and - * XHTML output. + * Returns a string of RDF namespace declarations for XML and XHTML output. */ function drupal_get_rdf_namespaces() { $xml_rdf_namespaces = array(); @@ -265,7 +271,7 @@ function drupal_get_rdf_namespaces() { } /** - * Add output to the head tag of the HTML page. + * Adds output to the head tag of the HTML page. * * This function can be called as long the headers aren't sent. Pass no * arguments (or NULL for both) to retrieve the currently stored elements. @@ -333,7 +339,7 @@ function _drupal_default_html_head() { } /** - * Retrieve output to be displayed in the HEAD tag of the HTML page. + * Retrieves output to be displayed in the HEAD tag of the HTML page. */ function drupal_get_html_head() { $elements = drupal_add_html_head(); @@ -342,7 +348,7 @@ function drupal_get_html_head() { } /** - * Add a feed URL for the current page. + * Adds a feed URL for the current page. * * This function can be called as long the HTML header hasn't been sent. * @@ -370,7 +376,7 @@ function drupal_add_feed($url = NULL, $title = '') { } /** - * Get the feed URLs for the current page. + * Gets the feed URLs for the current page. * * @param $delimiter * A delimiter to split feeds by. @@ -387,7 +393,7 @@ function drupal_get_feeds($delimiter = "\n") { */ /** - * Process a URL query parameter array to remove unwanted elements. + * Processes a URL query parameter array to remove unwanted elements. * * @param $query * (optional) An array to be processed. Defaults to $_GET. @@ -432,7 +438,7 @@ function drupal_get_query_parameters(array $query = NULL, array $exclude = array } /** - * Split an URL-encoded query string into an array. + * Splits a URL-encoded query string into an array. * * @param $query * The query string to split. @@ -452,10 +458,10 @@ function drupal_get_query_array($query) { } /** - * Parse an array into a valid, rawurlencoded query string. + * Parses an array into a valid, rawurlencoded query string. * - * This differs from http_build_query() as we need to rawurlencode() (instead of - * urlencode()) all query parameters. + * This differs from http_build_query() as we need to rawurlencode() + * (instead of urlencode()) all query parameters. * * @param $query * The query parameter array to be processed, e.g. $_GET. @@ -493,7 +499,7 @@ function drupal_http_build_query(array $query, $parent = '') { } /** - * Prepare a 'destination' URL query parameter for use in combination with drupal_goto(). + * Prepares a 'destination' URL query parameter for use with drupal_goto(). * * Used to direct the user back to the referring page after completing a form. * By default the current URL is returned. If a destination exists in the @@ -524,7 +530,7 @@ function drupal_get_destination() { } /** - * Wrapper around parse_url() to parse a system URL string into an associative array, suitable for url(). + * Parses a system URL string into an associative array suitable for url(). * * This function should only be used for URLs that have been generated by the * system, resp. url(). It should not be used for URLs that come from external @@ -548,8 +554,8 @@ function drupal_get_destination() { * * @return * An associative array containing the keys: - * - 'path': The path of the URL. If the given $url is external, this includes - * the scheme and host. + * - 'path': The path of the URL. If the given $url is external, this + * includes the scheme and host. * - 'query': An array of query parameters of $url, if existent. * - 'fragment': The fragment of $url, if existent. * @@ -610,8 +616,8 @@ function drupal_parse_url($url) { * * For aesthetic reasons slashes are not escaped. * - * Note that url() takes care of calling this function, so a path passed to that - * function should not be encoded in advance. + * Note that url() takes care of calling this function, so a path passed to + * that function should not be encoded in advance. * * @param $path * The Drupal path to encode. @@ -621,7 +627,7 @@ function drupal_encode_path($path) { } /** - * Send the user to a different Drupal page. + * Sends the user to a different Drupal page. * * This issues an on-site HTTP redirect. The function makes sure the redirected * URL is formatted correctly. @@ -687,19 +693,20 @@ function drupal_goto($path = '', array $options = array(), $http_response_code = } /** - * Deliver a "site is under maintenance" message to the browser. + * Delivers a "site is under maintenance" message to the browser. * * Page callback functions wanting to report a "site offline" message should * return MENU_SITE_OFFLINE instead of calling drupal_site_offline(). However, * functions that are invoked in contexts where that return value might not - * bubble up to menu_execute_active_handler() should call drupal_site_offline(). + * bubble up to menu_execute_active_handler() should call + * drupal_site_offline(). */ function drupal_site_offline() { drupal_deliver_page(MENU_SITE_OFFLINE); } /** - * Deliver a "page not found" error to the browser. + * Delivers a "page not found" error to the browser. * * Page callback functions wanting to report a "page not found" message should * return MENU_NOT_FOUND instead of calling drupal_not_found(). However, @@ -711,19 +718,20 @@ function drupal_not_found() { } /** - * Deliver a "access denied" error to the browser. + * Delivers a "access denied" error to the browser. * * Page callback functions wanting to report an "access denied" message should - * return MENU_ACCESS_DENIED instead of calling drupal_access_denied(). However, - * functions that are invoked in contexts where that return value might not - * bubble up to menu_execute_active_handler() should call drupal_access_denied(). + * return MENU_ACCESS_DENIED instead of calling drupal_access_denied(). + * However, functions that are invoked in contexts where that return value + * might not bubble up to menu_execute_active_handler() should call + * drupal_access_denied(). */ function drupal_access_denied() { drupal_deliver_page(MENU_ACCESS_DENIED); } /** - * Perform an HTTP request. + * Performs an HTTP request. * * This is a flexible and powerful HTTP client implementation. Correctly * handles GET, POST, PUT or any other HTTP requests. Handles redirects. @@ -732,7 +740,8 @@ function drupal_access_denied() { * A string containing a fully qualified URI. * @param array $options * (optional) An array that can have one or more of the following elements: - * - headers: An array containing request headers to send as name/value pairs. + * - headers: An array containing request headers to send as name/value + * pairs. * - method: A string containing the request method. Defaults to 'GET'. * - data: A string containing the request body, formatted as * 'param=value¶m=value&...'. Defaults to NULL. @@ -1024,6 +1033,16 @@ function drupal_http_request($url, array $options = array()) { * @} End of "HTTP handling". */ +/** + * Callback: Strips slashes from a string or array of strings. + * + * Used with array_walk(). + * + * @param $item + * An individual string or array of strings from superglobals. + * + * @see fix_gpc_magic(). + */ function _fix_gpc_magic(&$item) { if (is_array($item)) { array_walk($item, '_fix_gpc_magic'); @@ -1034,11 +1053,13 @@ function _fix_gpc_magic(&$item) { } /** - * Helper function to strip slashes from $_FILES skipping over the tmp_name keys - * since PHP generates single backslashes for file paths on Windows systems. + * Callback: Strips slashes from $_FILES items. + * + * The tmp_name key is skipped keys since PHP generates single backslashes for + * file paths on Windows systems. * - * tmp_name does not have backslashes added see - * http://php.net/manual/en/features.file-upload.php#42280 + * @see fix_gpc_magic() + * @see: http://php.net/manual/en/features.file-upload.php#42280 */ function _fix_gpc_magic_files(&$item, $key) { if ($key != 'tmp_name') { @@ -1052,7 +1073,10 @@ function _fix_gpc_magic_files(&$item, $key) { } /** - * Fix double-escaping problems caused by "magic quotes" in some PHP installations. + * Fixes double-escaping caused by "magic quotes" in some PHP installations. + * + * @see _fix_gpc_magic() + * @see _fix_gpc_magic_files() */ function fix_gpc_magic() { static $fixed = FALSE; @@ -1073,12 +1097,13 @@ function fix_gpc_magic() { */ /** - * Verify the syntax of the given e-mail address. + * Verifies the syntax of the given e-mail address. * * Empty e-mail addresses are allowed. See RFC 2822 for details. * * @param $mail * A string containing an e-mail address. + * * @return * TRUE if the address is in a valid format. */ @@ -1087,7 +1112,7 @@ function valid_email_address($mail) { } /** - * Verify the syntax of the given URL. + * Verifies the syntax of the given URL. * * This function should only be used on actual URLs. It should not be used for * Drupal menu paths, which can contain arbitrary characters. @@ -1096,6 +1121,7 @@ function valid_email_address($mail) { * The URL to verify. * @param $absolute * Whether the URL is absolute (beginning with a scheme such as "http:"). + * * @return * TRUE if the URL is in a valid format. */ @@ -1128,15 +1154,15 @@ function valid_url($url, $absolute = FALSE) { */ /** - * Register an event for the current visitor to the flood control mechanism. + * Registers an event for the current visitor to the flood control mechanism. * * @param $name * The name of an event. * @param $window * Optional number of seconds before this event expires. Defaults to 3600 (1 * hour). Typically uses the same value as the flood_is_allowed() $window - * parameter. Expired events are purged on cron run to prevent the flood table - * from growing indefinitely. + * parameter. Expired events are purged on cron run to prevent the flood + * table from growing indefinitely. * @param $identifier * Optional identifier (defaults to the current user's IP address). */ @@ -1155,7 +1181,7 @@ function flood_register_event($name, $window = 3600, $identifier = NULL) { } /** - * Make the flood control mechanism forget about an event for the current visitor. + * Makes the flood control mechanism forget an event for the current visitor. * * @param $name * The name of an event. @@ -1173,7 +1199,7 @@ function flood_clear_event($name, $identifier = NULL) { } /** - * Checks whether user is allowed to proceed with the specified event. + * Checks whether a user is allowed to proceed with the specified event. * * Events can have thresholds saying that each user can only do that event * a certain number of times in a time window. This function verifies that the @@ -1220,8 +1246,8 @@ function flood_is_allowed($name, $threshold, $window = 3600, $identifier = NULL) * This function must be called for all URIs within user-entered input prior * to being output to an HTML attribute value. It is often called as part of * check_url() or filter_xss(), but those functions return an HTML-encoded - * string, so this function can be called independently when the output needs to - * be a plain-text string for passing to t(), l(), drupal_attributes(), or + * string, so this function can be called independently when the output needs + * to be a plain-text string for passing to t(), l(), drupal_attributes(), or * another function that will call check_plain() separately. * * @param $uri @@ -1267,7 +1293,7 @@ function drupal_strip_dangerous_protocols($uri) { } /** - * Strips dangerous protocols (e.g. 'javascript:') from a URI and encodes it for output to an HTML attribute value. + * Strips dangerous protocols from a URI and encodes them for output to HTML. * * @param $uri * A plain-text URI that might contain dangerous protocols. @@ -1287,7 +1313,7 @@ function check_url($uri) { } /** - * Very permissive XSS/HTML filter for admin-only use. + * Applies a very permissive XSS/HTML filter for admin-only use. * * Use only for fields where it is impractical to use the * whole filter system, but where some (mainly inline) mark-up @@ -1301,7 +1327,7 @@ function filter_xss_admin($string) { } /** - * Filters an HTML string to prevent cross-site-scripting (XSS) vulnerabilities. + * Filters HTML to prevent cross-site-scripting (XSS) vulnerabilities. * * Based on kses by Ulf Harnhammar, see http://sourceforge.net/projects/kses. * For examples of various XSS attacks, see: http://ha.ckers.org/xss.html. @@ -1367,9 +1393,11 @@ function filter_xss($string, $allowed_tags = array('a', 'em', 'strong', 'cite', * @param $m * An array with various meaning depending on the value of $store. * If $store is TRUE then the array contains the allowed tags. - * If $store is FALSE then the array has one element, the HTML tag to process. + * If $store is FALSE then the array has one element, the HTML tag to + * process. * @param $store * Whether to store $m. + * * @return * If the element isn't allowed, an empty string. Otherwise, the cleaned up * version of the HTML element. @@ -1537,15 +1565,17 @@ function _filter_xss_attributes($attr) { } /** - * Processes an HTML attribute value and ensures it does not contain an URL with a disallowed protocol (e.g. javascript:). + * Processes an HTML attribute value and strips dangerous protocols from URLs. * * @param $string * The string with the attribute value. * @param $decode - * (Deprecated) Whether to decode entities in the $string. Set to FALSE if the - * $string is in plain text, TRUE otherwise. Defaults to TRUE. This parameter - * is deprecated and will be removed in Drupal 8. To process a plain-text URI, - * call drupal_strip_dangerous_protocols() or check_url() instead. + * (Deprecated) Whether to decode entities in the $string. Set to FALSE if + * the $string is in plain text, TRUE otherwise. Defaults to TRUE. This + * parameter is deprecated and will be removed in Drupal 8. To process + * a plain-text URI, call drupal_strip_dangerous_protocols() or check_url() + * instead. + * * @return * Cleaned up and HTML-escaped version of $string. */ @@ -1599,7 +1629,7 @@ function format_rss_channel($title, $link, $description, $items, $langcode = NUL } /** - * Format a single RSS item. + * Formats a single RSS item. * * Arbitrary elements may be added using the $args associative array. */ @@ -1615,7 +1645,7 @@ function format_rss_item($title, $link, $description, $args = array()) { } /** - * Format XML elements. + * Formats XML elements. * * @param $array * An array where each item represents an element and is either a: @@ -1654,7 +1684,7 @@ function format_xml_elements($array) { } /** - * Format a string containing a count of items. + * Formats a string containing a count of items. * * This function ensures that the string is pluralized correctly. Since t() is * called by this function, make sure not to pass already-localized strings to @@ -1677,16 +1707,17 @@ function format_xml_elements($array) { * The item count to display. * @param $singular * The string for the singular case. Please make sure it is clear this is - * singular, to ease translation (e.g. use "1 new comment" instead of "1 new"). - * Do not use @count in the singular string. + * singular, to ease translation (e.g. use "1 new comment" instead of + * "1 new"). Do not use @count in the singular string. * @param $plural - * The string for the plural case. Please make sure it is clear this is plural, - * to ease translation. Use @count in place of the item count, as in "@count - * new comments". + * The string for the plural case. Please make sure it is clear this is + * plural, to ease translation. Use @count in place of the item count, as + * in "@count new comments". * @param $args - * An associative array of replacements to make after translation. Incidences + * An associative array of replacements to make after translation. Instances * of any key in this array are replaced with the corresponding value. - * Based on the first character of the key, the value is escaped and/or themed: + * Based on the first character of the key, the value is escaped and/or + * themed: * - !variable: inserted as is * - @variable: escape plain text to HTML (check_plain) * - %variable: escape text and theme as a placeholder for user-submitted @@ -1699,6 +1730,7 @@ function format_xml_elements($array) { * translate to a language other than what is used to display the page. * - 'context' (default to the empty context) The context the source string * belongs to. + * * @return * A translated string. */ @@ -1729,11 +1761,12 @@ function format_plural($count, $singular, $plural, array $args = array(), array } /** - * Parse a given byte count. + * Parses a given byte count. * * @param $size * A size expressed as a number of bytes with optional SI or IEC binary unit * prefix (e.g. 2, 3K, 5MB, 10G, 6GiB, 8 bytes, 9mbytes). + * * @return * An integer representation of the size in bytes. */ @@ -1750,13 +1783,14 @@ function parse_size($size) { } /** - * Generate a string representation for the given byte count. + * Generates a string representation for the given byte count. * * @param $size * A size in bytes. * @param $langcode * Optional language code to translate to a language other than what is used * to display the page. + * * @return * A translated string representation of the size. */ @@ -1789,7 +1823,7 @@ function format_size($size, $langcode = NULL) { } /** - * Format a time interval with the requested granularity. + * Formats a time interval with the requested granularity. * * @param $timestamp * The length of the interval in seconds. @@ -1798,6 +1832,7 @@ function format_size($size, $langcode = NULL) { * @param $langcode * Optional language code to translate to a language other than * what is used to display the page. + * * @return * A translated string representation of the interval. */ @@ -1933,6 +1968,7 @@ function format_date($timestamp, $type = 'medium', $format = '', $timezone = NUL * * @param $date * A UNIX timestamp. + * * @return string * An ISO8601 formatted date. */ @@ -1977,14 +2013,12 @@ function _format_date_callback(array $matches = NULL, $new_langcode = NULL) { } /** - * Format a username. + * Formats a username. * * By default, the passed-in object's 'name' property is used if it exists, or * else, the site-defined value for the 'anonymous' variable. However, a module * may override this by implementing hook_username_alter(&$name, $account). * - * @see hook_username_alter() - * * @param $account * The account object for the user whose name is to be formatted. * @@ -1992,6 +2026,8 @@ function _format_date_callback(array $matches = NULL, $new_langcode = NULL) { * An unsanitized string with the username to display. The code receiving * this result must ensure that check_plain() is called on it before it is * printed to the page. + * + * @see hook_username_alter() */ function format_username($account) { $name = !empty($account->name) ? $account->name : variable_get('anonymous', t('Anonymous')); @@ -2018,9 +2054,9 @@ function format_username($account) { * and it will be replaced with the alias, if one exists. Additional query * arguments for internal paths must be supplied in $options['query'], not * included in $path. - * - If you provide an internal path and $options['alias'] is set to TRUE, the - * path is assumed already to be the correct path alias, and the alias is - * not looked up. + * - If you provide an internal path and $options['alias'] is set to TRUE, + * the path is assumed already to be the correct path alias, and the alias + * is not looked up. * - The special string '' generates a link to the site's base URL. * - If your external URL contains a query (e.g. http://example.com/foo?a=b), * then you can either URL encode the query keys and values yourself and @@ -2040,8 +2076,8 @@ function format_username($account) { * - 'external': Whether the given path is an external URL. * - 'language': An optional language object. If the path being linked to is * internal to the site, $options['language'] is used to look up the alias - * for the URL. If $options['language'] is omitted, the global $language_url - * will be used. + * for the URL. If $options['language'] is omitted, the global + * $language_url will be used. * - 'https': Whether this URL should point to a secure location. If not * defined, the current scheme is used, so the user stays on http or https * respectively. TRUE enforces HTTPS and FALSE enforces HTTP, but HTTPS can @@ -2058,8 +2094,8 @@ function format_username($account) { * Drupal on a web server that cannot be configured to automatically find * index.php, then hook_url_outbound_alter() can be implemented to force * this value to 'index.php'. - * - 'entity_type': The entity type of the object that called url(). Only set if - * url() is invoked by entity_uri(). + * - 'entity_type': The entity type of the object that called url(). Only + * set if url() is invoked by entity_uri(). * - 'entity': The entity object (such as a node) for which the URL is being * generated. Only set if url() is invoked by entity_uri(). * @@ -2184,7 +2220,7 @@ function url($path = NULL, array $options = array()) { } /** - * Return TRUE if a path is external to Drupal (e.g. http://example.com). + * Returns TRUE if a path is external to Drupal (e.g. http://example.com). * * If a path cannot be assessed by Drupal's menu handler, then we must * treat it as potentially insecure. @@ -2192,6 +2228,7 @@ function url($path = NULL, array $options = array()) { * @param $path * The internal path or external URL being linked to, such as "node/34" or * "http://example.com/foo". + * * @return * Boolean TRUE or FALSE, where TRUE indicates an external path. */ @@ -2204,7 +2241,7 @@ function url_is_external($path) { } /** - * Format an attribute string for a HTTP header. + * Formats an attribute string for a HTTP header. * * @param $attributes * An associative array of attributes such as 'rel'. @@ -2226,16 +2263,17 @@ function drupal_http_header_attributes(array $attributes = array()) { } /** - * Converts an associative array to an attribute string for use in XML/HTML tags. + * Converts an associative array to an XML/HTML tag attribute string. * * Each array key and its value will be formatted into an attribute string. - * If a value is itself an array, then its elements are concatenated to a single - * space-delimited string (for example, a class attribute with multiple values). + * If a value is itself an array, then its elements are concatenated to a + * single space-delimited string (for example, a class attribute with multiple + * values). * * Attribute values are sanitized by running them through check_plain(). * Attribute names are not automatically sanitized. When using user-supplied - * attribute names, it is strongly recommended to allow only white-listed names, - * since certain attributes carry security risks and can be abused. + * attribute names, it is strongly recommended to allow only white-listed + * names, since certain attributes carry security risks and can be abused. * * Examples of security aspects when using drupal_attributes: * @code @@ -2384,11 +2422,11 @@ function l($text, $path, array $options = array()) { * this function is to determine the most appropriate 'delivery callback' * function to route the content to. The delivery callback function then * sends the content to the browser in the needed format. The default delivery - * callback is drupal_deliver_html_page(), which delivers the content as an HTML - * page, complete with blocks in addition to the content. This default can be - * overridden on a per menu router item basis by setting 'delivery callback' in - * hook_menu() or hook_menu_alter(), and can also be overridden on a per request - * basis in hook_page_delivery_callback_alter(). + * callback is drupal_deliver_html_page(), which delivers the content as an + * HTML page, complete with blocks in addition to the content. This default + * can be overridden on a per menu router item basis by setting 'delivery + * callback' in hook_menu() or hook_menu_alter(), and can also be overridden + * on a per-request basis in hook_page_delivery_callback_alter(). * * For example, the same page callback function can be used for an HTML * version of the page and an Ajax version of the page. The page callback @@ -2552,7 +2590,7 @@ function drupal_deliver_html_page($page_callback_result) { } /** - * Perform end-of-request tasks. + * Performs end-of-request tasks. * * This function sets the page cache if appropriate, and allows modules to * react to the closing of the page by calling hook_exit(). @@ -2579,11 +2617,11 @@ function drupal_page_footer() { } /** - * Perform end-of-request tasks. + * Performs end-of-request tasks. * - * In some cases page requests need to end without calling drupal_page_footer(). - * In these cases, call drupal_exit() instead. There should rarely be a reason - * to call exit instead of drupal_exit(); + * In some cases page requests need to end without calling + * drupal_page_footer(). In these cases, call drupal_exit() instead. There + * should rarely be a reason to call exit instead of drupal_exit(); * * @param $destination * If this function is called from drupal_goto(), then this argument @@ -2601,7 +2639,7 @@ function drupal_exit($destination = NULL) { } /** - * Form an associative array from a linear array. + * Forms an associative array from a linear array. * * This function walks through the provided array and constructs an associative * array out of it. The keys of the resulting array will be the values of the @@ -2677,10 +2715,10 @@ function drupal_get_path($type, $name) { } /** - * Return the base URL path (i.e., directory) of the Drupal installation. + * Returns the base URL path (i.e., directory) of the Drupal installation. * - * base_path() prefixes and suffixes a "/" onto the returned path if the path is - * not empty. At the very least, this will return "/". + * base_path() prefixes and suffixes a "/" onto the returned path if the path + * is not empty. At the very least, this will return "/". * * Examples: * - http://example.com returns "/" because the path is empty. @@ -2691,7 +2729,7 @@ function base_path() { } /** - * Add a LINK tag with a distinct 'rel' attribute to the page's HEAD. + * Adds a LINK tag with a distinct 'rel' attribute to the page's HEAD. * * This function can be called as long the HTML header hasn't been sent, * which on normal pages is up through the preprocess step of theme('html'). @@ -2729,17 +2767,17 @@ function drupal_add_html_head_link($attributes, $header = FALSE) { * If CSS aggregation/compression is enabled, all cascading style sheets added * with $options['preprocess'] set to TRUE will be merged into one aggregate * file and compressed by removing all extraneous white space. - * Preprocessed inline stylesheets will not be aggregated into this single file; - * instead, they are just compressed upon output on the page. Externally hosted - * stylesheets are never aggregated or compressed. + * Preprocessed inline stylesheets will not be aggregated into this single + * file; instead, they are just compressed upon output on the page. Externally + * hosted stylesheets are never aggregated or compressed. * * The reason for aggregating the files is outlined quite thoroughly here: * http://www.die.net/musings/page_load_time/ "Load fewer external objects. Due * to request overhead, one bigger file just loads faster than two smaller ones * half its size." * - * $options['preprocess'] should be only set to TRUE when a file is required for - * all typical visitors and most pages of a site. It is critical that all + * $options['preprocess'] should be only set to TRUE when a file is required + * for all typical visitors and most pages of a site. It is critical that all * preprocessed files are added unconditionally on every page, even if the * files do not happen to be needed on a page. This is normally done by calling * drupal_add_css() in a hook_init() implementation. @@ -2775,8 +2813,8 @@ function drupal_add_html_head_link($attributes, $header = FALSE) { * (optional) A string defining the 'type' of CSS that is being added in the * $data parameter ('file', 'inline', or 'external'), or an array which can * have any or all of the following keys: - * - 'type': The type of stylesheet being added. Available options are 'file', - * 'inline' or 'external'. Defaults to 'file'. + * - 'type': The type of stylesheet being added. Available options are + * 'file', 'inline' or 'external'. Defaults to 'file'. * - 'basename': Force a basename for the file being added. Modules are * expected to use stylesheets with unique filenames, but integration of * external libraries may make this impossible. The basename of @@ -2793,26 +2831,26 @@ function drupal_add_html_head_link($attributes, $header = FALSE) { * loading a stylesheet within a higher weight group, so CSS within higher * weight groups take precendence over CSS within lower weight groups. * - 'every_page': For optimal front-end performance when aggregation is - * enabled, this should be set to TRUE if the stylesheet is present on every - * page of the website for users for whom it is present at all. This - * defaults to FALSE. It is set to TRUE for stylesheets added via module and - * theme .info files. Modules that add stylesheets within hook_init() + * enabled, this should be set to TRUE if the stylesheet is present on + * every page of the website for users for whom it is present at all. This + * defaults to FALSE. It is set to TRUE for stylesheets added via module + * and theme .info files. Modules that add stylesheets within hook_init() * implementations, or from other code that ensures that the stylesheet is * added to all website pages, should also set this flag to TRUE. All * stylesheets within the same group that have the 'every_page' flag set to * TRUE and do not have 'preprocess' set to FALSE are aggregated together * into a single aggregate file, and that aggregate file can be reused * across a user's entire site visit, leading to faster navigation between - * pages. However, stylesheets that are only needed on pages less frequently - * visited, can be added by code that only runs for those particular pages, - * and that code should not set the 'every_page' flag. This minimizes the - * size of the aggregate file that the user needs to download when first - * visiting the website. Stylesheets without the 'every_page' flag are - * aggregated into a separate aggregate file. This other aggregate file is - * likely to change from page to page, and each new aggregate file needs to - * be downloaded when first encountered, so it should be kept relatively - * small by ensuring that most commonly needed stylesheets are added to - * every page. + * pages. However, stylesheets that are only needed on pages less + * frequently visited, can be added by code that only runs for those + * particular pages, and that code should not set the 'every_page' flag. + * This minimizes the size of the aggregate file that the user needs to + * download when first visiting the website. Stylesheets without the + * 'every_page' flag are aggregated into a separate aggregate file. This + * other aggregate file is likely to change from page to page, and each + * new aggregate file needs to be downloaded when first encountered, so it + * should be kept relatively small by ensuring that most commonly needed + * stylesheets are added to every page. * - 'weight': The weight of the stylesheet specifies the order in which the * CSS will appear relative to other stylesheets with the same group and * 'every_page' flag. The exact ordering of stylesheets is as follows: @@ -2821,8 +2859,8 @@ function drupal_add_html_head_link($attributes, $header = FALSE) { * - Then by weight. * - Then by the order in which the CSS was added. For example, all else * being the same, a stylesheet added by a call to drupal_add_css() that - * happened later in the page request gets added to the page after one for - * which drupal_add_css() happened earlier in the page request. + * happened later in the page request gets added to the page after one + * for which drupal_add_css() happened earlier in the page request. * - 'media': The media type for the stylesheet, e.g., all, print, screen. * Defaults to 'all'. * - 'preprocess': If TRUE and CSS aggregation/compression is enabled, the @@ -2893,7 +2931,7 @@ function drupal_add_css($data = NULL, $options = NULL) { } /** - * Returns a themed representation of all stylesheets that should be attached to the page. + * Returns a themed representation of all stylesheets to attach to the page. * * It loads the CSS in order, with 'module' first, then 'theme' afterwards. * This ensures proper cascading of styles so themes can easily override @@ -2913,8 +2951,8 @@ function drupal_add_css($data = NULL, $options = NULL) { * stylesheets array is used instead. * @param $skip_alter * (optional) If set to TRUE, this function skips calling drupal_alter() on - * $css, useful when the calling function passes a $css array that has already - * been altered. + * $css, useful when the calling function passes a $css array that has + * already been altered. * * @return * A string of XHTML CSS tags. @@ -2963,11 +3001,20 @@ function drupal_get_css($css = NULL, $skip_alter = FALSE) { } /** - * Function used by uasort to sort the array structures returned by drupal_add_css() and drupal_add_js(). + * Callback: Sorts CSS and JavaScript resources * * This sort order helps optimize front-end performance while providing modules * and themes with the necessary control for ordering the CSS and JavaScript * appearing on a page. + * + * @param $a + * First item for comparison. The compared items should be associative + * arrays of member items from drupal_add_css() or drupal_add_js(). + * @param $b + * Second item for comparison. + * + * @see drupal_add_css() + * @see drupal_add_js() */ function drupal_sort_css_js($a, $b) { // First order by group, so that, for example, all items in the CSS_SYSTEM @@ -3003,7 +3050,7 @@ function drupal_sort_css_js($a, $b) { } /** - * Default callback to group CSS items. + * Grouping callback: Groups CSS items by their types, media, and browsers. * * This function arranges the CSS items that are in the #items property of the * styles element into groups. Arranging the CSS items into groups serves two @@ -3015,13 +3062,13 @@ function drupal_sort_css_js($a, $b) { * 31 CSS inclusion tag limit: http://drupal.org/node/228818. * * This function puts multiple items into the same group if they are groupable - * and if they are for the same 'media' and 'browsers'. Items of the 'file' type - * are groupable if their 'preprocess' flag is TRUE, items of the 'inline' type - * are always groupable, and items of the 'external' type are never groupable. - * This function also ensures that the process of grouping items does not change - * their relative order. This requirement may result in multiple groups for the - * same type, media, and browsers, if needed to accommodate other items in - * between. + * and if they are for the same 'media' and 'browsers'. Items of the 'file' + * type are groupable if their 'preprocess' flag is TRUE, items of the 'inline' + * type are always groupable, and items of the 'external' type are never + * groupable. This function also ensures that the process of grouping items + * does not change their relative order. This requirement may result in + * multiple groups for the same type, media, and browsers, if needed to + * accommodate other items in between. * * @param $css * An array of CSS items, as returned by drupal_add_css(), but after @@ -3034,6 +3081,7 @@ function drupal_sort_css_js($a, $b) { * 'items' key, which is the subset of items from $css that are in the group. * * @see drupal_pre_render_styles() + * @see system_element_info() */ function drupal_group_css($css) { $groups = array(); @@ -3100,7 +3148,7 @@ function drupal_group_css($css) { } /** - * Default callback to aggregate CSS files and inline content. + * Aggregation callback: Aggregates CSS files and inline content. * * Having the browser load fewer CSS files results in much faster page loads * than when it loads many small files. This function aggregates files within @@ -3116,6 +3164,7 @@ function drupal_group_css($css) { * * @see drupal_group_css() * @see drupal_pre_render_styles() + * @see system_element_info() */ function drupal_aggregate_css(&$css_groups) { $preprocess_css = (variable_get('preprocess_css', FALSE) && (!defined('MAINTENANCE_MODE') || MAINTENANCE_MODE != 'update')); @@ -3142,7 +3191,7 @@ function drupal_aggregate_css(&$css_groups) { } /** - * #pre_render callback to add the elements needed for CSS tags to be rendered. + * Pre-render callback: Adds the elements needed for CSS tags to be rendered. * * For production websites, LINK tags are preferable to STYLE tags with @import * statements, because: @@ -3164,28 +3213,28 @@ function drupal_aggregate_css(&$css_groups) { * (http://drupal.org/node/228818) and LINK tags are limited to one file per * tag, whereas STYLE tags can contain multiple @import statements allowing * multiple files to be loaded per tag. When CSS aggregation is disabled, a - * Drupal site can easily have more than 31 CSS files that need to be loaded, so - * using LINK tags exclusively would result in a site that would display + * Drupal site can easily have more than 31 CSS files that need to be loaded, + * so using LINK tags exclusively would result in a site that would display * incorrectly in IE. Depending on different needs, different strategies can be * employed to decide when to use LINK tags and when to use STYLE tags. * * The strategy employed by this function is to use LINK tags for all aggregate * files and for all files that cannot be aggregated (e.g., if 'preprocess' is * set to FALSE or the type is 'external'), and to use STYLE tags for groups - * of files that could be aggregated together but aren't (e.g., if the site-wide - * aggregation setting is disabled). This results in all LINK tags when - * aggregation is enabled, a guarantee that as many or only slightly more tags - * are used with aggregation disabled than enabled (so that if the limit were to - * be crossed with aggregation enabled, the site developer would also notice the - * problem while aggregation is disabled), and an easy way for a developer to - * view HTML source while aggregation is disabled and know what files will be - * aggregated together when aggregation becomes enabled. - * - * This function evaluates the aggregation enabled/disabled condition on a group - * by group basis by testing whether an aggregate file has been made for the - * group rather than by testing the site-wide aggregation setting. This allows - * this function to work correctly even if modules have implemented custom - * logic for grouping and aggregating files. + * of files that could be aggregated together but aren't (e.g., if the + * site-wide aggregation setting is disabled). This results in all LINK tags + * when aggregation is enabled, a guarantee that as many or only slightly more + * tags are used with aggregation disabled than enabled (so that if the limit + * were to be crossed with aggregation enabled, the site developer would also + * notice the problem while aggregation is disabled), and an easy way for a + * developer to view HTML source while aggregation is disabled and know what + * files will be aggregated together when aggregation becomes enabled. + * + * This function evaluates the aggregation enabled/disabled condition on a + * group-by-group basis by testing whether an aggregate file has been made for + * the group rather than by testing the site-wide aggregation setting. This + * allows this function to work correctly even if modules have implemented + * custom logic for grouping and aggregating files. * * @param $element * A render array containing: @@ -3456,9 +3505,7 @@ function drupal_build_css_cache($css) { } /** - * Helper function for drupal_build_css_cache(). - * - * This function will prefix all paths within a CSS file. + * Prefixes all paths within a CSS file for drupal_build_css_cache(). */ function _drupal_build_css_path($matches, $base = NULL) { $_base = &drupal_static(__FUNCTION__); @@ -3529,13 +3576,14 @@ function drupal_load_stylesheet($file, $optimize = NULL, $reset_basepath = TRUE) } /** - * Process the contents of a stylesheet for aggregation. + * Processes the contents of a stylesheet for aggregation. * * @param $contents * The contents of the stylesheet. * @param $optimize * (optional) Boolean whether CSS contents should be minified. Defaults to * FALSE. + * * @return * Contents of the stylesheet including the imported stylesheets. */ @@ -3631,15 +3679,17 @@ function drupal_delete_file_if_stale($uri) { } /** - * Prepare a string for use as a valid CSS identifier (element, class or ID name). + * Prepares a string for use as a CSS identifier (element, class, or ID name). * - * http://www.w3.org/TR/CSS21/syndata.html#characters shows the syntax for valid - * CSS identifiers (including element names, classes, and IDs in selectors.) + * http://www.w3.org/TR/CSS21/syndata.html#characters shows the syntax for + * valid CSS identifiers (including element names, classes, and IDs in + * selectors.) * * @param $identifier * The identifier to clean. * @param $filter * An array of string replacements to use on the identifier. + * * @return * The cleaned identifier. */ @@ -3661,13 +3711,14 @@ function drupal_clean_css_identifier($identifier, $filter = array(' ' => '-', '_ } /** - * Prepare a string for use as a valid class name. + * Prepares a string for use as a valid class name. * * Do not pass one string containing multiple classes as they will be * incorrectly concatenated with dashes, i.e. "one two" will become "one-two". * * @param $class * The class name to clean. + * * @return * The cleaned class name. */ @@ -3676,7 +3727,7 @@ function drupal_html_class($class) { } /** - * Prepare a string for use as a valid HTML ID and guarantee uniqueness. + * Prepares a string for use as a valid HTML ID and guarantee uniqueness. * * This function ensures that each passed HTML ID value only exists once on the * page. By tracking the already returned ids, this function enables forms, @@ -3799,15 +3850,15 @@ function drupal_region_class($region) { * * The behavior of this function depends on the parameters it is called with. * Generally, it handles the addition of JavaScript to the page, either as - * reference to an existing file or as inline code. The following actions can be - * performed using this function: + * reference to an existing file or as inline code. The following actions can + * be performed using this function: * - Add a file ('file'): Adds a reference to a JavaScript file to the page. * - Add inline JavaScript code ('inline'): Executes a piece of JavaScript code * on the current page by placing the code directly in the page (for example, * to tell the user that a new message arrived, by opening a pop up, alert - * box, etc.). This should only be used for JavaScript that cannot be executed - * from a file. When adding inline code, make sure that you are not relying on - * $() being the jQuery function. Wrap your code in + * box, etc.). This should only be used for JavaScript that cannot be + * executed from a file. When adding inline code, make sure that you are not + * relying on $() being the jQuery function. Wrap your code in * @code (function ($) {... })(jQuery); @endcode * or use jQuery() instead of $(). * - Add external JavaScript ('external'): Allows the inclusion of external @@ -3843,8 +3894,8 @@ function drupal_region_class($region) { * to request overhead, one bigger file just loads faster than two smaller ones * half its size." * - * $options['preprocess'] should be only set to TRUE when a file is required for - * all typical visitors and most pages of a site. It is critical that all + * $options['preprocess'] should be only set to TRUE when a file is required + * for all typical visitors and most pages of a site. It is critical that all * preprocessed files are added unconditionally on every page, even if the * files are not needed on a page. This is normally done by calling * drupal_add_js() in a hook_init() implementation. @@ -3861,10 +3912,10 @@ function drupal_region_class($region) { * JavaScript aggregation is enabled. * - 'setting': An associative array with configuration options. The array is * merged directly into Drupal.settings. All modules should wrap their - * actual configuration settings in another variable to prevent conflicts in - * the Drupal.settings namespace. Items added with a string key will replace - * existing settings with that key; items with numeric array keys will be - * added to the existing settings array. + * actual configuration settings in another variable to prevent conflicts + * in the Drupal.settings namespace. Items added with a string key will + * replace existing settings with that key; items with numeric array keys + * will be added to the existing settings array. * @param $options * (optional) A string defining the type of JavaScript that is being added in * the $data parameter ('file'/'setting'/'inline'/'external'), or an @@ -3885,8 +3936,8 @@ function drupal_region_class($region) { * group is presented on the page before JavaScript within a higher weight * group. * - every_page: For optimal front-end performance when aggregation is - * enabled, this should be set to TRUE if the JavaScript is present on every - * page of the website for users for whom it is present at all. This + * enabled, this should be set to TRUE if the JavaScript is present on + * every page of the website for users for whom it is present at all. This * defaults to FALSE. It is set to TRUE for JavaScript files that are added * via module and theme .info files. Modules that add JavaScript within * hook_init() implementations, or from other code that ensures that the @@ -3910,12 +3961,12 @@ function drupal_region_class($region) { * and 'every_page' value. In some cases, the order in which the JavaScript * is presented on the page is very important. jQuery, for example, must be * added to the page before any jQuery code is run, so jquery.js uses the - * JS_LIBRARY group and a weight of -20, jquery.once.js (a library drupal.js - * depends on) uses the JS_LIBRARY group and a weight of -19, drupal.js uses - * the JS_LIBRARY group and a weight of -1, other libraries use the - * JS_LIBRARY group and a weight of 0 or higher, and all other scripts use - * one of the other group constants. The exact ordering of JavaScript is as - * follows: + * JS_LIBRARY group and a weight of -20, jquery.once.js (a library + * drupal.js depends on) uses the JS_LIBRARY group and a weight of -19, + * drupal.js uses the JS_LIBRARY group and a weight of -1, other libraries + * use the JS_LIBRARY group and a weight of 0 or higher, and all other + * scripts use one of the other group constants. The exact ordering of + * JavaScript is as follows: * - First by scope, with 'header' first, 'footer' last, and any other * scopes provided by a custom theme coming in between, as determined by * the theme. @@ -3923,9 +3974,9 @@ function drupal_region_class($region) { * - Then by the 'every_page' flag, with TRUE coming before FALSE. * - Then by weight. * - Then by the order in which the JavaScript was added. For example, all - * else being the same, JavaScript added by a call to drupal_add_js() that - * happened later in the page request gets added to the page after one for - * which drupal_add_js() happened earlier in the page request. + * else being the same, JavaScript added by a call to drupal_add_js() + * that happened later in the page request gets added to the page after + * one for which drupal_add_js() happened earlier in the page request. * - defer: If set to TRUE, the defer attribute is set on the <script> * tag. Defaults to FALSE. * - cache: If set to FALSE, the JavaScript file is loaded anew on every page @@ -4024,6 +4075,7 @@ function drupal_add_js($data = NULL, $options = NULL) { * * @param $data * (optional) The default data parameter for the JavaScript item array. + * * @see drupal_get_js() * @see drupal_add_js() */ @@ -4067,8 +4119,10 @@ function drupal_js_defaults($data = NULL) { * (optional) If set to TRUE, this function skips calling drupal_alter() on * $javascript, useful when the calling function passes a $javascript array * that has already been altered. + * * @return * All JavaScript code segments and includes for the scope as HTML tags. + * * @see drupal_add_js() * @see locale_js_alter() * @see drupal_js_defaults() @@ -4231,8 +4285,8 @@ function drupal_get_js($scope = 'header', $javascript = NULL, $skip_alter = FALS * * Libraries, JavaScript, CSS and other types of custom structures are attached * to elements using the #attached property. The #attached property is an - * associative array, where the keys are the the attachment types and the values - * are the attached data. For example: + * associative array, where the keys are the the attachment types and the + * values are the attached data. For example: * @code * $build['#attached'] = array( * 'js' => array(drupal_get_path('module', 'taxonomy') . '/taxonomy.js'), @@ -4269,9 +4323,9 @@ function drupal_get_js($scope = 'header', $javascript = NULL, $skip_alter = FALS * set to FALSE, will continue to add the libraries, even though one or more * dependencies are missing. Defaults to FALSE. * @param $every_page - * Set to TRUE to indicate that the attachments are added to every page on the - * site. Only attachments with the every_page flag set to TRUE can participate - * in JavaScript/CSS aggregation. + * Set to TRUE to indicate that the attachments are added to every page on + * the site. Only attachments with the every_page flag set to TRUE can + * participate in JavaScript/CSS aggregation. * * @return * FALSE if there were any missing library dependencies; TRUE if all library @@ -4352,8 +4406,8 @@ function drupal_process_attached($elements, $group = JS_DEFAULT, $dependency_che * * A "state" means a certain property on a DOM element, such as "visible" or * "checked". A state can be applied to an element, depending on the state of - * another element on the page. In general, states depend on HTML attributes and - * DOM element properties, which change due to user interaction. + * another element on the page. In general, states depend on HTML attributes + * and DOM element properties, which change due to user interaction. * * Since states are driven by JavaScript only, it is important to understand * that all states are applied on presentation only, none of the states force @@ -4532,9 +4586,9 @@ function drupal_add_library($module, $name, $every_page = NULL) { * * Library information is statically cached. Libraries are keyed by module for * several reasons: - * - Libraries are not unique. Multiple modules might ship with the same library - * in a different version or variant. This registry cannot (and does not - * attempt to) prevent library conflicts. + * - Libraries are not unique. Multiple modules might ship with the same + * library in a different version or variant. This registry cannot (and does + * not attempt to) prevent library conflicts. * - Modules implementing and thereby depending on a library that is registered * by another module can only rely on that module's library. * - Two (or more) modules can still register the same library and use it @@ -4547,9 +4601,10 @@ function drupal_add_library($module, $name, $every_page = NULL) { * libraries registered by $module are returned. * * @return - * The definition of the requested library, if $name was passed and it exists, - * or FALSE if it does not exist. If no $name was passed, an associative array - * of libraries registered by $module is returned (which may be empty). + * The definition of the requested library, if $name was passed and it + * exists, or FALSE if it does not exist. If no $name was passed, an + * associative array of libraries registered by $module is returned (which + * may be empty). * * @see drupal_add_library() * @see hook_library_info() @@ -4591,11 +4646,12 @@ function drupal_get_library($module, $name = NULL) { } /** - * Assist in adding the tableDrag JavaScript behavior to a themed table. + * Assists in adding the tableDrag JavaScript behavior to a themed table. * - * Draggable tables should be used wherever an outline or list of sortable items - * needs to be arranged by an end-user. Draggable tables are very flexible and - * can manipulate the value of form elements placed within individual columns. + * Draggable tables should be used wherever an outline or list of sortable + * items needs to be arranged by an end-user. Draggable tables are very + * flexible and can manipulate the value of form elements placed within + * individual columns. * * To set up a table to use drag and drop in place of weight select-lists or * in place of a form that contains parent relationships, the form must be @@ -4609,14 +4665,14 @@ function drupal_get_library($module, $name = NULL) { * In the theme function for the form, a special class must be added to each * form element within the same column, "grouping" them together. * - * In a situation where a single weight column is being sorted in the table, the - * classes could be added like this (in the theme function): + * In a situation where a single weight column is being sorted in the table, + * the classes could be added like this (in the theme function): * @code * $form['my_elements'][$delta]['weight']['#attributes']['class'] = array('my-elements-weight'); * @endcode * - * Each row of the table must also have a class of "draggable" in order to enable the - * drag handles: + * Each row of the table must also have a class of "draggable" in order to + * enable the drag handles: * @code * $row = array(...); * $rows[] = array( @@ -4636,8 +4692,8 @@ function drupal_get_library($module, $name = NULL) { * @endcode * * In a more complex case where there are several groups in one column (such as - * the block regions on the admin/structure/block page), a separate subgroup class - * must also be added to differentiate the groups. + * the block regions on the admin/structure/block page), a separate subgroup + * class must also be added to differentiate the groups. * @code * $form['my_elements'][$region][$delta]['weight']['#attributes']['class'] = array('my-elements-weight', 'my-elements-weight-' . $region); * @endcode @@ -4658,12 +4714,12 @@ function drupal_get_library($module, $name = NULL) { * See theme_menu_overview_form() for an example creating a table containing * parent relationships. * - * Please note that this function should be called from the theme layer, such as - * in a .tpl.php file, theme_ function, or in a template_preprocess function, - * not in a form declaration. Though the same JavaScript could be added to the - * page using drupal_add_js() directly, this function helps keep template files - * clean and readable. It also prevents tabledrag.js from being added twice - * accidentally. + * Please note that this function should be called from the theme layer, such + * as in a .tpl.php file, theme_ function, or in a template_preprocess + * function, not in a form declaration. Though the same JavaScript could be + * added to the page using drupal_add_js() directly, this function helps keep + * template files clean and readable. It also prevents tabledrag.js from + * being added twice accidentally. * * @param $table_id * String containing the target table's id attribute. If the table does not @@ -4671,8 +4727,8 @@ function drupal_get_library($module, $name = NULL) { * @param $action * String describing the action to be done on the form item. Either 'match' * 'depth', or 'order'. Match is typically used for parent relationships. - * Order is typically used to set weights on other form elements with the same - * group. Depth updates the target element with the current indentation. + * Order is typically used to set weights on other form elements with the + * same group. Depth updates the target element with the current indentation. * @param $relationship * String describing where the $action variable should be performed. Either * 'parent', 'sibling', 'group', or 'self'. Parent will only look for fields @@ -4682,8 +4738,8 @@ function drupal_get_library($module, $name = NULL) { * @param $group * A class name applied on all related form elements for this action. * @param $subgroup - * (optional) If the group has several subgroups within it, this string should - * contain the class name identifying fields in the same subgroup. + * (optional) If the group has several subgroups within it, this string + * should contain the class name identifying fields in the same subgroup. * @param $source * (optional) If the $action is 'match', this string should contain the class * name identifying what field will be used as the source value when matching @@ -4694,6 +4750,7 @@ function drupal_get_library($module, $name = NULL) { * column should not be hidden. * @param $limit * (optional) Limit the maximum amount of parenting in this table. + * * @see block-admin-display-form.tpl.php * @see theme_menu_overview_form() */ @@ -4822,7 +4879,7 @@ function drupal_json_decode($var) { } /** - * Return data in JSON format. + * Returns data in JSON format. * * This function should be used for JavaScript callback functions returning * data in JSON format. It sets the header for JavaScript output. @@ -4840,7 +4897,7 @@ function drupal_json_output($var = NULL) { } /** - * Get a salt useful for hardening against SQL injection. + * Gets a salt useful for hardening against SQL injection. * * @return * A salt based on information in settings.php, not in the database. @@ -4853,7 +4910,7 @@ function drupal_get_hash_salt() { } /** - * Ensure the private key variable used to generate tokens is set. + * Ensures the private key variable used to generate tokens is set. * * @return * The private key. @@ -4867,7 +4924,7 @@ function drupal_get_private_key() { } /** - * Generate a token based on $value, the current user session and private key. + * Generates a token based on $value, the user session, and the private key. * * @param $value * An additional value to base the token on. @@ -4877,7 +4934,7 @@ function drupal_get_token($value = '') { } /** - * Validate a token based on $value, the current user session and private key. + * Validates a token based on $value, the user session, and the private key. * * @param $token * The token to be validated. @@ -4885,6 +4942,7 @@ function drupal_get_token($value = '') { * An additional value to base the token on. * @param $skip_anonymous * Set to true to skip token validation for anonymous users. + * * @return * True for a valid token, false for an invalid token. When $skip_anonymous * is true, the return value will always be true for anonymous users. @@ -4953,7 +5011,7 @@ function _drupal_bootstrap_full() { } /** - * Store the current page in the cache. + * Stores the current page in the cache. * * If page_compression is enabled, a gzipped version of the page is stored in * the cache to avoid compressing the output on each request. The cache entry @@ -5005,10 +5063,10 @@ function drupal_page_set_cache() { /** * Executes a cron run when called. * - * Do not call this function from test, use $this->cronRun() instead. + * Do not call this function from a test. Use $this->cronRun() instead. * * @return - * Returns TRUE if ran successfully + * Returns TRUE if cron ran successfully. */ function drupal_cron_run() { // Allow execution to continue even if the request gets canceled. @@ -5083,7 +5141,10 @@ function drupal_cron_run() { } /** - * Shutdown function for cron cleanup. + * Shutdown function: Performs cron cleanup. + * + * @see drupal_cron_run() + * @see drupal_register_shutdown_function() */ function drupal_cron_cleanup() { // See if the semaphore is still locked. @@ -5129,16 +5190,17 @@ function drupal_cron_cleanup() { * @param string $key * The key to be used for the associative array returned. Possible values are * 'uri', for the file's URI; 'filename', for the basename of the file; and - * 'name' for the name of the file without the extension. If you choose 'name' - * or 'filename', only the highest-precedence file will be returned. + * 'name' for the name of the file without the extension. If you choose + * 'name' or 'filename', only the highest-precedence file will be returned. * @param int $min_depth * Minimum depth of directories to return files from, relative to each * directory searched. For instance, a minimum depth of 2 would find modules * inside /modules/node/tests, but not modules directly in /modules/node. * * @return array - * An associative array of file objects, keyed on the chosen key. Each element - * in the array is an object containing file information, with properties: + * An associative array of file objects, keyed on the chosen key. Each + * element in the array is an object containing file information, with + * properties: * - 'uri': Full URI of the file. * - 'filename': File name. * - 'name': Name of file without the extension. @@ -5202,7 +5264,7 @@ function drupal_system_listing($mask, $directory, $key = 'name', $min_depth = 1) } /** - * Set the main page content value for later use. + * Sets the main page content value for later use. * * Given the nature of the Drupal page handling, this will be called once with * a string or array. We store that and return it later as the block is being @@ -5210,6 +5272,7 @@ function drupal_system_listing($mask, $directory, $key = 'name', $min_depth = 1) * * @param $content * A string or renderable array representing the body of the page. + * * @return * If called without $content, a renderable array representing the body of * the page. @@ -5232,7 +5295,7 @@ function drupal_set_page_content($content = NULL) { } /** - * #pre_render callback to render #browsers into #prefix and #suffix. + * Pre-render callback: Renders #browsers into #prefix and #suffix. * * @param $elements * A render array with a '#browsers' property. The '#browsers' property can @@ -5308,7 +5371,7 @@ function drupal_pre_render_conditional_comments($elements) { } /** - * #pre_render callback to render a link into #markup. + * Pre-render callback: Renders a link into #markup. * * Doing so during pre_render gives modules a chance to alter the link parts. * @@ -5362,7 +5425,7 @@ function drupal_pre_render_link($element) { } /** - * #pre_render callback that collects child links into a single array. + * Pre-render callback: Collects child links into a single array. * * This function can be added as a pre_render callback for a renderable array, * usually one which will be themed by theme_links(). It iterates through all @@ -5453,20 +5516,20 @@ function drupal_pre_render_links($element) { } /** - * #pre_render callback to append contents in #markup to #children. + * Pre-render callback: Appends contents in #markup to #children. * * This needs to be a #pre_render callback, because eventually assigned * #theme_wrappers will expect the element's rendered content in #children. * Note that if also a #theme is defined for the element, then the result of * the theme callback will override #children. * - * @see drupal_render() - * * @param $elements * A structured array using the #markup key. * * @return * The passed-in elements, but #markup appended to #children. + * + * @see drupal_render() */ function drupal_pre_render_markup($elements) { $elements['#children'] = $elements['#markup']; @@ -5477,10 +5540,12 @@ function drupal_pre_render_markup($elements) { * Renders the page, including all theming. * * @param $page - * A string or array representing the content of a page. The array consists of - * the following keys: - * - #type: Value is always 'page'. This pushes the theming through page.tpl.php (required). - * - #show_messages: Suppress drupal_get_message() items. Used by Batch API (optional). + * A string or array representing the content of a page. The array consists + * of the following keys: + * - #type: Value is always 'page'. This pushes the theming through + * page.tpl.php. Required. + * - #show_messages: (optional) Suppress drupal_get_message() items. Used by + * Batch API. * * @see hook_page_alter() * @see element_info() @@ -5555,22 +5620,23 @@ function drupal_render_page($page) { * the form markup itself. * * drupal_render() can optionally cache the rendered output of elements to - * improve performance. To use drupal_render() caching, set the element's #cache - * property to an associative array with one or several of the following keys: - * - 'keys': An array of one or more keys that identify the element. If 'keys' - * is set, the cache ID is created automatically from these keys. See - * drupal_render_cid_create(). - * - 'granularity' (optional): Define the cache granularity using binary - * combinations of the cache granularity constants, e.g. DRUPAL_CACHE_PER_USER - * to cache for each user separately or - * DRUPAL_CACHE_PER_PAGE | DRUPAL_CACHE_PER_ROLE to cache separately for each - * page and role. If not specified the element is cached globally for each - * theme and language. - * - 'cid': Specify the cache ID directly. Either 'keys' or 'cid' is required. - * If 'cid' is set, 'keys' and 'granularity' are ignored. Use only if you - * have special requirements. - * - 'expire': Set to one of the cache lifetime constants. - * - 'bin': Specify a cache bin to cache the element in. Defaults to 'cache'. + * improve performance. To use drupal_render() caching, set the element's + * #cache property to an associative array with one or several of the + * following keys: + * - 'keys': An array of one or more keys that identify the element. If 'keys' + * is set, the cache ID is created automatically from these keys. See + * drupal_render_cid_create(). + * - 'granularity' (optional): Define the cache granularity using binary + * combinations of the cache granularity constants, e.g. + * DRUPAL_CACHE_PER_USER to cache for each user separately or + * DRUPAL_CACHE_PER_PAGE | DRUPAL_CACHE_PER_ROLE to cache separately for each + * page and role. If not specified the element is cached globally for each + * theme and language. + * - 'cid': Specify the cache ID directly. Either 'keys' or 'cid' is required. + * If 'cid' is set, 'keys' and 'granularity' are ignored. Use only if you + * have special requirements. + * - 'expire': Set to one of the cache lifetime constants. + * - 'bin': Specify a cache bin to cache the element in. Defaults to 'cache'. * * This function is usually called from within another function, like * drupal_get_form() or a theme function. Elements are sorted internally @@ -5587,6 +5653,7 @@ function drupal_render_page($page) { * * @param $elements * The structured array describing the data to be rendered. + * * @return * The rendered HTML. */ @@ -5700,7 +5767,7 @@ function drupal_render(&$elements) { } /** - * Render children of an element and concatenate them. + * Renders children of an element and concatenates them. * * This renders all children of an element using drupal_render() and then * joins them together into a single string. @@ -5708,8 +5775,8 @@ function drupal_render(&$elements) { * @param $element * The structured array whose children shall be rendered. * @param $children_keys - * If the keys of the element's children are already known, they can be passed - * in to save another run of element_children(). + * If the keys of the element's children are already known, they can be + * passed in to save another run of element_children(). */ function drupal_render_children(&$element, $children_keys = NULL) { if ($children_keys === NULL) { @@ -5725,7 +5792,7 @@ function drupal_render_children(&$element, $children_keys = NULL) { } /** - * Render an element. + * Renders an element. * * This function renders an element using drupal_render(). The top level * element is shown with show() before rendering, so it will always be rendered @@ -5754,7 +5821,7 @@ function render(&$element) { } /** - * Hide an element from later rendering. + * Hides an element from later rendering. * * The first time render() or drupal_render() is called on an element tree, * as each element in the tree is rendered, it is marked with a #printed flag @@ -5780,7 +5847,7 @@ function hide(&$element) { } /** - * Show a hidden element for later rendering. + * Shows a hidden element for later rendering. * * You can also use render($element), which shows the element while rendering * it. @@ -5809,16 +5876,17 @@ function show(&$element) { } /** - * Get the rendered output of a renderable element from cache. - * - * @see drupal_render() - * @see drupal_render_cache_set() + * Gets the rendered output of a renderable element from cache. * * @param $elements * A renderable array. + * * @return * A markup string containing the rendered content of the element, or FALSE * if no cached copy of the element is available. + * + * @see drupal_render() + * @see drupal_render_cache_set() */ function drupal_render_cache_get($elements) { if (!in_array($_SERVER['REQUEST_METHOD'], array('GET', 'HEAD')) || !$cid = drupal_render_cid_create($elements)) { @@ -5839,17 +5907,17 @@ function drupal_render_cache_get($elements) { } /** - * Cache the rendered output of a renderable element. + * Caches the rendered output of a renderable element. * - * This is called by drupal_render() if the #cache property is set on an element. - * - * @see drupal_render() - * @see drupal_render_cache_get() + * This is called by drupal_render() if the #cache property is set on an + * element. * * @param $markup * The rendered output string of $elements. * @param $elements * A renderable array. + * + * @see drupal_render_cache_get() */ function drupal_render_cache_set(&$markup, $elements) { // Create the cache ID for the element. @@ -5875,7 +5943,7 @@ function drupal_render_cache_set(&$markup, $elements) { } /** - * Collect #attached for an element and all child elements into a single array. + * Collects #attached for an element and its children into a single array. * * When caching elements, it is necessary to collect all libraries, JavaScript * and CSS into a single array, from both the element itself and all child @@ -5918,9 +5986,10 @@ function drupal_render_collect_attached($elements, $return = FALSE) { } /** - * Prepare an element for caching based on a query. This smart caching strategy - * saves Drupal from querying and rendering to HTML when the underlying query is - * unchanged. + * Prepares an element for caching based on a query. + * + * This smart caching strategy saves Drupal from querying and rendering to + * HTML when the underlying query is unchanged. * * Expensive queries should use the query builder to create the query and then * call this function. Executing the query and formatting results should happen @@ -5958,12 +6027,13 @@ function drupal_render_cache_by_query($query, $function, $expire = CACHE_TEMPORA } /** - * Helper function for building cache ids. + * Returns cache ID parts for building a cache ID. * * @param $granularity - * One or more cache granularity constants, e.g. DRUPAL_CACHE_PER_USER to cache - * for each user separately or DRUPAL_CACHE_PER_PAGE | DRUPAL_CACHE_PER_ROLE to - * cache separately for each page and role. + * One or more cache granularity constants, e.g. DRUPAL_CACHE_PER_USER to + * cache for each user separately or + * DRUPAL_CACHE_PER_PAGE | DRUPAL_CACHE_PER_ROLE to cache separately for + * each page and role. * * @return * An array of cache ID parts, always containing the active theme. If the @@ -6002,7 +6072,7 @@ function drupal_render_cid_parts($granularity = NULL) { } /** - * Create the cache ID for a renderable element. + * Creates the cache ID for a renderable element. * * This creates the cache ID string, either by returning the #cache['cid'] * property if present or by building the cache ID out of the #cache['keys'] @@ -6028,7 +6098,15 @@ function drupal_render_cid_create($elements) { } /** - * Function used by uasort to sort structured arrays by weight. + * Callback: Sorts a structured array by '#weight' property. + * + * Used with uasort(). + * + * @param $a + * First item for comparison. The compared items should be associative + * arrays that optionally include a '#weight' key. + * @param $b + * Second item for comparison. */ function element_sort($a, $b) { $a_weight = (is_array($a) && isset($a['#weight'])) ? $a['#weight'] : 0; @@ -6040,7 +6118,18 @@ function element_sort($a, $b) { } /** - * Array sorting callback; sorts elements by title. + * Callback: Sorts a structured array by '#title' property. + * + * Used with uasort(). + * + * @param $a + * First item for comparison. The compared items should be associative + * arrays that optionally include a '#title' key. + * @param $b + * Second item for comparison. + * + * @see system_modules() + * @see theme_simpletest_test_table() */ function element_sort_by_title($a, $b) { $a_title = (is_array($a) && isset($a['#title'])) ? $a['#title'] : ''; @@ -6049,7 +6138,7 @@ function element_sort_by_title($a, $b) { } /** - * Retrieve the default properties for the defined element type. + * Retrieves the default properties for the defined element type. * * @param $type * An element type as defined by hook_element_info(). @@ -6075,7 +6164,7 @@ function element_info($type) { } /** - * Retrieve a single property for the defined element type. + * Retrieves a single property for the defined element type. * * @param $type * An element type as defined by hook_element_info(). @@ -6090,7 +6179,15 @@ function element_info_property($type, $property_name, $default = NULL) { } /** - * Function used by uasort to sort structured arrays by weight, without the property weight prefix. + * Callback: Sorts a structured array by 'weight' key (no # prefix). + * + * Used with uasort(). + * + * @param $a + * First item for comparison. The compared items should be associative + * arrays that optionally include a 'weight' key. + * @param $b + * Second item for comparison. */ function drupal_sort_weight($a, $b) { $a_weight = (is_array($a) && isset($a['weight'])) ? $a['weight'] : 0; @@ -6102,7 +6199,15 @@ function drupal_sort_weight($a, $b) { } /** - * Array sorting callback; sorts elements by 'title' key. + * Callback: Sorts a structured array by 'title' key (no # prefix). + * + * Used with uasort(). + * + * @param $a + * First item for comparison. The compared items should be associative + * arrays that optionally include a 'title' key. + * @param $b + * Second item for comparison. */ function drupal_sort_title($a, $b) { if (!isset($b['title'])) { @@ -6115,21 +6220,21 @@ function drupal_sort_title($a, $b) { } /** - * Check if the key is a property. + * Checks if the key is a property. */ function element_property($key) { return $key[0] == '#'; } /** - * Get properties of a structured array element. Properties begin with '#'. + * Gets properties of a structured array element. Properties begin with '#'. */ function element_properties($element) { return array_filter(array_keys((array) $element), 'element_property'); } /** - * Check if the key is a child. + * Checks if the key is a child. */ function element_child($key) { return !isset($key[0]) || $key[0] != '#'; @@ -6145,6 +6250,7 @@ function element_child($key) { * The element array whose children are to be identified. * @param $sort * Boolean to indicate whether the children should be sorted by weight. + * * @return * The array keys of the element's children. */ @@ -6191,6 +6297,7 @@ function element_children(&$elements, $sort = FALSE) { * * @param $elements * The parent element. + * * @return * The array keys of the element's visible children. */ @@ -6222,11 +6329,11 @@ function element_get_visible_children(array $elements) { * @param $element * The renderable element to process. * @param $map - * An associative array whose keys are element property names and whose values - * are the HTML attribute names to set for corresponding the property; e.g., - * array('#propertyname' => 'attributename'). If both names are identical - * except for the leading '#', then an attribute name value is sufficient and - * no property name needs to be specified. + * An associative array whose keys are element property names and whose + * values are the HTML attribute names to set for corresponding the property; + * e.g., array('#propertyname' => 'attributename'). If both names are + * identical except for the leading '#', then an attribute name value is + * sufficient and no property name needs to be specified. */ function element_set_attributes(array &$element, array $map) { foreach ($map as $property => $attribute) { @@ -6265,11 +6372,11 @@ function element_set_attributes(array &$element, array $map) { * To deal with the situation, the code needs to figure out the route to the * element, given an array of parents that is either * @code array('signature_settings', 'signature') @endcode in the first case or - * @code array('signature_settings', 'user', 'signature') @endcode in the second - * case. + * @code array('signature_settings', 'user', 'signature') @endcode in the + * second case. * - * Without this helper function the only way to set the signature element in one - * line would be using eval(), which should be avoided: + * Without this helper function the only way to set the signature element in + * one line would be using eval(), which should be avoided: * @code * // Do not do this! Avoid eval(). * eval('$form[\'' . implode("']['", $parents) . '\'] = $element;'); @@ -6280,9 +6387,9 @@ function element_set_attributes(array &$element, array $map) { * drupal_array_set_nested_value($form, $parents, $element); * @endcode * - * However if the number of array parent keys is static, the value should always - * be set directly rather than calling this function. For instance, for the - * first example we could just do: + * However if the number of array parent keys is static, the value should + * always be set directly rather than calling this function. For instance, for + * the first example we could just do: * @code * $form['signature_settings']['signature'] = $element; * @endcode @@ -6317,9 +6424,9 @@ function drupal_array_set_nested_value(array &$array, array $parents, $value, $f /** * Retrieves a value from a nested array with variable depth. * - * This helper function should be used when the depth of the array element being - * retrieved may vary (that is, the number of parent keys is variable). It is - * primarily used for form structures and renderable arrays. + * This helper function should be used when the depth of the array element + * being retrieved may vary (that is, the number of parent keys is variable). + * It is primarily used for form structures and renderable arrays. * * Without this helper function the only way to get a nested array value with * variable depth in one line would be using eval(), which should be avoided: @@ -6334,8 +6441,8 @@ function drupal_array_set_nested_value(array &$array, array $parents, $value, $f * $value = drupal_array_get_nested_value($form, $parents); * @endcode * - * The return value will be NULL, regardless of whether the actual value is NULL - * or whether the requested key does not exist. If it is required to know + * The return value will be NULL, regardless of whether the actual value is + * NULL or whether the requested key does not exist. If it is required to know * whether the nested array key actually exists, pass a third argument that is * altered by reference: * @code @@ -6346,8 +6453,9 @@ function drupal_array_set_nested_value(array &$array, array $parents, $value, $f * } * @endcode * - * However if the number of array parent keys is static, the value should always - * be retrieved directly rather than calling this function. For instance: + * However if the number of array parent keys is static, the value should + * always be retrieved directly rather than calling this function. For + * instance: * @code * $value = $form['signature_settings']['signature']; * @endcode @@ -6364,8 +6472,8 @@ function drupal_array_set_nested_value(array &$array, array $parents, $value, $f * The requested nested value. Possibly NULL if the value is NULL or not all * nested parent keys exist. $key_exists is altered by reference and is a * Boolean that indicates whether all nested parent keys exist (TRUE) or not - * (FALSE). This allows to distinguish between the two possibilities when NULL - * is returned. + * (FALSE). This allows to distinguish between the two possibilities when + * NULL is returned. * * @see drupal_array_set_nested_value() */ @@ -6385,10 +6493,10 @@ function drupal_array_get_nested_value(array &$array, array $parents, &$key_exis } /** - * Determines whether a nested array with variable depth contains all of the requested keys. + * Determines whether a nested array contains the requested keys. * - * This helper function should be used when the depth of the array element to be - * checked may vary (that is, the number of parent keys is variable). See + * This helper function should be used when the depth of the array element to + * be checked may vary (that is, the number of parent keys is variable). See * drupal_array_set_nested_value() for details. It is primarily used for form * structures and renderable arrays. * @@ -6421,7 +6529,7 @@ function drupal_array_nested_key_exists(array $array, array $parents) { } /** - * Provide theme registration for themes across .inc files. + * Provides theme registration for themes across .inc files. */ function drupal_common_theme() { return array( @@ -6632,7 +6740,7 @@ function drupal_common_theme() { */ /** - * Creates all tables in a module's hook_schema() implementation. + * Creates all tables defined in a module's hook_schema(). * * Note: This function does not pass the module's schema through * hook_schema_alter(). The module's tables will be created exactly as the @@ -6651,7 +6759,7 @@ function drupal_install_schema($module) { } /** - * Remove all tables that a module defines in its hook_schema(). + * Removes all tables defined in a module's hook_schema(). * * Note: This function does not pass the module's schema through * hook_schema_alter(). The module's tables will be created exactly as the @@ -6659,6 +6767,7 @@ function drupal_install_schema($module) { * * @param $module * The module for which the tables will be removed. + * * @return * An array of arrays with the following key/value pairs: * - success: a boolean indicating whether the query succeeded. @@ -6714,7 +6823,7 @@ function drupal_get_schema_unprocessed($module, $table = NULL) { } /** - * Fill in required default values for table definitions returned by hook_schema(). + * Fills in required default values for table definitions from hook_schema(). * * @param $schema * The schema definition array as it was returned by the module's @@ -6745,7 +6854,9 @@ function _drupal_schema_initialize(&$schema, $module, $remove_descriptions = TRU } /** - * Retrieve a list of fields from a table schema. The list is suitable for use in a SQL query. + * Retrieves a list of fields from a table schema. + * + * The returned list is suitable for use in a SQL query. * * @param $table * The name of the table from which to retrieve fields. @@ -6779,9 +6890,9 @@ function drupal_schema_fields_sql($table, $prefix = NULL) { * An object or array representing the record to write, passed in by * reference. If inserting a new record, values not provided in $record will * be populated in $record and in the database with the default values from - * the schema, as well as a single serial (auto-increment) field (if present). - * If updating an existing record, only provided values are updated in the - * database, and $record is not modified. + * the schema, as well as a single serial (auto-increment) field (if + * present). If updating an existing record, only provided values are + * updated in the database, and $record is not modified. * @param $primary_keys * To indicate that this is a new record to be inserted, omit this argument. * If this is an update, this argument specifies the primary keys' field @@ -6939,7 +7050,8 @@ function drupal_write_record($table, &$record, $primary_keys = array()) { * Information stored in a module .info file: * - name: The real name of the module for display purposes. * - description: A brief description of the module. - * - dependencies: An array of shortnames of other modules this module requires. + * - dependencies: An array of shortnames of other modules this module + * requires. * - package: The name of the package of modules this module belongs to. * * See forum.info for an example of a module .info file. @@ -6981,7 +7093,7 @@ function drupal_parse_info_file($filename) { } /** - * Parse data in Drupal's .info format. + * Parses data in Drupal's .info format. * * Data should be in an .ini-like format to specify values. White-space * generally doesn't matter, except inside values: @@ -7011,6 +7123,7 @@ function drupal_parse_info_file($filename) { * * @param $data * A string to parse. + * * @return * The info array. * @@ -7074,11 +7187,12 @@ function drupal_parse_info_format($data) { } /** - * Severity levels, as defined in RFC 3164: http://www.ietf.org/rfc/rfc3164.txt. + * Returns a list of severity levels, as defined in RFC 3164. * * @return * Array of the possible severity levels for log messages. * + * @see http://www.ietf.org/rfc/rfc3164.txt * @see watchdog() * @ingroup logging_severity_levels */ @@ -7097,7 +7211,7 @@ function watchdog_severity_levels() { /** - * Explode a string of given tags into an array. + * Explodes a string of tags into an array. * * @see drupal_implode_tags() */ @@ -7123,7 +7237,7 @@ function drupal_explode_tags($tags) { } /** - * Implode an array of tags into a string. + * Implodes an array of tags into a string. * * @see drupal_explode_tags() */ @@ -7141,7 +7255,7 @@ function drupal_implode_tags($tags) { } /** - * Flush all cached data on the site. + * Flushes all cached data on the site. * * Empties cache tables, rebuilds the menu cache and theme registries, and * invokes a hook so that other modules' cache data can be cleared as well. @@ -7182,10 +7296,10 @@ function drupal_flush_all_caches() { } /** - * Helper function to change query-strings on css/js files. + * Changes the dummy query string added to all CSS and JavaScript files. * - * Changes the character added to all css/js files as dummy query-string, so - * that all browsers are forced to reload fresh files. + * Changing the dummy query string appended to CSS and JavaScript files forces + * all browsers to reload fresh files. */ function _drupal_flush_css_js() { // The timestamp is converted to base 36 in order to make it more compact. @@ -7193,7 +7307,7 @@ function _drupal_flush_css_js() { } /** - * Debug function used for outputting debug information. + * Outputs debug information. * * The debug information is passed on to trigger_error() after being converted * to a string using _drupal_debug_message(). @@ -7218,10 +7332,11 @@ function debug($data, $label = NULL, $print_r = FALSE) { } /** - * Parse a dependency for comparison by drupal_check_incompatibility(). + * Parses a dependency for comparison by drupal_check_incompatibility(). * * @param $dependency * A dependency string, for example 'foo (>=8.x-4.5-beta5, 3.x)'. + * * @return * An associative array with three keys: * - 'name' includes the name of the thing to depend on (e.g. 'foo'). @@ -7275,12 +7390,13 @@ function drupal_parse_dependency($dependency) { } /** - * Check whether a version is compatible with a given dependency. + * Checks whether a version is compatible with a given dependency. * * @param $v * The parsed dependency structure from drupal_parse_dependency(). * @param $current_version * The version to check against (like 4.2). + * * @return * NULL if compatible, otherwise the original dependency version string that * caused the incompatibility. @@ -7378,11 +7494,12 @@ function archiver_get_extensions() { } /** - * Create the appropriate archiver for the specified file. + * Creates the appropriate archiver for the specified file. * * @param $file * The full path of the archive file. Note that stream wrapper * paths are supported, but not remote ones. + * * @return * A newly created instance of the archiver class appropriate * for the specified file, already bound to that file. @@ -7411,14 +7528,14 @@ function archiver_get_archiver($file) { } /** - * Drupal Updater registry. + * Assembles the Drupal Updater registry. * * An Updater is a class that knows how to update various parts of the Drupal * file system, for example to update modules that have newer releases, or to * install a new theme. * * @return - * Returns the Drupal Updater class registry. + * The Drupal Updater class registry. * * @see hook_updater_info() * @see hook_updater_info_alter() @@ -7434,10 +7551,10 @@ function drupal_get_updaters() { } /** - * Drupal FileTransfer registry. + * Assembles Drupal FileTransfer registry. * * @return - * Returns the Drupal FileTransfer class registry. + * The Drupal FileTransfer class registry. * * @see FileTransfer * @see hook_filetransfer_info()