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

1 files changed, 51 insertions, 53 deletions

diff --git a/includes/file.inc b/includes/file.inc
index 7fd6c71c9..7ec13f32e 100644
--- a/includes/file.inc
+++ b/includes/file.inc
@@ -70,11 +70,7 @@ define('FILE_EXISTS_ERROR', 2);
 define('FILE_STATUS_PERMANENT', 1);
 
 /**
- * Methods to manage a registry of stream wrappers.
- */
-
-/**
- * Drupal stream wrapper registry.
+ * Provides Drupal stream wrapper registry.
  *
  * A stream wrapper is an abstraction of a file system that allows Drupal to
  * use the same set of methods to access both local files and remote resources.
@@ -206,7 +202,7 @@ function file_uri_scheme($uri) {
 }
 
 /**
- * Check that the scheme of a stream URI is valid.
+ * Checks that the scheme of a stream URI is valid.
  *
  * Confirms that there is a registered stream handler for the provided scheme
  * and that it is callable. This is useful if you want to confirm a valid
@@ -232,7 +228,7 @@ function file_stream_wrapper_valid_scheme($scheme) {
 
 
 /**
- * Returns the part of an URI after the schema.
+ * Returns the part of a URI after the schema.
  *
  * @param $uri
  *   A stream, referenced as "scheme://target".
@@ -252,7 +248,7 @@ function file_uri_target($uri) {
 }
 
 /**
- * Get the default file stream implementation.
+ * Gets the default file stream implementation.
  *
  * @return
  *   'public', 'private' or any other file scheme defined as the default.
@@ -322,7 +318,7 @@ function file_stream_wrapper_get_instance_by_uri($uri) {
 }
 
 /**
- * Returns a reference to the stream wrapper class responsible for a given scheme.
+ * Returns a reference to the stream wrapper class responsible for a scheme.
  *
  * This helper method returns a stream instance using a scheme. That is, the
  * passed string does not contain a "://". For example, "public" is a scheme
@@ -357,7 +353,6 @@ function file_stream_wrapper_get_instance_by_scheme($scheme) {
  * Creates a web-accessible URL for a stream to an external or local file.
  *
  * Compatibility: normal paths and stream wrappers.
- * @see http://drupal.org/node/515192
  *
  * There are two kinds of local files:
  * - "managed files", i.e. those stored by a Drupal-compatible stream wrapper.
@@ -375,6 +370,8 @@ function file_stream_wrapper_get_instance_by_scheme($scheme) {
  *   If the provided string already contains a preceding 'http', 'https', or
  *   '/', nothing is done and the same string is returned. If a stream wrapper
  *   could not be found to generate an external URL, then FALSE is returned.
+ *
+ * @see http://drupal.org/node/515192
  */
 function file_create_url($uri) {
   // Allow the URI to be altered, e.g. to serve a file from a CDN or static
@@ -417,7 +414,7 @@ function file_create_url($uri) {
 }
 
 /**
- * Check that the directory exists and is writable.
+ * Checks that the directory exists and is writable.
  *
  * Directories need to have execute permissions to be considered a directory by
  * FTP servers, etc.
@@ -459,7 +456,7 @@ function file_prepare_directory(&$directory, $options = FILE_MODIFY_PERMISSIONS)
 }
 
 /**
- * If missing, create a .htaccess file in each Drupal files directory.
+ * Creates a .htaccess file in each Drupal files directory if it is missing.
  */
 function file_ensure_htaccess() {
   file_create_htaccess('public://', FALSE);
@@ -470,7 +467,7 @@ function file_ensure_htaccess() {
 }
 
 /**
- * Creates an .htaccess file in the given directory.
+ * Creates a .htaccess file in the given directory.
  *
  * @param $directory
  *   The directory.
@@ -526,19 +523,19 @@ function file_create_htaccess($directory, $private = TRUE) {
  * @return
  *   An array of file objects, indexed by fid.
  *
+ * @todo Remove $conditions in Drupal 8.
+ *
  * @see hook_file_load()
  * @see file_load()
  * @see entity_load()
  * @see EntityFieldQuery
- *
- * @todo Remove $conditions in Drupal 8.
  */
 function file_load_multiple($fids = array(), $conditions = array()) {
   return entity_load('file', $fids, $conditions);
 }
 
 /**
- * Load a file object from the database.
+ * Loads a single file object from the database.
  *
  * @param $fid
  *   A file ID.
@@ -555,7 +552,7 @@ function file_load($fid) {
 }
 
 /**
- * Save a file object to the database.
+ * Saves a file object to the database.
  *
  * If the $file->fid is not set a new record will be added.
  *
@@ -797,7 +794,7 @@ function file_copy(stdClass $source, $destination = NULL, $replace = FILE_EXISTS
 }
 
 /**
- * Determine whether the URI has a valid scheme for file API operations.
+ * Determines whether the URI has a valid scheme for file API operations.
  *
  * There must be a scheme and it must be a Drupal-provided scheme like
  * 'public', 'private', 'temporary', or an extension provided with
@@ -926,7 +923,7 @@ function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXIST
 }
 
 /**
- * Given a relative path, construct a URI into Drupal's default files location.
+ * Constructs a URI to Drupal's default files location given a relative path.
  */
 function file_build_uri($path) {
   $uri = file_default_scheme() . '://' . $path;
@@ -934,8 +931,7 @@ function file_build_uri($path) {
 }
 
 /**
- * Determines the destination path for a file depending on how replacement of
- * existing files should be handled.
+ * Determines the destination path for a file.
  *
  * @param $destination
  *   A string specifying the desired final URI or filepath.
@@ -972,7 +968,7 @@ function file_destination($destination, $replace) {
 }
 
 /**
- * Move a file to a new location and update the file's database entry.
+ * Moves a file to a new location and update the file's database entry.
  *
  * Moving a file is performed by copying the file to the new location and then
  * deleting the original.
@@ -1052,8 +1048,7 @@ function file_move(stdClass $source, $destination = NULL, $replace = FILE_EXISTS
 }
 
 /**
- * Move a file to a new location without calling any hooks or making any
- * changes to the database.
+ * Moves a file to a new location without database changes or hook invocation.
  *
  * @param $source
  *   A string specifying the filepath or URI of the original file.
@@ -1082,7 +1077,7 @@ function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXIST
 }
 
 /**
- * Modify a filename as needed for security purposes.
+ * Modifies a filename as needed for security purposes.
  *
  * Munging a file name prevents unknown file extensions from masking exploit
  * files. When web servers such as Apache decide how to process a URL request,
@@ -1146,7 +1141,7 @@ function file_munge_filename($filename, $extensions, $alerts = TRUE) {
 }
 
 /**
- * Undo the effect of file_munge_filename().
+ * Undoes the effect of file_munge_filename().
  *
  * @param $filename
  *   String with the filename to be unmunged.
@@ -1159,7 +1154,7 @@ function file_unmunge_filename($filename) {
 }
 
 /**
- * Create a full file path from a directory and filename.
+ * Creates a full file path from a directory and filename.
  *
  * If a file with the specified name already exists, an alternative will be
  * used.
@@ -1214,7 +1209,7 @@ function file_create_filename($basename, $directory) {
 }
 
 /**
- * Delete a file and its database record.
+ * Deletes a file and its database record.
  *
  * If the $force parameter is not TRUE, file_usage_list() will be called to
  * determine if the file is being used by any modules. If the file is being
@@ -1269,8 +1264,7 @@ function file_delete(stdClass $file, $force = FALSE) {
 }
 
 /**
- * Delete a file without calling any hooks or making any changes to the
- * database.
+ * Deletes a file without database changes or hook invocations.
  *
  * This function should be used when the file to be deleted does not have an
  * entry recorded in the files table.
@@ -1306,7 +1300,7 @@ function file_unmanaged_delete($path) {
 }
 
 /**
- * Recursively delete all files and directories in the specified filepath.
+ * Deletes all files and directories in the specified filepath recursively.
  *
  * If the specified path is a directory then the function will call itself
  * recursively to process the contents. Once the contents have been removed the
@@ -1344,7 +1338,7 @@ function file_unmanaged_delete_recursive($path) {
 }
 
 /**
- * Determine total disk space used by a single user or the whole filesystem.
+ * Determines total disk space used by a single user or the whole filesystem.
  *
  * @param $uid
  *   Optional. A user id, specifying NULL returns the total space used by all
@@ -1581,7 +1575,6 @@ function file_save_upload($source, $validators = array(), $destination = FALSE,
  * or open_basedir are enabled, so this function fills that gap.
  *
  * Compatibility: normal paths and stream wrappers.
- * @see http://drupal.org/node/515192
  *
  * @param $filename
  *   The filename of the uploaded file.
@@ -1592,6 +1585,7 @@ function file_save_upload($source, $validators = array(), $destination = FALSE,
  *   TRUE on success, or FALSE on failure.
  *
  * @see move_uploaded_file()
+ * @see http://drupal.org/node/515192
  * @ingroup php_wrappers
  */
 function drupal_move_uploaded_file($filename, $uri) {
@@ -1612,7 +1606,7 @@ function drupal_move_uploaded_file($filename, $uri) {
 }
 
 /**
- * Check that a file meets the criteria specified by the validators.
+ * Checks that a file meets the criteria specified by the validators.
  *
  * After executing the validator callbacks specified hook_file_validate() will
  * also be called to allow other modules to report errors about the file.
@@ -1647,10 +1641,11 @@ function file_validate(stdClass &$file, $validators = array()) {
 }
 
 /**
- * Check for files with names longer than we can store in the database.
+ * Checks for files with names longer than we can store in the database.
  *
  * @param $file
  *   A Drupal file object.
+ *
  * @return
  *   An array. If the file name is too long, it will contain an error message.
  */
@@ -1667,7 +1662,7 @@ function file_validate_name_length(stdClass $file) {
 }
 
 /**
- * Check that the filename ends with an allowed extension.
+ * Checks that the filename ends with an allowed extension.
  *
  * @param $file
  *   A Drupal file object.
@@ -1691,7 +1686,7 @@ function file_validate_extensions(stdClass $file, $extensions) {
 }
 
 /**
- * Check that the file's size is below certain limits.
+ * Checks that the file's size is below certain limits.
  *
  * This check is not enforced for the user #1.
  *
@@ -1730,7 +1725,7 @@ function file_validate_size(stdClass $file, $file_limit = 0, $user_limit = 0) {
 }
 
 /**
- * Check that the file is recognized by image_get_info() as an image.
+ * Checks that the file is recognized by image_get_info() as an image.
  *
  * @param $file
  *   A Drupal file object.
@@ -1752,7 +1747,7 @@ function file_validate_is_image(stdClass $file) {
 }
 
 /**
- * Verify that image dimensions are within the specified maximum and minimum.
+ * Verifies that image dimensions are within the specified maximum and minimum.
  *
  * Non-image files will be ignored. If a image toolkit is available the image
  * will be scaled to fit within the desired maximum dimensions.
@@ -1810,7 +1805,7 @@ function file_validate_image_resolution(stdClass $file, $maximum_dimensions = 0,
 }
 
 /**
- * Save a string to the specified destination and create a database file entry.
+ * Saves a file to the specified destination and creates a database entry.
  *
  * @param $data
  *   A string containing the contents of the file.
@@ -1874,7 +1869,7 @@ function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAM
 }
 
 /**
- * Save a string to the specified destination without invoking file API.
+ * Saves a string to the specified destination without invoking file API.
  *
  * This function is identical to file_save_data() except the file will not be
  * saved to the {file_managed} table and none of the file_* hooks will be
@@ -1885,7 +1880,8 @@ function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAM
  * @param $destination
  *   A string containing the destination location. This must be a stream wrapper
  *   URI. If no value is provided, a randomized name will be generated and the
- *   file will be saved using Drupal's default files scheme, usually "public://".
+ *   file will be saved using Drupal's default files scheme, usually
+ *   "public://".
  * @param $replace
  *   Replace behavior when the destination file already exists:
  *   - FILE_EXISTS_REPLACE - Replace the existing file.
@@ -1911,7 +1907,7 @@ function file_unmanaged_save_data($data, $destination = NULL, $replace = FILE_EX
 }
 
 /**
- * Transfer file using HTTP to client.
+ * Transfers a file to the client using HTTP.
  *
  * Pipes a file through Drupal to the client.
  *
@@ -1953,7 +1949,7 @@ function file_transfer($uri, $headers) {
  * exists but no modules responded drupal_access_denied() will be returned.
  * If the file does not exist drupal_not_found() will be returned.
  *
- * @see hook_file_download()
+ * @see system_menu()
  */
 function file_download() {
   // Merge remainder of arguments from GET['q'], into relative file path.
@@ -2063,7 +2059,7 @@ function file_scan_directory($dir, $mask, $options = array(), $depth = 0) {
 }
 
 /**
- * Determine the maximum file upload size by querying the PHP settings.
+ * Determines the maximum file upload size by querying the PHP settings.
  *
  * @return
  *   A file size limit in bytes based on the PHP upload_max_filesize and
@@ -2087,7 +2083,7 @@ function file_upload_max_size() {
 }
 
 /**
- * Determine an Internet Media Type, or MIME type from a filename.
+ * Determines an Internet Media Type or MIME type from a filename.
  *
  * @param $uri
  *   A string containing the URI, path, or filename.
@@ -2116,7 +2112,7 @@ function file_get_mimetype($uri, $mapping = NULL) {
 }
 
 /**
- * Set the permissions on a file or directory.
+ * Sets the permissions on a file or directory.
  *
  * This function will use the 'file_chmod_directory' and 'file_chmod_file'
  * variables for the default modes for directories and uploaded/generated
@@ -2222,10 +2218,11 @@ function drupal_unlink($uri, $context = NULL) {
  *   The absolute local filesystem path (with no symbolic links), or FALSE on
  *   failure.
  *
+ * @todo This function is deprecated, and should be removed wherever possible.
+ *
  * @see DrupalStreamWrapperInterface::realpath()
  * @see http://php.net/manual/function.realpath.php
  * @ingroup php_wrappers
- * @todo: This function is deprecated, and should be removed wherever possible.
  */
 function drupal_realpath($uri) {
   // If this URI is a stream, pass it off to the appropriate stream wrapper.
@@ -2252,7 +2249,6 @@ function drupal_realpath($uri) {
  * PHP's dirname() as a fallback.
  *
  * Compatibility: normal paths and stream wrappers.
- * @see http://drupal.org/node/515192
  *
  * @param $uri
  *   A URI or path.
@@ -2261,6 +2257,7 @@ function drupal_realpath($uri) {
  *   A string containing the directory name.
  *
  * @see dirname()
+ * @see http://drupal.org/node/515192
  * @ingroup php_wrappers
  */
 function drupal_dirname($uri) {
@@ -2310,7 +2307,6 @@ function drupal_basename($uri, $suffix = NULL) {
  * is not provided, this function will make sure that Drupal's is used.
  *
  * Compatibility: normal paths and stream wrappers.
- * @see http://drupal.org/node/515192
  *
  * @param $uri
  *   A URI or pathname.
@@ -2325,6 +2321,7 @@ function drupal_basename($uri, $suffix = NULL) {
  *   Boolean TRUE on success, or FALSE on failure.
  *
  * @see mkdir()
+ * @see http://drupal.org/node/515192
  * @ingroup php_wrappers
  */
 function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) {
@@ -2341,7 +2338,7 @@ function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) {
 }
 
 /**
- * Remove a directory.
+ * Removes a directory.
  *
  * PHP's rmdir() is broken on Windows, as it can fail to remove a directory
  * when it has a read-only flag set.
@@ -2378,7 +2375,6 @@ function drupal_rmdir($uri, $context = NULL) {
  * given a filepath.
  *
  * Compatibility: normal paths and stream wrappers.
- * @see http://drupal.org/node/515192
  *
  * @param $directory
  *   The directory where the temporary filename will be created.
@@ -2390,6 +2386,7 @@ function drupal_rmdir($uri, $context = NULL) {
  *   The new temporary filename, or FALSE on failure.
  *
  * @see tempnam()
+ * @see http://drupal.org/node/515192
  * @ingroup php_wrappers
  */
 function drupal_tempnam($directory, $prefix) {
@@ -2412,7 +2409,7 @@ function drupal_tempnam($directory, $prefix) {
 }
 
 /**
- * Get the path of system-appropriate temporary directory.
+ * Gets the path of system-appropriate temporary directory.
  */
 function file_directory_temp() {
   $temporary_directory = variable_get('file_temporary_path', NULL);
@@ -2469,6 +2466,7 @@ function file_directory_temp() {
  *
  * @param $file
  *   A file object.
+ *
  * @return
  *   An associative array of headers, as expected by file_transfer().
  */