- Patch #319183 by drewish: clean up file.inc documentation.

includes/file.inc

@@ -14,9 +14,9 @@
  * Fields on the file object:
  * - fid - File ID
  * - uid - The {users}.uid of the user who is associated with the file.
- * - filename - Name of the file with no path components. This may differ
- *   from the basename of the filepath if the file is renamed to avoid
- *   overwriting an existing file.
+ * - filename - Name of the file with no path components. This may differ from
+ *   the basename of the filepath if the file is renamed to avoid overwriting
+ *   an existing file.
  * - filepath - Path of the file relative to Drupal root.
  * - filemime - The file's MIME type.
  * - filesize - The size of the file in bytes.
@@ -108,11 +108,13 @@ function file_create_url($path) {
  * Make sure the destination is a complete path and resides in the file system
  * directory, if it is not prepend the file system directory.
  *
- * @param $destination A string containing the path to verify. If this value is
- *   omitted, Drupal's 'files' directory will be used.
- * @return A string containing the path to file, with file system directory
- *   appended if necessary, or FALSE if the path is invalid (i.e. outside the
- *   configured 'files' or temp directories).
+ * @param $destination
+ *   A string containing the path to verify. If this value is omitted, Drupal's
+ *   'files' directory will be used.
+ * @return
+ *   A string containing the path to file, with file system directory appended
+ *   if necessary, or FALSE if the path is invalid (i.e. outside the configured
+ *   'files' or temp directories).
  */
 function file_create_path($destination = NULL) {
   $file_path = file_directory_path();
@@ -138,17 +140,23 @@ function file_create_path($destination = NULL) {
 }
 
 /**
- * Check that the directory exists and is writable. Directories need to
- * have execute permissions to be considered a directory by FTP servers, etc.
- *
- * @param $directory A string containing the name of a directory path.
- * @param $mode A Boolean value to indicate if the directory should be created
- *   if it does not exist or made writable if it is read-only.
- * @param $form_item An optional string containing the name of a form item that
- *   any errors will be attached to. This is useful for settings forms that
- *   require the user to specify a writable directory. If it can't be made to
- *   work, a form error will be set preventing them from saving the settings.
- * @return FALSE when directory not found, or TRUE when directory exists.
+ * Check that the directory exists and is writable.
+ *
+ * Directories need to have execute permissions to be considered a directory by
+ * FTP servers, etc.
+ *
+ * @param $directory
+ *   A string containing the name of a directory path.
+ * @param $mode
+ *   A Boolean value to indicate if the directory should be created if it does
+ *   not exist or made writable if it is read-only.
+ * @param $form_item
+ *   An optional string containing the name of a form item that any errors will
+ *   be attached to. This is useful for settings forms that require the user to
+ *   specify a writable directory. If it can't be made to work, a form error
+ *   will be set preventing them from saving the settings.
+ * @return
+ *   FALSE when directory not found, or TRUE when directory exists.
  */
 function file_check_directory(&$directory, $mode = FALSE, $form_item = NULL) {
   $directory = rtrim($directory, '/\\');
@@ -199,10 +207,11 @@ function file_check_directory(&$directory, $mode = FALSE, $form_item = NULL) {
 /**
  * Checks path to see if it is a directory, or a directory/file.
  *
- * @param $path A string containing a file path. This will be set to the
- *   directory's path.
- * @return If the directory is not in a Drupal writable directory, FALSE is
- *   returned. Otherwise, the base name of the path is returned.
+ * @param $path
+ *   A string containing a file path. This will be set to the directory's path.
+ * @return
+ *   If the directory is not in a Drupal writable directory, FALSE is returned.
+ *   Otherwise, the base name of the path is returned.
  */
 function file_check_path(&$path) {
   // Check if path is a directory.
@@ -232,10 +241,13 @@ function file_check_path(&$path) {
  *   file_check_location('/www/example.com/files/../../../etc/passwd', '/www/example.com/files');
  * @endcode
  *
- * @param $source A string set to the file to check.
- * @param $directory A string where the file should be located.
- * @return FALSE if the path does not exist in the directory;
- *   otherwise, the real path of the source.
+ * @param $source
+ *   A string set to the file to check.
+ * @param $directory
+ *   A string where the file should be located.
+ * @return
+ *   FALSE if the path does not exist in the directory; otherwise, the real
+ *   path of the source.
  */
 function file_check_location($source, $directory = '') {
   $check = realpath($source);
@@ -315,6 +327,7 @@ function file_load($param, $reset = NULL) {
  *   A file object returned by file_load().
  * @return
  *   The updated file object.
+ *
  * @see hook_file_insert()
  * @see hook_file_update()
  */
@@ -365,6 +378,7 @@ function file_save($file) {
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
  *   File object if the copy is successful, or FALSE in the event of an error.
+ *
  * @see file_unmanaged_copy()
  * @see hook_file_copy()
  */
@@ -410,6 +424,7 @@ function file_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME)
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
  *   The path to the new file, or FALSE in the event of an error.
+ *
  * @see file_copy()
  */
 function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
@@ -463,13 +478,16 @@ function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXIST
  * Determines the destination path for a file depending on how replacement of
  * existing files should be handled.
  *
- * @param $destination A string specifying the desired path.
- * @param $replace Replace behavior when the destination file already exists.
+ * @param $destination
+ *   A string specifying the desired path.
+ * @param $replace
+ *   Replace behavior when the destination file already exists.
  *   - FILE_EXISTS_REPLACE - Replace the existing file.
  *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is
  *                          unique.
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
- * @return The destination file path or FALSE if the file already exists and
+ * @return
+ *   The destination file path or FALSE if the file already exists and
  *   FILE_EXISTS_ERROR was specified.
  */
 function file_destination($destination, $replace) {
@@ -517,6 +535,7 @@ function file_destination($destination, $replace) {
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
  *   Resulting file object for success, or FALSE in the event of an error.
+ *
  * @see file_unmanaged_move()
  * @see hook_file_move()
  */
@@ -554,6 +573,7 @@ function file_move($source, $destination = NULL, $replace = FILE_EXISTS_RENAME)
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
  *   The filepath of the moved file, or FALSE in the event of an error.
+ *
  * @see file_move()
  */
 function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
@@ -565,15 +585,18 @@ function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXIST
 }
 
 /**
- * Munge the filename as needed for security purposes. For instance the file
- * name "exploit.php.pps" would become "exploit.php_.pps".
- *
- * @param $filename The name of a file to modify.
- * @param $extensions A space separated list of extensions that should not
- *   be altered.
- * @param $alerts Whether alerts (watchdog, drupal_set_message()) should be
- *   displayed.
- * @return $filename The potentially modified $filename.
+ * Munge the filename as needed for security purposes.
+ *
+ * For instance the file name "exploit.php.pps" would become "exploit.php_.pps".
+ *
+ * @param $filename
+ *   The name of a file to modify.
+ * @param $extensions
+ *   A space separated list of extensions that should not be altered.
+ * @param $alerts
+ *   Whether alerts (watchdog, drupal_set_message()) should be displayed.
+ * @return
+ *   $filename The potentially modified $filename.
  */
 function file_munge_filename($filename, $extensions, $alerts = TRUE) {
   $original = $filename;
@@ -610,20 +633,28 @@ function file_munge_filename($filename, $extensions, $alerts = TRUE) {
 /**
  * Undo the effect of upload_munge_filename().
  *
- * @param $filename string filename
- * @return string
+ * @param $filename
+ *   String with the filename to be unmunged.
+ * @return
+ *   An unmunged filename string.
  */
 function file_unmunge_filename($filename) {
   return str_replace('_.', '.', $filename);
 }
 
 /**
- * Create a full file path from a directory and filename. If a file with the
- * specified name already exists, an alternative will be used.
+ * Create a full file path from a directory and filename.
+ *
+ * If a file with the specified name already exists, an alternative will be
+ * used.
  *
- * @param $basename string filename
- * @param $directory string directory
+ * @param $basename
+ *   String filename
+ * @param $directory
+ *   String directory
  * @return
+ *   File path consisting of $directory and a unique filename based off
+ *   of $basename.
  */
 function file_create_filename($basename, $directory) {
   $destination = $directory . '/' . $basename;
@@ -665,6 +696,7 @@ function file_create_filename($basename, $directory) {
  *   TRUE for success, FALSE in the event of an error, or an array if the file
  *   is being used by another module. The array keys are the module's name and
  *   the values are the number of references.
+ *
  * @see file_unmanaged_delete()
  * @see hook_file_references()
  * @see hook_file_delete()
@@ -703,6 +735,7 @@ function file_delete($file, $force = FALSE) {
  * @return
  *   TRUE for success or path does not exist, or FALSE in the event of an
  *   error.
+ *
  * @see file_delete()
  */
 function file_unmanaged_delete($path) {
@@ -743,8 +776,7 @@ function file_space_used($uid = NULL, $status = FILE_STATUS_PERMANENT) {
 }
 
 /**
- * Saves a file upload to a new location. The source file is validated as a
- * proper upload and handled as such.
+ * Saves a file upload to a new location.
  *
  * The file will be added to the files table as a temporary file. Temporary
  * files are periodically cleaned. To make the file permanent file call
@@ -754,11 +786,7 @@ function file_space_used($uid = NULL, $status = FILE_STATUS_PERMANENT) {
  *   A string specifying the name of the upload field to save.
  * @param $validators
  *   An optional, associative array of callback functions used to validate the
- *   file. The keys are function names and the values arrays of callback
- *   parameters which will be passed in after the user and file objects. The
- *   functions should return an array of error messages, an empty array
- *   indicates that the file passed validation. The functions will be called in
- *   the order specified.
+ *   file. See @file_validate for a full discussion of the array format.
  * @param $destination
  *   A string containing the directory $source should be copied to. If this is
  *   not provided or is not writable, the temporary directory will be used.
@@ -896,6 +924,7 @@ function file_save_upload($source, $validators = array(), $destination = FALSE,
  *   the order specified.
  * @return
  *   An array contaning validation error messages.
+ *
  * @see hook_file_validate()
  */
 function file_validate(&$file, $validators = array()) {
@@ -940,6 +969,8 @@ function file_validate_name_length($file) {
  * @return
  *   An array. If the file extension is not allowed, it will contain an error
  *   message.
+ *
+ * @see hook_file_validate()
  */
 function file_validate_extensions($file, $extensions) {
   global $user;
@@ -954,8 +985,9 @@ function file_validate_extensions($file, $extensions) {
 }
 
 /**
- * Check that the file's size is below certain limits. This check is not
- * enforced for the user #1.
+ * Check that the file's size is below certain limits.
+ *
+ * This check is not enforced for the user #1.
  *
  * @param $file
  *   A Drupal file object.
@@ -968,6 +1000,8 @@ function file_validate_extensions($file, $extensions) {
  * @return
  *   An array. If the file size exceeds limits, it will contain an error
  *   message.
+ *
+ * @see hook_file_validate()
  */
 function file_validate_size($file, $file_limit = 0, $user_limit = 0) {
   global $user;
@@ -994,6 +1028,8 @@ function file_validate_size($file, $file_limit = 0, $user_limit = 0) {
  *   A Drupal file object.
  * @return
  *   An array. If the file is not an image, it will contain an error message.
+ *
+ * @see hook_file_validate()
  */
 function file_validate_is_image(&$file) {
   $errors = array();
@@ -1008,7 +1044,10 @@ function file_validate_is_image(&$file) {
 
 /**
  * If the file is an image verify that its dimensions are within the specified
- * maximum and minimum dimensions. Non-image files will be ignored.
+ * maximum and minimum dimensions.
+ *
+ * Non-image files will be ignored. If a image toolkit is available the image
+ * will be scalled to fit within the desired maximum dimensions.
  *
  * @param $file
  *   A Drupal file object. This function may resize the file affecting its
@@ -1024,6 +1063,8 @@ function file_validate_is_image(&$file) {
  * @return
  *   An array. If the file is an image and did not meet the requirements, it
  *   will contain an error message.
+ *
+ * @see hook_file_validate()
  */
 function file_validate_image_resolution(&$file, $maximum_dimensions = 0, $minimum_dimensions = 0) {
   $errors = array();
@@ -1078,6 +1119,7 @@ function file_validate_image_resolution(&$file, $maximum_dimensions = 0, $minimu
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
  *   A file object, or FALSE on error.
+ *
  * @see file_unmanaged_save_data()
  */
 function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
@@ -1117,6 +1159,7 @@ function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAM
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
  *   A string with the path of the resulting file, or FALSE on error.
+ *
  * @see file_save_data()
  */
 function file_unmanaged_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
@@ -1145,6 +1188,7 @@ function file_unmanaged_save_data($data, $destination = NULL, $replace = FILE_EX
  * @return
  *   File object if the change is successful, or FALSE in the event of an
  *   error.
+ *
  * @see hook_file_status()
  */
 function file_set_status($file, $status = FILE_STATUS_PERMANENT) {
@@ -1200,7 +1244,7 @@ function file_transfer($source, $headers) {
 }
 
 /**
- * Menu handler private file transfers.
+ * Menu handler for 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 a module
@@ -1236,6 +1280,7 @@ function file_download() {
 
 /**
  * Finds all files that match a given mask in a given directory.
+ *
  * Directories and files beginning with a period are excluded; this
  * prevents hidden files and directories (such as SVN working directories)
  * from being scanned.
@@ -1261,7 +1306,6 @@ function file_download() {
  * @param $depth
  *   Current depth of recursion. This parameter is only used internally and
  *   should not be passed.
- *
  * @return
  *   An associative array (keyed on the provided key) of objects with
  *   "path", "basename", and "name" members corresponding to the
@@ -1304,7 +1348,8 @@ function file_scan_directory($dir, $mask, $nomask = array('.', '..', 'CVS'), $ca
 /**
  * Determine the default temporary directory.
  *
- * @return A string containing a temp directory.
+ * @return
+ *   A string containing a temp directory.
  */
 function file_directory_temp() {
   $temporary_directory = variable_get('file_directory_temp', NULL);
@@ -1343,7 +1388,8 @@ function file_directory_temp() {
 /**
  * Determine the default 'files' directory.
  *
- * @return A string containing the path to Drupal's 'files' directory.
+ * @return
+ *   A string containing the path to Drupal's 'files' directory.
  */
 function file_directory_path() {
   return variable_get('file_directory_path', conf_path() . '/files');