Skip to content

GitLab

D
drupal
Commit 9727bd09 authored by catch's avatar catch
Browse files
Options

Issue #1315886 by xjm: Clean up API docs for includes directory, files starting with A-C.

parent c9e01c6e
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 726 additions and 414 deletions
core/includes/actions.inc
View file @ 9727bd09
......@@ -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.
*/
......
core/includes/ajax.inc
View file @ 9727bd09
......@@ -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
......
core/includes/archiver.inc
View file @ 9727bd09
......@@ -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.
......
core/includes/authorize.inc
View file @ 9727bd09
......@@ -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.
......
core/includes/batch.inc
View file @ 9727bd09
<?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()) {
......
core/includes/batch.queue.inc
View file @ 9727bd09
<?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();
......
core/includes/bootstrap.inc
View file @ 9727bd09
This diff is collapsed.
core/includes/cache-install.inc
View file @ 9727bd09
......@@ -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;
}
......
core/includes/cache.inc
View file @ 9727bd09
<?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.