Index: includes/file.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/file.inc,v
retrieving revision 1.121.2.9
diff -u -r1.121.2.9 file.inc
--- includes/file.inc	16 Sep 2009 19:34:14 -0000	1.121.2.9
+++ includes/file.inc	30 Sep 2009 16:45:05 -0000
@@ -195,23 +195,28 @@
 }
 
 /**
- * Copies a file to a new location. This is a powerful function that in many ways
- * performs like an advanced version of copy().
- * - Checks if $source and $dest are valid and readable/writable.
+ * Copies a file to a new location.
+ *
+ * This function performs the following steps:
+ * - Checks whether $source and $dest are valid and readable/writable. $dest
+ *   must be within the Drupal files or temp directory to be valid.
  * - Performs a file copy if $source is not equal to $dest.
- * - If file already exists in $dest either the call will error out, replace the
- *   file or rename the file based on the $replace parameter.
+ * - If file already exists in $dest, either triggers an error, replaces
+ *   the file, or renames the file, based on the value of $replace.
+ *
+ * @see file_move()
  *
  * @param $source A string specifying the file location of the original file.
- *   This parameter will contain the resulting destination filename in case of
+ *   Replaced by the full path of the resulting destination filename in case of
  *   success.
  * @param $dest A string containing the directory $source should be copied to.
- *   If this value is omitted, Drupal's 'files' directory will be used.
- * @param $replace Replace behavior when the destination file already exists.
+ *   Must be within Drupal's files or temp directory; if omitted, Drupal's 
+ *   files directory will be used.
  *   - FILE_EXISTS_REPLACE - Replace the existing file
- *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique
+ *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename
+ *     is unique
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
- * @return True for success, FALSE for failure.
+ * @return TRUE for success, FALSE for failure.
  */
 function file_copy(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME) {
   $dest = file_create_path($dest);
@@ -311,21 +316,28 @@
 
 /**
  * Moves a file to a new location.
- * - Checks if $source and $dest are valid and readable/writable.
+ *
+ * This function performs the following steps:
+ * - Checks whether $source and $dest are valid and readable/writable. $dest
+ *   must be within the Drupal files or temp directory to be valid.
  * - Performs a file move if $source is not equal to $dest.
- * - If file already exists in $dest either the call will error out, replace the
- *   file or rename the file based on the $replace parameter.
+ * - If file already exists in $dest, either triggers an error, replaces
+ *   the file, or renames the file, based on the value of $replace.
+ *
+ * @see file_copy()
  *
  * @param $source A string specifying the file location of the original file.
- *   This parameter will contain the resulting destination filename in case of
+ *   Replaced by the full path of the resulting destination filename in case of
  *   success.
- * @param $dest A string containing the directory $source should be copied to.
- *   If this value is omitted, Drupal's 'files' directory will be used.
- * @param $replace Replace behavior when the destination file already exists.
+ * @param $dest A string containing the directory $source should be moved to.
+ *   Must be within Drupal's files or temp directory; if omitted, Drupal's 
+ *   files directory will be used.
+ * @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_RENAME - Append _{incrementing number} until the filename
+ *     is unique
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
- * @return True for success, FALSE for failure.
+ * @return TRUE for success, FALSE for failure.
  */
 function file_move(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME) {
   $path_original = is_object($source) ? $source->filepath : $source;