From 9727bd093b417e67be028f2acf94648e53049095 Mon Sep 17 00:00:00 2001
From: catch <catch@35733.no-reply.drupal.org>
Date: Mon, 5 Dec 2011 21:52:27 +0900
Subject: [PATCH] Issue #1315886 by xjm: Clean up API docs for includes
directory, files starting with A-C.
---
core/includes/actions.inc | 14 +-
core/includes/ajax.inc | 43 ++-
core/includes/archiver.inc | 19 +-
core/includes/authorize.inc | 26 +-
core/includes/batch.inc | 30 +-
core/includes/batch.queue.inc | 35 +-
core/includes/bootstrap.inc | 228 +++++++------
core/includes/cache-install.inc | 21 +-
core/includes/cache.inc | 155 +++++++--
core/includes/common.inc | 569 +++++++++++++++++++-------------
10 files changed, 726 insertions(+), 414 deletions(-)
diff --git a/core/includes/actions.inc b/core/includes/actions.inc
index 760de8300b38..0414867e87ff 100644
--- a/core/includes/actions.inc
+++ b/core/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,9 +178,9 @@ 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
+ * 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
@@ -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
@@ -223,7 +226,7 @@ function actions_actions_map($actions) {
}
/**
- * Given a hash of an action array key, returns the key (function or ID).
+ * Returns an action array key (function or ID), given its hash.
*
* Faster than actions_actions_map() when you only need the function name or ID.
*
@@ -231,6 +234,7 @@ function actions_actions_map($actions) {
* 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 +336,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 +366,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/core/includes/ajax.inc b/core/includes/ajax.inc
index cda55b424663..693fe3a2a0af 100644
--- a/core/includes/ajax.inc
+++ b/core/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
@@ -101,7 +102,7 @@
* In the above example, the 'changethis' element is Ajax-enabled. The default
* #ajax['event'] is 'change', so when the 'changethis' element changes,
* an Ajax call is made. The form is submitted and reprocessed, and then the
- * callback is called. In this case, the form has been automatically
+ * callback is called. In this case, the form has been automatically
* built changing $form['replace_textfield']['#description'], so the callback
* just returns that part of the form.
*
@@ -188,11 +189,11 @@
* 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 +223,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 +302,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,7 +349,9 @@ 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
@@ -361,6 +364,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,7 +386,12 @@ 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
@@ -396,6 +406,9 @@ function ajax_form_callback() {
* 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 +427,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 +560,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 +583,7 @@ function ajax_footer() {
}
/**
- * Form element process callback to handle #ajax.
+ * Form element processing handler for the #ajax form property.
*
* @param $element
* An associative array containing the properties of the element.
@@ -589,7 +602,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
diff --git a/core/includes/archiver.inc b/core/includes/archiver.inc
index fec053be6233..2db2db15a293 100644
--- a/core/includes/archiver.inc
+++ b/core/includes/archiver.inc
@@ -6,43 +6,45 @@
*/
/**
- * 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
- * are supported. If the file does not yet exist, it will be created if
+ * The full system path of the archive to manipulate. Only local files
+ * are supported. If the file does not yet exist, it will be created if
* appropriate.
*/
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 @@ public function remove($path);
* 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/core/includes/authorize.inc b/core/includes/authorize.inc
index 862992f61317..21e9a11488e5 100644
--- a/core/includes/authorize.inc
+++ b/core/includes/authorize.inc
@@ -6,7 +6,13 @@
*/
/**
- * 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.
+ *
+ * @see authorize_filetransfer_form_validate()
+ * @see authorize_filetransfer_form_submit()
+ * @ingroup forms
*/
function authorize_filetransfer_form($form, &$form_state) {
global $base_url, $is_https;
@@ -127,10 +133,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 +158,7 @@ function _authorize_filetransfer_connection_settings($backend) {
}
/**
- * Recursively fill in the default settings on a file transfer connection form.
+ * Sets the default settings on a file transfer connection form recursively.
*
* 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 +172,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,9 +191,10 @@ function _authorize_filetransfer_connection_settings_set_defaults(&$element, $ke
}
/**
- * Validate callback for the filetransfer authorization form.
+ * Form validation handler for authorize_filetransfer_form().
*
* @see authorize_filetransfer_form()
+ * @see authorize_filetransfer_submit()
*/
function authorize_filetransfer_form_validate($form, &$form_state) {
// Only validate the form if we have collected all of the user input and are
@@ -218,9 +224,10 @@ 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()
+ * @see authorize_filetransfer_validate()
*/
function authorize_filetransfer_form_submit($form, &$form_state) {
global $base_url;
@@ -280,7 +287,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 +305,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/core/includes/batch.inc b/core/includes/batch.inc
index 513a8f9ad0d4..15129a41d0e5 100644
--- a/core/includes/batch.inc
+++ b/core/includes/batch.inc
@@ -1,6 +1,5 @@
<?php
-
/**
* @file
* Batch processing API for processes to run in multiple HTTP requests.
@@ -21,6 +20,7 @@
* @param $id
* The ID of the batch to load. When a progressive batch is being processed,
* the relevant ID is found in $_REQUEST['id'].
+ *
* @return
* An array representing the batch, or FALSE if no batch was found.
*/
@@ -36,7 +36,7 @@ function batch_load($id) {
}
/**
- * State-based dispatcher for the batch processing page.
+ * Renders the batch processing page based on the current state of the batch.
*
* @see _batch_shutdown()
*/
@@ -94,7 +94,7 @@ function _batch_page() {
}
/**
- * Initialize the batch processing.
+ * Initializes the batch processing.
*
* JavaScript-enabled clients are identified by the 'has_js' cookie set in
* drupal.js. If no JavaScript-enabled page has been visited during the current
@@ -110,7 +110,7 @@ function _batch_start() {
}
/**
- * Output a batch processing page with JavaScript support.
+ * Outputs a batch processing page with JavaScript support.
*
* This initializes the batch and error messages. Note that in JavaScript-based
* processing, the batch processing page is displayed only once and updated via
@@ -144,7 +144,7 @@ function _batch_progress_page_js() {
}
/**
- * Do one execution pass in JavaScript-mode and return progress to the browser.
+ * Does one execution pass with JavaScript and returns progress to the browser.
*
* @see _batch_progress_page_js()
* @see _batch_process()
@@ -164,7 +164,7 @@ function _batch_do() {
}
/**
- * Output a batch processing page without JavaScript support.
+ * Outputs a batch processing page without JavaScript support.
*
* @see _batch_process()
*/
@@ -228,7 +228,7 @@ function _batch_progress_page_nojs() {
}
/**
- * Process sets in a batch.
+ * Processes sets in a batch.
*
* If the batch was marked for progressive execution (default), this executes as
* many operations in batch sets until an execution time of 1 second has been
@@ -370,7 +370,7 @@ function _batch_process() {
}
/**
- * Helper function for _batch_process(): returns the formatted percentage.
+ * Formats the percent completion for a batch set.
*
* @param $total
* The total number of operations.
@@ -379,11 +379,14 @@ function _batch_process() {
* rather than an integer in the case of a multi-step operation that is not
* yet complete; in that case, the fractional part of $current represents the
* fraction of the operation that has been completed.
+ *
* @return
* The properly formatted percentage, as a string. We output percentages
* using the correct number of decimal places so that we never print "100%"
* until we are finished, but we also never print more decimal places than
* are meaningful.
+ *
+ * @see _batch_process()
*/
function _batch_api_percentage($total, $current) {
if (!$total || $total == $current) {
@@ -410,7 +413,7 @@ function _batch_api_percentage($total, $current) {
}
/**
- * Return the batch set being currently processed.
+ * Returns the batch set being currently processed.
*/
function &_batch_current_set() {
$batch = &batch_get();
@@ -418,7 +421,7 @@ function &_batch_current_set() {
}
/**
- * Retrieve the next set in a batch.
+ * Retrieves the next set in a batch.
*
* If there is a subsequent set in this batch, assign it as the new set to
* process and execute its form submit handler (if defined), which may add
@@ -442,7 +445,7 @@ function _batch_next_set() {
}
/**
- * End the batch processing.
+ * Ends the batch processing.
*
* Call the 'finished' callback of each batch set to allow custom handling of
* the results and resolve page redirection.
@@ -521,7 +524,10 @@ function _batch_finished() {
}
/**
- * Shutdown function; store the current batch data for the next request.
+ * Shutdown function: Stores the current batch data for the next request.
+ *
+ * @see _batch_page()
+ * @see drupal_register_shutdown_function()
*/
function _batch_shutdown() {
if ($batch = batch_get()) {
diff --git a/core/includes/batch.queue.inc b/core/includes/batch.queue.inc
index 8464836987b7..ed290ee70f00 100644
--- a/core/includes/batch.queue.inc
+++ b/core/includes/batch.queue.inc
@@ -1,24 +1,30 @@
<?php
-
/**
* @file
* Queue handlers used by the Batch API.
*
- * Those implementations:
- * - ensure FIFO ordering,
- * - let an item be repeatedly claimed until it is actually deleted (no notion
- * of lease time or 'expire' date), to allow multipass operations.
+ * These implementations:
+ * - Ensure FIFO ordering.
+ * - Allow an item to be repeatedly claimed until it is actually deleted (no
+ * notion of lease time or 'expire' date), to allow multipass operations.
*/
/**
- * Batch queue implementation.
+ * Defines a batch queue.
*
* Stale items from failed batches are cleaned from the {queue} table on cron
* using the 'created' date.
*/
class BatchQueue extends SystemQueue {
+ /**
+ * Overrides SystemQueue::claimItem().
+ *
+ * Unlike SystemQueue::claimItem(), this method provides a default lease
+ * time of 0 (no expiration) instead of 30. This allows the item to be
+ * claimed repeatedly until it is deleted.
+ */
public function claimItem($lease_time = 0) {
$item = db_query_range('SELECT data, item_id FROM {queue} q WHERE name = :name ORDER BY item_id ASC', 0, 1, array(':name' => $this->name))->fetchObject();
if ($item) {
@@ -29,9 +35,9 @@ public function claimItem($lease_time = 0) {
}
/**
- * 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();
@@ -44,10 +50,17 @@ public function getAllItems() {
}
/**
- * Batch queue implementation used for non-progressive batches.
+ * Defines a batch queue for non-progressive batches.
*/
class BatchMemoryQueue extends MemoryQueue {
+ /**
+ * Overrides MemoryQueue::claimItem().
+ *
+ * Unlike MemoryQueue::claimItem(), this method provides a default lease
+ * time of 0 (no expiration) instead of 30. This allows the item to be
+ * claimed repeatedly until it is deleted.
+ */
public function claimItem($lease_time = 0) {
if (!empty($this->queue)) {
reset($this->queue);
@@ -57,9 +70,9 @@ public function claimItem($lease_time = 0) {
}
/**
- * 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/core/includes/bootstrap.inc b/core/includes/bootstrap.inc
index 4d298eacaf92..8fa8a25121ad 100644
--- a/core/includes/bootstrap.inc
+++ b/core/includes/bootstrap.inc
@@ -43,9 +43,9 @@
* 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
+ * 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
+ * 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."
*
@@ -137,8 +137,7 @@
const 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.
*/
const DRUPAL_BOOTSTRAP_FULL = 7;
@@ -153,8 +152,9 @@
const 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.
*/
const DRUPAL_KILOBYTE = 1024;
@@ -314,7 +314,7 @@ abstract class DrupalCacheArray implements ArrayAccess {
protected $storage = array();
/**
- * Constructor.
+ * Constructs a DrupalCacheArray object.
*
* @param $cid
* The cid for the array being cached.
@@ -330,10 +330,16 @@ public function __construct($cid, $bin) {
}
}
+ /**
+ * Implements ArrayAccess::offsetExists().
+ */
public function offsetExists($offset) {
return $this->offsetGet($offset) !== NULL;
}
+ /**
+ * Implements ArrayAccess::offsetGet().
+ */
public function offsetGet($offset) {
if (isset($this->storage[$offset]) || array_key_exists($offset, $this->storage)) {
return $this->storage[$offset];
@@ -343,10 +349,16 @@ public function offsetGet($offset) {
}
}
+ /**
+ * Implements ArrayAccess::offsetSet().
+ */
public function offsetSet($offset, $value) {
$this->storage[$offset] = $value;
}
+ /**
+ * Implements ArrayAccess::offsetUnset().
+ */
public function offsetUnset($offset) {
unset($this->storage[$offset]);
}
@@ -386,7 +398,7 @@ protected function persist($offset, $persist = TRUE) {
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.
@@ -412,6 +424,9 @@ protected function set($cid, $data, $bin, $lock = TRUE) {
}
}
+ /**
+ * Destructs the DrupalCacheArray object.
+ */
public function __destruct() {
$data = array();
foreach ($this->keysToPersist as $offset => $persist) {
@@ -426,8 +441,10 @@ public function __destruct() {
}
/**
- * 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.
@@ -440,7 +457,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.
@@ -464,7 +481,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.
@@ -613,7 +630,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.
@@ -675,7 +692,7 @@ function drupal_override_server_variables($variables = array()) {
}
/**
- * Initialize PHP environment.
+ * Initializes the PHP environment.
*/
function drupal_environment_initialize() {
if (!isset($_SERVER['HTTP_REFERER'])) {
@@ -734,7 +751,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.
@@ -744,8 +761,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;
@@ -839,9 +855,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
@@ -943,11 +960,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
@@ -1054,7 +1071,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
@@ -1086,7 +1103,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.
@@ -1105,7 +1122,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.
@@ -1127,8 +1144,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).
@@ -1160,7 +1178,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).
@@ -1196,11 +1214,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.
@@ -1217,6 +1236,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).
*/
@@ -1230,9 +1251,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.
@@ -1267,7 +1289,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
@@ -1310,7 +1332,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
@@ -1413,7 +1435,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');
@@ -1530,7 +1552,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.
@@ -1572,7 +1594,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.
@@ -1611,6 +1633,7 @@ function check_plain($text) {
*
* @param $text
* The text to check.
+ *
* @return
* TRUE if the text is valid UTF-8, FALSE if not.
*/
@@ -1652,7 +1675,7 @@ function request_uri() {
}
/**
- * Log an exception.
+ * Logs an exception.
*
* This is a wrapper function for watchdog() which automatically decodes an
* exception.
@@ -1693,7 +1716,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
@@ -1753,7 +1776,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.
@@ -1789,12 +1812,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,
@@ -1822,7 +1846,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.
@@ -1839,7 +1865,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
@@ -1864,7 +1892,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
@@ -1873,6 +1901,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.
*/
@@ -1898,7 +1927,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.
@@ -1917,7 +1946,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.
@@ -1964,7 +1994,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.
@@ -1982,7 +2012,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.
@@ -2086,20 +2116,22 @@ 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 an integer constant identifying 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. To access the Drupal
+ * database from a script without loading anything else, 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.
@@ -2178,7 +2210,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;
@@ -2193,7 +2225,7 @@ function drupal_get_user_timezone() {
}
/**
- * Custom PHP error handler.
+ * Provides custom PHP error handling.
*
* @param $error_level
* The level of the error raised.
@@ -2204,7 +2236,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 . '/core/includes/errors.inc';
@@ -2212,7 +2245,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
@@ -2240,7 +2273,7 @@ function _drupal_exception_handler($exception) {
}
/**
- * Bootstrap configuration: Setup script environment and load settings.php.
+ * Sets up the script environment and loads settings.php.
*/
function _drupal_bootstrap_configuration() {
// Set the Drupal custom error handler.
@@ -2289,7 +2322,7 @@ function _drupal_bootstrap_configuration() {
}
/**
- * Bootstrap page cache: Try to serve a page from cache.
+ * Attempts to serve a page from the cache.
*/
function _drupal_bootstrap_page_cache() {
global $user;
@@ -2345,7 +2378,7 @@ function _drupal_bootstrap_page_cache() {
}
/**
- * Bootstrap database: Initialize database system and register autoload functions.
+ * Initializes the database system and registers autoload functions.
*/
function _drupal_bootstrap_database() {
// Redirect the user to the installation script if Drupal has not been
@@ -2397,7 +2430,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;
@@ -2414,7 +2447,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');
@@ -2437,8 +2470,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
@@ -2474,7 +2506,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;
@@ -2534,7 +2566,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';
@@ -2577,7 +2609,7 @@ function get_t() {
}
/**
- * Initialize all the defined language types.
+ * Initializes all the defined language types.
*/
function drupal_language_initialize() {
$types = language_types();
@@ -2602,7 +2634,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
@@ -2617,7 +2649,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
@@ -2627,7 +2659,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()));
@@ -2684,7 +2716,7 @@ function language_list($field = 'language') {
}
/**
- * Default language used on the site.
+ * Returns the default language used on the site.
*
* @return
* A language object.
@@ -2764,16 +2796,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 '/'
@@ -2813,6 +2845,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
@@ -2862,7 +2896,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().
@@ -2898,11 +2932,17 @@ 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');
}
+ /**
+ * Overrides DrupalCacheArray::resolveCacheMiss().
+ */
protected function resolveCacheMiss($offset) {
$complete_schema = drupal_get_complete_schema();
$value = isset($complete_schema[$offset]) ? $complete_schema[$offset] : NULL;
@@ -2913,7 +2953,7 @@ protected function resolveCacheMiss($offset) {
}
/**
- * 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().
@@ -2983,13 +3023,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.
*/
@@ -2998,13 +3039,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.
*/
@@ -3013,7 +3055,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
@@ -3022,6 +3064,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.
@@ -3093,7 +3136,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.
@@ -3104,7 +3147,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
@@ -3122,7 +3165,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
@@ -3273,7 +3316,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.
@@ -3283,7 +3326,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)));
@@ -3291,7 +3334,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).
@@ -3304,7 +3348,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".
@@ -3339,7 +3383,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/core/includes/cache-install.inc b/core/includes/cache-install.inc
index 8bcf8b7b1c17..ec46ae0126cb 100644
--- a/core/includes/cache-install.inc
+++ b/core/includes/cache-install.inc
@@ -6,7 +6,7 @@
*/
/**
- * A stub cache implementation to be used during the installation process.
+ * Defines a stub cache implementation to be used during installation.
*
* The stub implementation is needed when database access is not yet available.
* Because Drupal's caching system never requires that cached data be present,
@@ -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) {
}
+ /**
+ * Implements DrupalCacheInterface::deletePrefix().
+ */
function deletePrefix($cid) {
try {
if (class_exists('Database')) {
@@ -36,6 +49,9 @@ function deletePrefix($cid) {
}
}
+ /**
+ * 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 @@ function clear($cid = NULL, $wildcard = FALSE) {
}
}
+ /**
+ * Overrides DrupalDatabaseCache::isEmpty().
+ */
function isEmpty() {
return TRUE;
}
diff --git a/core/includes/cache.inc b/core/includes/cache.inc
index fcf3e5e5187f..5d82fa0d91b6 100644
--- a/core/includes/cache.inc
+++ b/core/includes/cache.inc
@@ -1,19 +1,25 @@
<?php
/**
- * Factory for instantiating and statically caching the correct class for a cache bin.
+ * @file
+ * Functions and interfaces for cache handling.
+ */
+
+/**
+ * Instantiates and statically caches the correct class for a cache bin.
*
* By default, this returns an instance of the DrupalDatabaseCache class.
* Classes implementing DrupalCacheInterface can register themselves both as a
* default implementation and for specific bins.
*
- * @see DrupalCacheInterface
- *
* @param $bin
* The cache bin for which the cache object should be returned, defaults to
* 'cache'.
+ *
* @return DrupalCacheInterface
* The cache object associated with the specified bin.
+ *
+ * @see DrupalCacheInterface
*/
function cache($bin = 'cache') {
// Temporary backwards compatibiltiy layer, allow old style prefixed cache
@@ -34,7 +40,7 @@ function cache($bin = 'cache') {
}
/**
- * Return data from the persistent cache
+ * Returns data from the persistent cache.
*
* Data may be stored as either plain text or as serialized data. cache_get
* will automatically return unserialized objects and arrays.
@@ -55,13 +61,14 @@ function cache_get($cid, $bin = 'cache') {
}
/**
- * Return data from the persistent cache when given an array of cache IDs.
+ * Returns data from the persistent cache when given an array of cache IDs.
*
* @param $cids
* An array of cache IDs for the data to retrieve. This is passed by
* reference, and will have the IDs successfully returned from cache removed.
* @param $bin
* The cache bin where the data is stored.
+ *
* @return
* An array of the items successfully returned from cache indexed by cid.
*/
@@ -70,7 +77,7 @@ function cache_get_multiple(array &$cids, $bin = 'cache') {
}
/**
- * Store data in the persistent cache.
+ * Stores data in the persistent cache.
*
* The persistent cache is split up into several cache bins. In the default
* cache implementation, each cache bin corresponds to a database table by the
@@ -143,7 +150,7 @@ function cache_set($cid, $data, $bin = 'cache', $expire = CACHE_PERMANENT) {
}
/**
- * Expire data from the cache.
+ * Expires data from the cache.
*
* If called without arguments, expirable entries will be cleared from the
* cache_page and cache_block bins.
@@ -151,15 +158,12 @@ function cache_set($cid, $data, $bin = 'cache', $expire = CACHE_PERMANENT) {
* @param $cid
* If set, the cache ID to delete. Otherwise, all cache entries that can
* expire are deleted.
- *
* @param $bin
- * If set, the bin $bin to delete from. Mandatory
- * argument if $cid is set.
- *
+ * If set, the cache bin to delete from. Mandatory argument if $cid is set.
* @param $wildcard
- * If $wildcard is TRUE, cache IDs starting with $cid are deleted in
- * addition to the exact cache ID specified by $cid. If $wildcard is
- * TRUE and $cid is '*' then the entire bin $bin is emptied.
+ * If TRUE, cache IDs starting with $cid are deleted in addition to the
+ * exact cache ID specified by $cid. If $wildcard is TRUE and $cid is '*',
+ * the entire cache bin is emptied.
*/
function cache_clear_all($cid = NULL, $bin = NULL, $wildcard = FALSE) {
if (!isset($cid) && !isset($bin)) {
@@ -175,13 +179,14 @@ function cache_clear_all($cid = NULL, $bin = NULL, $wildcard = FALSE) {
}
/**
- * Check if a cache bin is empty.
+ * Checks if a cache bin is empty.
*
* A cache bin is considered empty if it does not contain any valid data for any
* cache ID.
*
* @param $bin
* The cache bin to check.
+ *
* @return
* TRUE if the cache bin specified is empty.
*/
@@ -190,7 +195,7 @@ function cache_is_empty($bin) {
}
/**
- * Interface for cache implementations.
+ * Defines an interface for cache implementations.
*
* All cache implementations have to implement this interface.
* DrupalDatabaseCache provides the default implementation, which can be
@@ -228,7 +233,7 @@ function cache_is_empty($bin) {
*/
interface DrupalCacheInterface {
/**
- * Constructor.
+ * Constructs a new cache interface.
*
* @param $bin
* The cache bin for which the object is created.
@@ -236,31 +241,34 @@ interface DrupalCacheInterface {
function __construct($bin);
/**
- * Return data from the persistent cache. Data may be stored as either plain
- * text or as serialized data. cache_get will automatically return
- * unserialized objects and arrays.
+ * Returns data from the persistent cache.
+ *
+ * Data may be stored as either plain text or as serialized data. cache_get()
+ * will automatically return unserialized objects and arrays.
*
* @param $cid
* The cache ID of the data to retrieve.
+ *
* @return
* The cache or FALSE on failure.
*/
function get($cid);
/**
- * Return data from the persistent cache when given an array of cache IDs.
+ * Returns data from the persistent cache when given an array of cache IDs.
*
* @param $cids
* An array of cache IDs for the data to retrieve. This is passed by
* reference, and will have the IDs successfully returned from cache
* removed.
+ *
* @return
* An array of the items successfully returned from cache indexed by cid.
*/
function getMultiple(&$cids);
/**
- * Store data in the persistent cache.
+ * Stores data in the persistent cache.
*
* @param $cid
* The cache ID of the data to store.
@@ -280,7 +288,7 @@ function getMultiple(&$cids);
function set($cid, $data, $expire = CACHE_PERMANENT);
/**
- * Delete an item from the cache.
+ * Deletes an item from the cache.
*
* @param $cid
* The cache ID to delete.
@@ -288,7 +296,7 @@ function set($cid, $data, $expire = CACHE_PERMANENT);
function delete($cid);
/**
- * Delete multiple items from the cache.
+ * Deletes multiple items from the cache.
*
* @param $cids
* An array of $cids to delete.
@@ -296,7 +304,7 @@ function delete($cid);
function deleteMultiple(Array $cids);
/**
- * Delete items from the cache using a wildcard prefix.
+ * Deletes items from the cache using a wildcard prefix.
*
* @param $prefix
* A wildcard prefix.
@@ -304,23 +312,25 @@ function deleteMultiple(Array $cids);
function deletePrefix($prefix);
/**
- * Flush all cache items in a bin.
+ * Flushes all cache items in a bin.
*/
function flush();
/**
- * Expire temporary items from cache.
+ * Expires temporary items from the cache.
*/
function expire();
/**
- * Perform garbage collection on a cache bin.
+ * Performs garbage collection on a cache bin.
*/
function garbageCollection();
/**
- * Expire data from the cache. If called without arguments, expirable
- * entries will be cleared from the cache_page and cache_block bins.
+ * Expires data from the cache.
+ *
+ * If called without arguments, expirable entries will be cleared from the
+ * cache_page and cache_block bins.
*
* @param $cid
* If set, the cache ID to delete. Otherwise, all cache entries that can
@@ -330,13 +340,13 @@ function garbageCollection();
* to match rather than a complete ID. The match is a right hand
* match. If '*' is given as $cid, the bin $bin will be emptied.
*
- * @todo: this method is deprecated, as it's functionality is covered by
- * more targeted methods in the interface.
+ * @todo: This method is deprecated, as its functionality is covered by more
+ * targeted methods in the interface.
*/
function clear($cid = NULL, $wildcard = FALSE);
/**
- * Check if a cache bin is empty.
+ * Checks if a cache bin is empty.
*
* A cache bin is considered empty if it does not contain any valid data for
* any cache ID.
@@ -348,7 +358,7 @@ function isEmpty();
}
/**
- * A stub cache implementation.
+ * Defines a stub cache implementation.
*
* The stub implementation is needed when database access is not yet available.
* Because Drupal's caching system never requires that cached data be present,
@@ -360,39 +370,75 @@ function isEmpty();
*/
class DrupalNullCache implements DrupalCacheInterface {
+ /**
+ * Constructs a DrupalNullCache object.
+ */
function __construct($bin) {}
+ /**
+ * Implements DrupalCacheInterface::get().
+ */
function get($cid) {
return FALSE;
}
+ /**
+ * Implements DrupalCacheInterface::getMultiple().
+ */
function getMultiple(&$cids) {
return array();
}
+ /**
+ * Implements DrupalCacheInterface::set().
+ */
function set($cid, $data, $expire = CACHE_PERMANENT) {}
+ /**
+ * Implements DrupalCacheInterface::delete().
+ */
function delete($cid) {}
+ /**
+ * Implements DrupalCacheInterface::deleteMultiple().
+ */
function deleteMultiple(array $cids) {}
+ /**
+ * Implements DrupalCacheInterface::deletePrefix().
+ */
function deletePrefix($prefix) {}
+ /**
+ * Implements DrupalCacheInterface::flush().
+ */
function flush() {}
+ /**
+ * Implements DrupalCacheInterface::expire().
+ */
function expire() {}
+ /**
+ * Implements DrupalCacheInterface::garbageCollection().
+ */
function garbageCollection() {}
+ /**
+ * Implements DrupalCacheInterface::clear().
+ */
function clear($cid = NULL, $wildcard = FALSE) {}
+ /**
+ * Implements DrupalCacheInterface::isEmpty().
+ */
function isEmpty() {
return TRUE;
}
}
/**
- * Default cache implementation.
+ * Defines a default cache implementation.
*
* This is Drupal's default cache implementation. It uses the database to store
* cached data. Each cache bin corresponds to a database table by the same name.
@@ -400,6 +446,9 @@ function isEmpty() {
class DrupalDatabaseCache implements DrupalCacheInterface {
protected $bin;
+ /**
+ * Constructs a new DrupalDatabaseCache object.
+ */
function __construct($bin) {
// All cache tables should be prefixed with 'cache_', apart from the
// default 'cache' bin, which would look silly.
@@ -409,12 +458,18 @@ function __construct($bin) {
$this->bin = $bin;
}
+ /**
+ * Implements DrupalCacheInterface::get().
+ */
function get($cid) {
$cids = array($cid);
$cache = $this->getMultiple($cids);
return reset($cache);
}
+ /**
+ * Implements DrupalCacheInterface::getMultiple().
+ */
function getMultiple(&$cids) {
try {
// Garbage collection necessary when enforcing a minimum cache lifetime.
@@ -446,13 +501,14 @@ function getMultiple(&$cids) {
}
/**
- * 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 +537,9 @@ protected function prepareItem($cache) {
return $cache;
}
+ /**
+ * Implements DrupalCacheInterface::set().
+ */
function set($cid, $data, $expire = CACHE_PERMANENT) {
$fields = array(
'serialized' => 0,
@@ -507,12 +566,18 @@ function set($cid, $data, $expire = CACHE_PERMANENT) {
}
}
+ /**
+ * Implements DrupalCacheInterface::delete().
+ */
function delete($cid) {
db_delete($this->bin)
->condition('cid', $cid)
->execute();
}
+ /**
+ * Implements DrupalCacheInterface::deleteMultiple().
+ */
function deleteMultiple(Array $cids) {
// Delete in chunks when a large array is passed.
do {
@@ -523,16 +588,25 @@ function deleteMultiple(Array $cids) {
while (count($cids));
}
+ /**
+ * Implements DrupalCacheInterface::deletePrefix().
+ */
function deletePrefix($prefix) {
db_delete($this->bin)
->condition('cid', db_like($prefix) . '%', 'LIKE')
->execute();
}
+ /**
+ * Implements DrupalCacheInterface::flush().
+ */
function flush() {
db_truncate($this->bin)->execute();
}
+ /**
+ * Implements 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 +639,9 @@ function expire() {
}
}
+ /**
+ * Implements DrupalCacheInterface::garbageCollection().
+ */
function garbageCollection() {
global $user;
@@ -582,6 +659,9 @@ function garbageCollection() {
}
}
+ /**
+ * Implements DrupalCacheInterface::clear().
+ */
function clear($cid = NULL, $wildcard = FALSE) {
global $user;
@@ -606,6 +686,9 @@ function clear($cid = NULL, $wildcard = FALSE) {
}
}
+ /**
+ * Implements DrupalCacheInterface::isEmpty().
+ */
function isEmpty() {
$this->garbageCollection();
$query = db_select($this->bin);
diff --git a/core/includes/common.inc b/core/includes/common.inc
index 551cc5c0a397..4f78db13d375 100644
--- a/core/includes/common.inc
+++ b/core/includes/common.inc
@@ -70,8 +70,7 @@
const CSS_THEME = 100;
/**
- * The default group for JavaScript libraries or jQuery plugins added
- * to the page.
+ * The default group for JavaScript and jQuery libraries added to the page.
*/
const JS_LIBRARY = -100;
@@ -91,8 +90,9 @@
const JS_SETTING = 200;
/**
- * 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()
*/
const HTTP_REQUEST_TIMEOUT = -1;
@@ -115,31 +115,36 @@
*/
/**
- * 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.
- * - for blocks that change too frequently.
+ * 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.
+ * - For blocks that change too frequently.
*/
const 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.
*/
const 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.
*/
const 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.
*/
@@ -151,12 +156,12 @@
const 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.
*/
const 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.
@@ -173,7 +178,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
@@ -199,13 +204,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.
@@ -225,7 +230,7 @@ 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
@@ -241,7 +246,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();
@@ -254,7 +259,7 @@ function drupal_get_breadcrumb() {
}
/**
- * 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 as the headers aren't sent. Pass no
* arguments (or NULL for both) to retrieve the currently stored elements.
@@ -321,7 +326,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();
@@ -330,7 +335,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.
*
@@ -358,7 +363,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.
@@ -375,7 +380,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.
@@ -420,7 +425,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.
@@ -440,7 +445,7 @@ 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.
@@ -481,7 +486,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
@@ -512,7 +517,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
@@ -609,7 +614,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.
@@ -675,7 +680,7 @@ 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,
@@ -687,7 +692,7 @@ function drupal_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,
@@ -699,19 +704,20 @@ function drupal_not_found() {
}
/**
- * Deliver a "access denied" error to the browser.
+ * Delivers an "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().
+ * 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.
@@ -1012,6 +1018,14 @@ function drupal_http_request($url, array $options = array()) {
* @} End of "HTTP handling".
*/
+/**
+ * Strips slashes from a string or array of strings.
+ *
+ * Callback for array_walk() within fix_gpx_magic().
+ *
+ * @param $item
+ * An individual string or array of strings from superglobals.
+ */
function _fix_gpc_magic(&$item) {
if (is_array($item)) {
array_walk($item, '_fix_gpc_magic');
@@ -1022,11 +1036,19 @@ 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.
+ * Strips slashes from $_FILES items.
+ *
+ * Callback for array_walk() within fix_gpc_magic().
*
- * tmp_name does not have backslashes added see
- * http://php.net/manual/en/features.file-upload.php#42280
+ * The tmp_name key is skipped keys since PHP generates single backslashes for
+ * file paths on Windows systems.
+ *
+ * @param $item
+ * An item from $_FILES.
+ * @param $key
+ * The key for the item within $_FILES.
+ *
+ * @see http://php.net/manual/en/features.file-upload.php#42280
*/
function _fix_gpc_magic_files(&$item, $key) {
if ($key != 'tmp_name') {
@@ -1040,7 +1062,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;
@@ -1061,12 +1086,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.
*/
@@ -1075,7 +1101,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.
@@ -1084,6 +1110,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.
*/
@@ -1116,7 +1143,7 @@ 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.
@@ -1143,7 +1170,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.
@@ -1161,7 +1188,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
@@ -1255,7 +1282,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 it for output to HTML.
*
* @param $uri
* A plain-text URI that might contain dangerous protocols.
@@ -1275,7 +1302,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
@@ -1289,7 +1316,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.
@@ -1358,6 +1385,7 @@ function filter_xss($string, $allowed_tags = array('a', 'em', 'strong', 'cite',
* 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.
@@ -1525,15 +1553,16 @@ 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
+ * (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.
*/
@@ -1587,7 +1616,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.
*/
@@ -1603,7 +1632,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:
@@ -1642,7 +1671,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
@@ -1664,31 +1693,27 @@ function format_xml_elements($array) {
* @param $count
* 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.
+ * The string for the singular case. 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.
* @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. 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:
- * - !variable: inserted as is
- * - @variable: escape plain text to HTML (check_plain)
- * - %variable: escape text and theme as a placeholder for user-submitted
- * content (check_plain + drupal_placeholder)
- * Note that you do not need to include @count in this array.
- * This replacement is done automatically for the plural case.
+ * Based on the first character of the key, the value is escaped and/or
+ * themed. See format_string(). Note that you do not need to include @count
+ * in this array; this replacement is done automatically for the plural case.
* @param $options
- * An associative array of additional options, with the following keys:
- * - 'langcode' (default to the current language) The language code to
- * 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.
+ * An associative array of additional options. See t() for allowed keys.
+ *
* @return
* A translated string.
+ *
+ * @see t()
+ * @see format_string()
*/
function format_plural($count, $singular, $plural, array $args = array(), array $options = array()) {
$args['@count'] = $count;
@@ -1717,11 +1742,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.
*/
@@ -1738,13 +1764,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.
*/
@@ -1777,7 +1804,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.
@@ -1786,6 +1813,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.
*/
@@ -1917,10 +1945,11 @@ function format_date($timestamp, $type = 'medium', $format = '', $timezone = NUL
/**
* Returns an ISO8601 formatted date based on the given date.
*
- * Can be used as a callback for RDF mappings.
+ * Callback for use within hook_rdf_mapping() implementations.
*
* @param $date
* A UNIX timestamp.
+ *
* @return string
* An ISO8601 formatted date.
*/
@@ -1931,7 +1960,9 @@ function date_iso8601($date) {
}
/**
- * Callback function for preg_replace_callback().
+ * Translates a formatted date string.
+ *
+ * Callback for preg_replace_callback() within format_date().
*/
function _format_date_callback(array $matches = NULL, $new_langcode = NULL) {
// We cache translations to avoid redundant and rather costly calls to t().
@@ -2023,8 +2054,8 @@ function _format_date_callback(array $matches = NULL, $new_langcode = NULL) {
* 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().
*
@@ -2149,7 +2180,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.
@@ -2157,6 +2188,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.
*/
@@ -2169,7 +2201,7 @@ function url_is_external($path) {
}
/**
- * Format an attribute string for a HTTP header.
+ * Formats an attribute string for an HTTP header.
*
* @param $attributes
* An associative array of attributes such as 'rel'.
@@ -2191,7 +2223,7 @@ 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
@@ -2412,7 +2444,7 @@ function drupal_deliver_page($page_callback_result, $default_delivery_callback =
}
/**
- * Package and send the result of a page callback to the browser as HTML.
+ * Packages and sends the result of a page callback to the browser as HTML.
*
* @param $page_callback_result
* The result of a page callback. Can be one of:
@@ -2521,7 +2553,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().
@@ -2548,7 +2580,7 @@ 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
@@ -2570,7 +2602,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
@@ -2646,10 +2678,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() adds a "/" to the beginning and end of 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.
@@ -2660,12 +2692,12 @@ 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').
- * Adding a link will overwrite a prior link with the exact same 'rel' and
- * 'href' attributes.
+ * 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'). Adding
+ * a link will overwrite a prior link with the exact same 'rel' and 'href'
+ * attributes.
*
* @param $attributes
* Associative array of element attributes including 'href' and 'rel'.
@@ -2729,8 +2761,8 @@ function drupal_add_html_head_link($attributes, $header = FALSE) {
* See drupal_get_css() where the overrides are performed. Also, if the
* direction of the current language is right-to-left (Hebrew, Arabic,
* etc.), the function will also look for an RTL CSS file and append it to
- * the list. The name of this file should have an '-rtl.css' suffix. For
- * example a CSS file called 'mymodule-name.css' will have a
+ * the list. The name of this file should have an '-rtl.css' suffix. For
+ * example, a CSS file called 'mymodule-name.css' will have a
* 'mymodule-name-rtl.css' file added to the list, if exists in the same
* directory. This CSS file should contain overrides for properties which
* should be reversed or otherwise different in a right-to-left display.
@@ -2862,7 +2894,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
@@ -2932,11 +2964,24 @@ 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().
+ * Sorts CSS and JavaScript resources.
+ *
+ * Callback for uasort() within:
+ * - drupal_get_css()
+ * - drupal_get_js()
*
* 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
@@ -2972,7 +3017,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
@@ -3003,6 +3048,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();
@@ -3069,7 +3115,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
@@ -3085,6 +3131,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'));
@@ -3111,7 +3158,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:
@@ -3342,8 +3389,8 @@ function drupal_pre_render_styles($elements) {
* in $css while the value is the cache file name. The cache file is generated
* in two cases. First, if there is no file name value for the key, which will
* happen if a new file name has been added to $css or after the lookup
- * variable is emptied to force a rebuild of the cache. Second, the cache
- * file is generated if it is missing on disk. Old cache files are not deleted
+ * variable is emptied to force a rebuild of the cache. Second, the cache file
+ * is generated if it is missing on disk. Old cache files are not deleted
* immediately when the lookup variable is emptied, but are deleted after a set
* period by drupal_delete_file_if_stale(). This ensures that files referenced
* by a cached page will still be available.
@@ -3421,9 +3468,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__);
@@ -3494,13 +3539,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.
*/
@@ -3586,7 +3632,11 @@ function drupal_clear_css_cache() {
}
/**
- * Callback to delete files modified more than a set time ago.
+ * Deletes files modified more than a set time ago.
+ *
+ * Callback for file_scan_directory() within:
+ * - drupal_clear_css_cache()
+ * - drupal_clear_js_cache()
*/
function drupal_delete_file_if_stale($uri) {
// Default stale file threshold is 30 days.
@@ -3596,7 +3646,7 @@ 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.)
@@ -3605,6 +3655,7 @@ function drupal_delete_file_if_stale($uri) {
* The identifier to clean.
* @param $filter
* An array of string replacements to use on the identifier.
+ *
* @return
* The cleaned identifier.
*/
@@ -3626,13 +3677,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.
*/
@@ -3641,7 +3693,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 guarantees 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,
@@ -3772,7 +3824,7 @@ function drupal_region_class($region) {
* 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
+ * $() 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
@@ -3892,7 +3944,7 @@ function drupal_region_class($region) {
* 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.
+ * tag. Defaults to FALSE.
* - cache: If set to FALSE, the JavaScript file is loaded anew on every page
* call; in other words, it is not cached. Used only when 'type' references
* a JavaScript file. Defaults to TRUE.
@@ -3995,6 +4047,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()
*/
@@ -4039,8 +4092,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()
@@ -4337,7 +4392,7 @@ function drupal_aggregate_js(&$js_groups) {
* );
* @endcode
*
- * 'js', 'css', and 'library' are types that get special handling. For any
+ * 'js', 'css', and 'library' are types that get special handling. For any
* other kind of attached data, the array key must be the full name of the
* callback function and each value an array of arguments. For example:
* @code
@@ -4688,16 +4743,16 @@ 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.
*
- * 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
- * themed into a table. The table must have an id attribute set. If using
- * theme_table(), the id may be set as such:
+ * 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 themed
+ * into a table. The table must have an ID attribute set. If using
+ * theme_table(), the ID may be set as follows:
* @code
* $output = theme('table', array('header' => $header, 'rows' => $rows, 'attributes' => array('id' => 'my-module-table')));
* return $output;
@@ -4712,8 +4767,8 @@ function drupal_get_library($module, $name = NULL) {
* $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(
@@ -4733,8 +4788,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
@@ -4751,14 +4806,14 @@ function drupal_get_library($module, $name = NULL) {
*
* In a situation where tree relationships are present, adding multiple
* subgroups is not necessary, because the table will contain indentations that
- * provide enough information about the sibling and parent relationships.
- * 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
+ * provide enough information about the sibling and parent relationships. See
+ * theme_menu_overview_form() for an example creating a table containing parent
+ * relationships.
+ *
+ * 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.
*
@@ -4831,8 +4886,8 @@ function drupal_add_tabledrag($table_id, $action, $relationship, $group, $subgro
* $files while the value is the cache file name. The cache file is generated
* in two cases. First, if there is no file name value for the key, which will
* happen if a new file name has been added to $files or after the lookup
- * variable is emptied to force a rebuild of the cache. Second, the cache
- * file is generated if it is missing on disk. Old cache files are not deleted
+ * variable is emptied to force a rebuild of the cache. Second, the cache file
+ * is generated if it is missing on disk. Old cache files are not deleted
* immediately when the lookup variable is emptied, but are deleted after a set
* period by drupal_delete_file_if_stale(). This ensures that files referenced
* by a cached page will still be available.
@@ -4919,7 +4974,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.
@@ -4937,7 +4992,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.
@@ -4950,7 +5005,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.
@@ -4964,7 +5019,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.
@@ -4974,7 +5029,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.
@@ -4982,6 +5037,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.
@@ -5050,7 +5106,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
@@ -5102,10 +5158,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
+ * TRUE if cron ran successfully.
*/
function drupal_cron_run() {
// Allow execution to continue even if the request gets canceled.
@@ -5180,7 +5236,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.
@@ -5300,7 +5359,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
@@ -5308,6 +5367,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.
@@ -5330,7 +5390,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
@@ -5406,7 +5466,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.
*
@@ -5460,7 +5520,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
@@ -5551,20 +5611,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'];
@@ -5577,8 +5637,10 @@ function drupal_pre_render_markup($elements) {
* @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).
+ * - #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).
*
* @see hook_page_alter()
* @see element_info()
@@ -5655,20 +5717,20 @@ function drupal_render_page($page) {
* 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'.
+ * - '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
@@ -5685,6 +5747,7 @@ function drupal_render_page($page) {
*
* @param $elements
* The structured array describing the data to be rendered.
+ *
* @return
* The rendered HTML.
*/
@@ -5798,7 +5861,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.
@@ -5823,7 +5886,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
@@ -5852,7 +5915,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
@@ -5878,7 +5941,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.
@@ -5907,16 +5970,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 the 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)) {
@@ -5937,17 +6001,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.
@@ -5973,7 +6037,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
@@ -6016,9 +6080,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
@@ -6056,12 +6121,15 @@ 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. For example, to cache separately
+ * for each user, use DRUPAL_CACHE_PER_USER. To cache separately for each
+ * page and role, use the expression:
+ * @code
+ * DRUPAL_CACHE_PER_PAGE | DRUPAL_CACHE_PER_ROLE
+ * @endcode
*
* @return
* An array of cache ID parts, always containing the active theme. If the
@@ -6100,7 +6168,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']
@@ -6126,7 +6194,15 @@ function drupal_render_cid_create($elements) {
}
/**
- * Function used by uasort to sort structured arrays by weight.
+ * Sorts a structured array by '#weight' property.
+ *
+ * Callback for uasort() within element_children().
+ *
+ * @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;
@@ -6138,7 +6214,17 @@ function element_sort($a, $b) {
}
/**
- * Array sorting callback; sorts elements by title.
+ * Sorts a structured array by '#title' property.
+ *
+ * Callback for uasort() within:
+ * - system_modules()
+ * - theme_simpletest_test_table()
+ *
+ * @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 element_sort_by_title($a, $b) {
$a_title = (is_array($a) && isset($a['#title'])) ? $a['#title'] : '';
@@ -6147,7 +6233,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().
@@ -6173,7 +6259,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().
@@ -6188,7 +6274,20 @@ function element_info_property($type, $property_name, $default = NULL) {
}
/**
- * Function used by uasort to sort structured arrays by weight, without the property weight prefix.
+ * Sorts a structured array by 'weight' key (no # prefix).
+ *
+ * Callback for uasort() within:
+ * - _field_ui_reduce_order()
+ * - update_resolve_dependencies()
+ * - archiver_get_info()
+ * - drupal_get_updaters()
+ * - drupal_get_filetransfer_info()
+ *
+ * @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;
@@ -6200,7 +6299,15 @@ function drupal_sort_weight($a, $b) {
}
/**
- * Array sorting callback; sorts elements by 'title' key.
+ * Sorts a structured array by 'title' key (no # prefix).
+ *
+ * Callback for uasort() within system_admin_index().
+ *
+ * @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'])) {
@@ -6213,21 +6320,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 (keys beginning 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] != '#';
@@ -6243,6 +6350,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.
*/
@@ -6289,6 +6397,7 @@ function element_children(&$elements, $sort = FALSE) {
*
* @param $elements
* The parent element.
+ *
* @return
* The array keys of the element's visible children.
*/
@@ -6484,7 +6593,7 @@ function &drupal_array_get_nested_value(array &$array, array $parents, &$key_exi
}
/**
- * 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
@@ -6520,7 +6629,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(
@@ -6728,7 +6837,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
@@ -6747,7 +6856,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
@@ -6755,6 +6864,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.
@@ -6810,7 +6920,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
@@ -6841,7 +6951,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 an SQL query.
*
* @param $table
* The name of the table from which to retrieve fields.
@@ -6849,7 +6961,7 @@ function _drupal_schema_initialize(&$schema, $module, $remove_descriptions = TRU
* An optional prefix to to all fields.
*
* @return An array of fields.
- **/
+ */
function drupal_schema_fields_sql($table, $prefix = NULL) {
$schema = drupal_get_schema($table);
$fields = array_keys($schema['fields']);
@@ -7081,7 +7193,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:
@@ -7111,6 +7223,7 @@ function drupal_parse_info_file($filename) {
*
* @param $data
* A string to parse.
+ *
* @return
* The info array.
*
@@ -7174,11 +7287,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
*/
@@ -7197,7 +7311,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()
*/
@@ -7223,7 +7337,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()
*/
@@ -7241,7 +7355,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.
@@ -7282,10 +7396,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.
@@ -7293,7 +7407,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().
@@ -7318,10 +7432,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').
@@ -7375,12 +7490,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.
@@ -7478,11 +7594,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.
+ * 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.
@@ -7511,14 +7628,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()
@@ -7534,10 +7651,10 @@ function drupal_get_updaters() {
}
/**
- * Drupal FileTransfer registry.
+ * Assembles the Drupal FileTransfer registry.
*
* @return
- * Returns the Drupal FileTransfer class registry.
+ * The Drupal FileTransfer class registry.
*
* @see FileTransfer
* @see hook_filetransfer_info()
--
GitLab