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	14 Feb 2011 16:28:48 -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,15 @@
  * @{
  * Common file handling functions.
  *
- * Fields on the file object:
+ * The File interface contains functions for manipulating both "managed" and
+ * "unmanaged" files. Managed files are files that Drupal keeps records of (in
+ * the {file_managed} database table), and unmanaged files are files that Drupal
+ * does not keep records of. Drupal has functions for operations such as
+ * delete, copy, move, etc. on both types of files. The functions for managed
+ * files manage the database records and invoke File API hooks, in addition to
+ * the base file operations that the unmanaged functions perform.
+ *
+ * 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
@@ -753,8 +761,8 @@
  * @return
  *   File object if the copy is successful, or FALSE in the event of an error.
  *
- * @see file_unmanaged_copy()
  * @see hook_file_copy()
+ * @see file_unmanaged_copy()
  */
 function file_copy(stdClass $source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
   if (!file_valid_uri($destination)) {
@@ -794,7 +802,7 @@
 }
 
 /**
- * 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
@@ -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().
@@ -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.
@@ -985,8 +993,8 @@
  * @return
  *   Resulting file object for success, or FALSE in the event of an error.
  *
- * @see file_unmanaged_move()
  * @see hook_file_move()
+ * @see file_unmanaged_move()
  */
 function file_move(stdClass $source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
   if (!file_valid_uri($destination)) {
@@ -1031,8 +1039,7 @@
 }
 
 /**
- * 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.
  *
  * @param $source
  *   A string specifying the filepath or URI of the original file.
@@ -1209,10 +1216,10 @@
  *   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()
+ * @see file_unmanaged_delete()
  */
 function file_delete(stdClass $file, $force = FALSE) {
   if (!file_valid_uri($file->uri)) {
@@ -1243,11 +1250,7 @@
 }
 
 /**
- * Delete a file without calling any hooks or making any changes to the
- * database.
- *
- * This function should be used when the file to be deleted does not have an
- * entry recorded in the files table.
+ * Deletes a file without invoking the File API.
  *
  * @param $path
  *   A string containing a file path or (streamwrapper) URI.
@@ -1256,8 +1259,8 @@
  *   TRUE for success or path does not exist, or FALSE in the event of an
  *   error.
  *
- * @see file_delete()
  * @see file_unmanaged_delete_recursive()
+ * @see file_delete()
  */
 function file_unmanaged_delete($path) {
   // Resolve streamwrapper URI to local path.
@@ -1282,7 +1285,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 +1755,7 @@
 }
 
 /**
- * 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.
  *
  * @param $data
  *   A string containing the contents of the file.
@@ -1816,24 +1819,20 @@
 }
 
 /**
- * Save 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
- * called.
+ * Saves a string to a file without invoking the File API.
  *
  * @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