Index: includes/file.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/file.inc,v
retrieving revision 1.243
diff -u -r1.243 file.inc
--- includes/file.inc	15 Dec 2010 03:39:41 -0000	1.243
+++ includes/file.inc	10 Feb 2011 19:32:26 -0000
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * API for handling file uploads and server file management.
+ * File API - handles file uploads and server file management.
  */
 
 /**
@@ -20,7 +20,14 @@
  * @{
  * Common file handling functions.
  *
- * Fields on the file object:
+ * The File interface contains functions for handling "managed" and "unmanaged"
+ * files. Information about managed files is stored in the {file_managed}
+ * database table, and when managed files are created, deleted, etc., File API
+ * hooks are invoked. There are also functions for operations on unmanaged
+ * files, which do not have records in the database; these operations do not
+ * involve invoking File API hooks.
+ *
+ * Fields on the file object used for managed files:
  * - 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
@@ -735,6 +742,8 @@
  *   temporary file, the resulting file will also be a temporary file. See
  *   file_save_upload() for details on temporary files.
  *
+ * See file_unmanaged_copy() for the unmanaged file equivalent.
+ *
  * @param $source
  *   A file object.
  * @param $destination
@@ -753,7 +762,6 @@
  * @return
  *   File object if the copy is successful, or FALSE in the event of an error.
  *
- * @see file_unmanaged_copy()
  * @see hook_file_copy()
  */
 function file_copy(stdClass $source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
@@ -794,7 +802,7 @@
 }
 
 /**
- * Determine whether the URI has a valid scheme for file API operations.
+ * Determine 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
@@ -816,7 +824,7 @@
 }
 
 /**
- * Copies a file to a new location without invoking the file API.
+ * Copies a file to a new location without invoking the File API.
  *
  * This is a powerful function that in many ways performs like an advanced
  * version of copy().
@@ -826,6 +834,8 @@
  * - If file already exists in $destination either the call will error out,
  *   replace the file or rename the file based on the $replace parameter.
  *
+ * See file_copy() for the managed file equivalent.
+ *
  * @param $source
  *   A string specifying the filepath or URI of the source file.
  * @param $destination
@@ -842,8 +852,6 @@
  *
  * @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) {
   $original_source = $source;
@@ -955,7 +963,7 @@
 }
 
 /**
- * Move a file to a new location and update the file's database entry.
+ * Moves a file to a new location and updates the file's database entry.
  *
  * Moving a file is performed by copying the file to the new location and then
  * deleting the original.
@@ -965,6 +973,8 @@
  *   replace the file or rename the file based on the $replace parameter.
  * - Adds the new file to the files database.
  *
+ * See file_unmanaged_move() for the unmanaged file equivalent.
+ *
  * @param $source
  *   A file object.
  * @param $destination
@@ -985,7 +995,6 @@
  * @return
  *   Resulting file object for success, or FALSE in the event of an error.
  *
- * @see file_unmanaged_move()
  * @see hook_file_move()
  */
 function file_move(stdClass $source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
@@ -1031,8 +1040,9 @@
 }
 
 /**
- * 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 invoking the File API.
+ *
+ * See file_move() for the managed file equivalent.
  *
  * @param $source
  *   A string specifying the filepath or URI of the original file.
@@ -1049,8 +1059,6 @@
  *
  * @return
  *   The URI 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) {
   $filepath = file_unmanaged_copy($source, $destination, $replace);
@@ -1199,6 +1207,8 @@
  * determine if the file is being used by any modules. If the file is being
  * used the delete will be canceled.
  *
+ * See file_unmanaged_delete() for the unmanaged file equivalent.
+ *
  * @param $file
  *   A file object.
  * @param $force
@@ -1209,7 +1219,6 @@
  *   TRUE for success, FALSE in the event of an error, or an array if the file
  *   is being used by any modules.
  *
- * @see file_unmanaged_delete()
  * @see file_usage_list()
  * @see file_usage_delete()
  * @see hook_file_delete()
@@ -1243,11 +1252,9 @@
 }
 
 /**
- * Delete a file without calling any hooks or making any changes to the
- * database.
+ * Deletes a file without invoking the File API.
  *
- * This function should be used when the file to be deleted does not have an
- * entry recorded in the files table.
+ * See file_delete() for the managed file equivalent.
  *
  * @param $path
  *   A string containing a file path or (streamwrapper) URI.
@@ -1256,7 +1263,6 @@
  *   TRUE for success or path does not exist, or FALSE in the event of an
  *   error.
  *
- * @see file_delete()
  * @see file_unmanaged_delete_recursive()
  */
 function file_unmanaged_delete($path) {
@@ -1282,7 +1288,7 @@
 }
 
 /**
- * Recursively delete all files and directories in the specified filepath.
+ * Recursively deletes all files and directories in the specified filepath.
  *
  * 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
@@ -1752,7 +1758,9 @@
 }
 
 /**
- * Save a string to the specified destination and create a database file entry.
+ * Saves a string to a file and adds a file record to the database.
+ *
+ * See file_unmanaged_save_data() for the unmanaged file equivalent.
  *
  * @param $data
  *   A string containing the contents of the file.
@@ -1771,8 +1779,6 @@
  *
  * @return
  *   A file object, or FALSE on error.
- *
- * @see file_unmanaged_save_data()
  */
 function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
   global $user;
@@ -1816,30 +1822,26 @@
 }
 
 /**
- * Save a string to the specified destination without invoking file API.
+ * Saves a string to a file without invoking the 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
- * called.
+ * See file_save_data() for the managed file equivalent.
  *
  * @param $data
  *   A string containing the contents of the file.
  * @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 is saved using Drupal's
- *   default files scheme, usually "public://".
+ *   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://".
  * @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.
+ *     unique.
  *   - 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) {
   // Write the data to a temporary file.