Commit 180642cd authored by Dries's avatar Dries
Browse files

- Patch #1317620 by xjm: clean up API docs for includes directory, files starting with D-G.

parent 8be72b70
......@@ -2,7 +2,7 @@
/**
* @file
* Initialize the list of date formats and their locales.
* Initializes the list of date formats and their locales.
*/
/**
......
......@@ -2,7 +2,7 @@
/**
* @file
* Functions for error handling
* Functions for error handling.
*/
/**
......@@ -21,7 +21,8 @@
const ERROR_REPORTING_DISPLAY_ALL = 2;
/**
* Map PHP error constants to watchdog severity levels.
* Maps PHP error constants to watchdog severity levels.
*
* The error constants are documented at
* http://php.net/manual/en/errorfunc.constants.php
*
......@@ -50,7 +51,7 @@ function drupal_error_levels() {
}
/**
* Custom PHP error handler.
* Provides custom PHP error handling.
*
* @param $error_level
* The level of the error raised.
......@@ -61,7 +62,8 @@ function drupal_error_levels() {
* @param $line
* The line number the error was raised at.
* @param $context
* An array that points to the active symbol table at the point the error occurred.
* An array that points to the active symbol table at the point the error
* occurred.
*/
function _drupal_error_handler_real($error_level, $message, $filename, $line, $context) {
if ($error_level & error_reporting()) {
......@@ -88,10 +90,11 @@ function _drupal_error_handler_real($error_level, $message, $filename, $line, $c
}
/**
* Decode an exception, especially to retrive the correct caller.
* Decodes an exception and retrieves the correct caller.
*
* @param $exception
* The exception object that was thrown.
*
* @return
* An error in the format expected by _drupal_log_error().
*/
......@@ -134,10 +137,11 @@ function _drupal_decode_exception($exception) {
}
/**
* Render an error message for an exception without any possibility of a further exception occurring.
* Renders an exception error message without further exceptions.
*
* @param $exception
* The exception object that was thrown.
*
* @return
* An error message.
*/
......@@ -169,12 +173,12 @@ function error_displayable($error = NULL) {
}
/**
* Log a PHP error or exception, display an error page in fatal cases.
* Logs a PHP error or exception and displays an error page in fatal cases.
*
* @param $error
* An array with the following keys: %type, !message, %function, %file, %line
* and severity_level. All the parameters are plain-text, with the exception of
* !message, which needs to be a safe HTML string.
* and severity_level. All the parameters are plain-text, with the exception
* of !message, which needs to be a safe HTML string.
* @param $fatal
* TRUE if the error is fatal.
*/
......@@ -261,6 +265,7 @@ function _drupal_log_error($error, $fatal = FALSE) {
*
* @param $backtrace
* A standard PHP backtrace.
*
* @return
* An associative array with keys 'file', 'line' and 'function'.
*/
......
......@@ -70,11 +70,7 @@
const FILE_STATUS_PERMANENT = 1;
/**
* Methods to manage a registry of stream wrappers.
*/
/**
* Drupal stream wrapper registry.
* Provides Drupal stream wrapper registry.
*
* A stream wrapper is an abstraction of a file system that allows Drupal to
* use the same set of methods to access both local files and remote resources.
......@@ -206,7 +202,7 @@ function file_uri_scheme($uri) {
}
/**
* Check that the scheme of a stream URI is valid.
* Checks that the scheme of a stream URI is valid.
*
* Confirms that there is a registered stream handler for the provided scheme
* and that it is callable. This is useful if you want to confirm a valid
......@@ -232,7 +228,7 @@ function file_stream_wrapper_valid_scheme($scheme) {
/**
* Returns the part of an URI after the schema.
* Returns the part of a URI after the schema.
*
* @param $uri
* A stream, referenced as "scheme://target".
......@@ -252,7 +248,7 @@ function file_uri_target($uri) {
}
/**
* Get the default file stream implementation.
* Gets the default file stream implementation.
*
* @return
* 'public', 'private' or any other file scheme defined as the default.
......@@ -322,7 +318,7 @@ function file_stream_wrapper_get_instance_by_uri($uri) {
}
/**
* Returns a reference to the stream wrapper class responsible for a given scheme.
* Returns a reference to the stream wrapper class responsible for a scheme.
*
* This helper method returns a stream instance using a scheme. That is, the
* passed string does not contain a "://". For example, "public" is a scheme
......@@ -357,7 +353,6 @@ function file_stream_wrapper_get_instance_by_scheme($scheme) {
* Creates a web-accessible URL for a stream to an external or local file.
*
* Compatibility: normal paths and stream wrappers.
* @see http://drupal.org/node/515192
*
* There are two kinds of local files:
* - "managed files", i.e. those stored by a Drupal-compatible stream wrapper.
......@@ -375,6 +370,8 @@ function file_stream_wrapper_get_instance_by_scheme($scheme) {
* If the provided string already contains a preceding 'http', 'https', or
* '/', nothing is done and the same string is returned. If a stream wrapper
* could not be found to generate an external URL, then FALSE is returned.
*
* @see http://drupal.org/node/515192
*/
function file_create_url($uri) {
// Allow the URI to be altered, e.g. to serve a file from a CDN or static
......@@ -417,7 +414,7 @@ function file_create_url($uri) {
}
/**
* Check that the directory exists and is writable.
* Checks that the directory exists and is writable.
*
* Directories need to have execute permissions to be considered a directory by
* FTP servers, etc.
......@@ -459,7 +456,7 @@ function file_prepare_directory(&$directory, $options = FILE_MODIFY_PERMISSIONS)
}
/**
* If missing, create a .htaccess file in each Drupal files directory.
* Creates a .htaccess file in each Drupal files directory if it is missing.
*/
function file_ensure_htaccess() {
file_save_htaccess('public://', FALSE);
......@@ -470,7 +467,7 @@ function file_ensure_htaccess() {
}
/**
* Creates an .htaccess file in the given directory.
* Creates a .htaccess file in the given directory.
*
* @param $directory
* The directory.
......@@ -526,19 +523,19 @@ function file_save_htaccess($directory, $private = TRUE) {
* @return
* An array of file objects, indexed by fid.
*
* @todo Remove $conditions in Drupal 8.
*
* @see hook_file_load()
* @see file_load()
* @see entity_load()
* @see EntityFieldQuery
*
* @todo Remove $conditions in Drupal 8.
*/
function file_load_multiple($fids = array(), $conditions = array()) {
return entity_load('file', $fids, $conditions);
}
/**
* Load a file object from the database.
* Loads a single file object from the database.
*
* @param $fid
* A file ID.
......@@ -555,7 +552,7 @@ function file_load($fid) {
}
/**
* Save a file object to the database.
* Saves a file object to the database.
*
* If the $file->fid is not set a new record will be added.
*
......@@ -797,7 +794,7 @@ function file_copy(stdClass $source, $destination = NULL, $replace = FILE_EXISTS
}
/**
* Determine whether the URI has a valid scheme for file API operations.
* Determines whether the URI has a valid scheme for file API operations.
*
* There must be a scheme and it must be a Drupal-provided scheme like
* 'public', 'private', 'temporary', or an extension provided with
......@@ -926,7 +923,7 @@ function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXIST
}
/**
* Given a relative path, construct a URI into Drupal's default files location.
* Constructs a URI to Drupal's default files location given a relative path.
*/
function file_build_uri($path) {
$uri = file_default_scheme() . '://' . $path;
......@@ -934,8 +931,7 @@ function file_build_uri($path) {
}
/**
* Determines the destination path for a file depending on how replacement of
* existing files should be handled.
* Determines the destination path for a file.
*
* @param $destination
* A string specifying the desired final URI or filepath.
......@@ -972,7 +968,7 @@ function file_destination($destination, $replace) {
}
/**
* Move a file to a new location and update the file's database entry.
* Moves a file to a new location and update the file's database entry.
*
* Moving a file is performed by copying the file to the new location and then
* deleting the original.
......@@ -1052,8 +1048,7 @@ function file_move(stdClass $source, $destination = NULL, $replace = FILE_EXISTS
}
/**
* Move a file to a new location without calling any hooks or making any
* changes to the database.
* Moves a file to a new location without database changes or hook invocation.
*
* @param $source
* A string specifying the filepath or URI of the original file.
......@@ -1082,7 +1077,7 @@ function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXIST
}
/**
* Modify a filename as needed for security purposes.
* Modifies a filename as needed for security purposes.
*
* Munging a file name prevents unknown file extensions from masking exploit
* files. When web servers such as Apache decide how to process a URL request,
......@@ -1146,7 +1141,7 @@ function file_munge_filename($filename, $extensions, $alerts = TRUE) {
}
/**
* Undo the effect of file_munge_filename().
* Undoes the effect of file_munge_filename().
*
* @param $filename
* String with the filename to be unmunged.
......@@ -1159,7 +1154,7 @@ function file_unmunge_filename($filename) {
}
/**
* Create a full file path from a directory and filename.
* Creates a full file path from a directory and filename.
*
* If a file with the specified name already exists, an alternative will be
* used.
......@@ -1214,7 +1209,7 @@ function file_create_filename($basename, $directory) {
}
/**
* Delete a file and its database record.
* Deletes a file and its database record.
*
* If the $force parameter is not TRUE, file_usage_list() will be called to
* determine if the file is being used by any modules. If the file is being
......@@ -1275,8 +1270,7 @@ function file_delete(stdClass $file, $force = FALSE) {
}
/**
* Delete a file without calling any hooks or making any changes to the
* database.
* Deletes a file without database changes or hook invocations.
*
* This function should be used when the file to be deleted does not have an
* entry recorded in the files table.
......@@ -1312,7 +1306,7 @@ function file_unmanaged_delete($path) {
}
/**
* Recursively delete all files and directories in the specified filepath.
* Deletes all files and directories in the specified filepath recursively.
*
* If the specified path is a directory then the function will call itself
* recursively to process the contents. Once the contents have been removed the
......@@ -1350,7 +1344,7 @@ function file_unmanaged_delete_recursive($path) {
}
/**
* Determine total disk space used by a single user or the whole filesystem.
* Determines total disk space used by a single user or the whole filesystem.
*
* @param $uid
* Optional. A user id, specifying NULL returns the total space used by all
......@@ -1587,7 +1581,6 @@ function file_save_upload($source, $validators = array(), $destination = FALSE,
* or open_basedir are enabled, so this function fills that gap.
*
* Compatibility: normal paths and stream wrappers.
* @see http://drupal.org/node/515192
*
* @param $filename
* The filename of the uploaded file.
......@@ -1598,6 +1591,7 @@ function file_save_upload($source, $validators = array(), $destination = FALSE,
* TRUE on success, or FALSE on failure.
*
* @see move_uploaded_file()
* @see http://drupal.org/node/515192
* @ingroup php_wrappers
*/
function drupal_move_uploaded_file($filename, $uri) {
......@@ -1618,7 +1612,7 @@ function drupal_move_uploaded_file($filename, $uri) {
}
/**
* Check that a file meets the criteria specified by the validators.
* Checks that a file meets the criteria specified by the validators.
*
* After executing the validator callbacks specified hook_file_validate() will
* also be called to allow other modules to report errors about the file.
......@@ -1653,10 +1647,11 @@ function file_validate(stdClass &$file, $validators = array()) {
}
/**
* Check for files with names longer than we can store in the database.
* Checks for files with names longer than can be stored in the database.
*
* @param $file
* A Drupal file object.
*
* @return
* An array. If the file name is too long, it will contain an error message.
*/
......@@ -1673,7 +1668,7 @@ function file_validate_name_length(stdClass $file) {
}
/**
* Check that the filename ends with an allowed extension.
* Checks that the filename ends with an allowed extension.
*
* @param $file
* A Drupal file object.
......@@ -1697,7 +1692,7 @@ function file_validate_extensions(stdClass $file, $extensions) {
}
/**
* Check that the file's size is below certain limits.
* Checks that the file's size is below certain limits.
*
* This check is not enforced for the user #1.
*
......@@ -1736,7 +1731,7 @@ function file_validate_size(stdClass $file, $file_limit = 0, $user_limit = 0) {
}
/**
* Check that the file is recognized by image_get_info() as an image.
* Checks that the file is recognized by image_get_info() as an image.
*
* @param $file
* A Drupal file object.
......@@ -1758,7 +1753,7 @@ function file_validate_is_image(stdClass $file) {
}
/**
* Verify that image dimensions are within the specified maximum and minimum.
* Verifies that image dimensions are within the specified maximum and minimum.
*
* Non-image files will be ignored. If a image toolkit is available the image
* will be scaled to fit within the desired maximum dimensions.
......@@ -1816,7 +1811,7 @@ function file_validate_image_resolution(stdClass $file, $maximum_dimensions = 0,
}
/**
* Save a string to the specified destination and create a database file entry.
* Saves a file to the specified destination and creates a database entry.
*
* @param $data
* A string containing the contents of the file.
......@@ -1880,7 +1875,7 @@ function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAM
}
/**
* Save a string to the specified destination without invoking file API.
* Saves a file to the specified destination without invoking file API.
*
* This function is identical to file_save_data() except the file will not be
* saved to the {file_managed} table and none of the file_* hooks will be
......@@ -1891,7 +1886,8 @@ function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAM
* @param $destination
* A string containing the destination location. This must be a stream wrapper
* URI. If no value is provided, a randomized name will be generated and the
* file will be saved using Drupal's default files scheme, usually "public://".
* file will be saved using Drupal's default files scheme, usually
* "public://".
* @param $replace
* Replace behavior when the destination file already exists:
* - FILE_EXISTS_REPLACE - Replace the existing file.
......@@ -1917,7 +1913,7 @@ function file_unmanaged_save_data($data, $destination = NULL, $replace = FILE_EX
}
/**
* Transfer file using HTTP to client.
* Transfers a file to the client using HTTP.
*
* Pipes a file through Drupal to the client.
*
......@@ -1950,7 +1946,7 @@ function file_transfer($uri, $headers) {
}
/**
* Menu handler for private file transfers.
* Page callback: Handles private file transfers.
*
* Call modules that implement hook_file_download() to find out if a file is
* accessible and what headers it should be transferred with. If one or more
......@@ -1960,6 +1956,7 @@ function file_transfer($uri, $headers) {
* If the file does not exist drupal_not_found() will be returned.
*
* @see hook_file_download()
* @see system_menu()
*/
function file_download() {
// Merge remainder of arguments from GET['q'], into relative file path.
......@@ -2069,7 +2066,7 @@ function file_scan_directory($dir, $mask, $options = array(), $depth = 0) {
}
/**
* Determine the maximum file upload size by querying the PHP settings.
* Determines the maximum file upload size by querying the PHP settings.
*
* @return
* A file size limit in bytes based on the PHP upload_max_filesize and
......@@ -2093,7 +2090,7 @@ function file_upload_max_size() {
}
/**
* Determine an Internet Media Type, or MIME type from a filename.
* Determines an Internet Media Type or MIME type from a filename.
*
* @param $uri
* A string containing the URI, path, or filename.
......@@ -2122,7 +2119,7 @@ function file_get_mimetype($uri, $mapping = NULL) {
}
/**
* Set the permissions on a file or directory.
* Sets the permissions on a file or directory.
*
* This function will use the 'file_chmod_directory' and 'file_chmod_file'
* variables for the default modes for directories and uploaded/generated
......@@ -2228,10 +2225,11 @@ function drupal_unlink($uri, $context = NULL) {
* The absolute local filesystem path (with no symbolic links), or FALSE on
* failure.
*
* @todo This function is deprecated, and should be removed wherever possible.
*
* @see DrupalStreamWrapperInterface::realpath()
* @see http://php.net/manual/function.realpath.php
* @ingroup php_wrappers
* @todo: This function is deprecated, and should be removed wherever possible.
*/
function drupal_realpath($uri) {
// If this URI is a stream, pass it off to the appropriate stream wrapper.
......@@ -2252,7 +2250,6 @@ function drupal_realpath($uri) {
* PHP's dirname() as a fallback.
*
* Compatibility: normal paths and stream wrappers.
* @see http://drupal.org/node/515192
*
* @param $uri
* A URI or path.
......@@ -2261,6 +2258,7 @@ function drupal_realpath($uri) {
* A string containing the directory name.
*
* @see dirname()
* @see http://drupal.org/node/515192
* @ingroup php_wrappers
*/
function drupal_dirname($uri) {
......@@ -2310,7 +2308,6 @@ function drupal_basename($uri, $suffix = NULL) {
* is not provided, this function will make sure that Drupal's is used.
*
* Compatibility: normal paths and stream wrappers.
* @see http://drupal.org/node/515192
*
* @param $uri
* A URI or pathname.
......@@ -2325,6 +2322,7 @@ function drupal_basename($uri, $suffix = NULL) {
* Boolean TRUE on success, or FALSE on failure.
*
* @see mkdir()
* @see http://drupal.org/node/515192
* @ingroup php_wrappers
*/
function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) {
......@@ -2341,7 +2339,7 @@ function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) {
}
/**
* Remove a directory.
* Removes a directory.
*
* PHP's rmdir() is broken on Windows, as it can fail to remove a directory
* when it has a read-only flag set.
......@@ -2378,7 +2376,6 @@ function drupal_rmdir($uri, $context = NULL) {
* given a filepath.
*
* Compatibility: normal paths and stream wrappers.
* @see http://drupal.org/node/515192
*
* @param $directory
* The directory where the temporary filename will be created.
......@@ -2390,6 +2387,7 @@ function drupal_rmdir($uri, $context = NULL) {
* The new temporary filename, or FALSE on failure.
*
* @see tempnam()
* @see http://drupal.org/node/515192
* @ingroup php_wrappers
*/
function drupal_tempnam($directory, $prefix) {
......@@ -2412,7 +2410,7 @@ function drupal_tempnam($directory, $prefix) {
}
/**
* Get the path of system-appropriate temporary directory.
* Gets the path of system-appropriate temporary directory.
*/
function file_directory_temp() {
$temporary_directory = variable_get('file_temporary_path', NULL);
......@@ -2465,6 +2463,7 @@ function file_directory_temp() {
*
* @param $file
* A file object.
*
* @return
* An associative array of headers, as expected by file_transfer().
*/
......
This diff is collapsed.
......@@ -17,7 +17,7 @@
*/
/**
* Parses Gettext Portable Object file information and inserts into database
* Parses Gettext Portable Object information and inserts it into the database.
*
* @param $file
* Drupal file object corresponding to the PO file to import.
......@@ -74,7 +74,7 @@ function _locale_import_po($file, $langcode, $mode) {
}
/**
* Parses Gettext Portable Object file into an array
* Parses a Gettext Portable Object file into an array.
*
* @param $op
* Storage operation type: db-store or mem-store.
......@@ -335,7 +335,7 @@ function _locale_import_read_po($op, $file, $mode = NULL, $lang = NULL) {
}
/**
* Sets an error message occurred during locale file parsing.
* Sets an error message if an error occurred during locale file parsing.
*
* @param $message
* The message to be translated.
......@@ -354,7 +354,7 @@ function _locale_import_message($message, $file, $lineno = NULL) {
}
/**
* Imports a string into the database
* Performs the specified operation for one string.
*
* @param $op
* Operation to perform: 'db-store', 'db-report', 'mem-store' or 'mem-report'.
......@@ -448,7 +448,7 @@ function _locale_import_one_string($op, $value = NULL, $mode = NULL, $lang = NUL
}
/**
* Import one string into the database.
* Imports one string into the database.
*
* @param $report
* Report array summarizing the number of changes done in the form:
......@@ -562,7 +562,7 @@ function _locale_import_one_string_db(&$report, $langcode, $context, $source, $t
}
/**
* Parses a Gettext Portable Object file header
* Parses a Gettext Portable Object file header.
*
* @param $header
* A string containing the complete header.
......@@ -583,7 +583,7 @@ function _locale_import_parse_header($header) {
}
/**
* Parses a Plural-Forms entry from a Gettext Portable Object file header
* Parses a Plural-Forms entry from a Gettext Portable Object file header.
*
* @param $pluralforms
* A string containing the Plural-Forms entry.
......@@ -627,7 +627,7 @@ function _locale_import_parse_plural_forms($pluralforms, $filepath) {
}
/**
* Parses and sanitizes an arithmetic formula into a PHP expression
* Parses and sanitizes an arithmetic formula into a PHP expression.
*
* While parsing, we ensure, that the operators have the right
* precedence and associativity.
......@@ -730,7 +730,7 @@ function _locale_import_parse_arithmetic($string) {
}
/**
* Backward compatible implementation of token_get_all() for formula parsing
* Provides backward-compatible formula parsing for token_get_all().
*
* @param $string
* A string containing the arithmetic formula.
......@@ -795,9 +795,9 @@ function _locale_import_tokenize_formula($formula) {
}
/**
* Modify a string to contain proper count indices
* Adds count indices to a string.
*
* This is a callback function used via array_map()
* Callback for array_map() within _locale_import_one_string().
*
* @param $entry
* An array element.
......@@ -816,13 +816,13 @@ function _locale_import_append_plural($entry, $key) {
}
/**
* Generate a short, one string version of the passed comment array
* Generates a short, one-string version of the passed comment array.
*
* @param $comment
* An array of strings containing a comment.
*
* @return
* Short one string version of the comment.
* Short one-string version of the comment.
*/
function _locale_import_shorten_comments($comment) {
$comm = '';
......@@ -839,7 +839,7 @@ function _locale_import_shorten_comments($comment) {
}
/**
* Parses a string in quotes
* Parses a string in quotes.
*
* @param $string
* A string specified with enclosing quotes.
......@@ -865,13 +865,14 @@ function _locale_import_parse_quoted($string) {
}
/**
* Generates a structured array of all strings with translations in
* $language, if given. This array can be used to generate an export
* of the string in the database.
* Generates a structured array of all translated strings for the language.
*
* @param $language
* Language object to generate the output for, or NULL if generating
* translation template.