diff --git includes/file.inc includes/file.inc
index 19c534f..a64d3fa 100644
--- includes/file.inc
+++ includes/file.inc
@@ -98,12 +98,19 @@ define('FILE_EXISTS_ERROR', 2);
 define('FILE_STATUS_PERMANENT', 1);
 
 /**
- * Create the download path to a file.
+ * Creates the web accessible URL to a stream.
+ *
+ * Compatibility: only stream wrappers.
+ * @see http://drupal.org/node/515192
  *
  * @param $uri
- *   A string containing the URI of the file to generate a URL for.
+ *   A string containing the URI to verify. If this value is omitted,
+ *   Drupal's public files directory will be used [public://].
  * @return
- *   A string containing a URL that can be used to download the file.
+ *   Returns a string containing a URL that may be used to access the stream.
+ *   If the provided string already contains a preceding 'http', nothing is done
+ *   and the same string is returned. If a Valid stream wrapper could not be found
+ *   to generate an external Url, then FALSE will be returned.
  */
 function file_create_url($uri) {
   // Flat out check for http so that we don't have to actually implement getExternalUrl()
@@ -122,8 +129,11 @@ function file_create_url($uri) {
 }
 
 /**
- * Make sure the destination is a complete path and resides in the file system
- * directory, if it is not prepend the file system directory.
+ * Asserts that the URI is a complete path that resides in a valid
+ * filesystem directory.
+ *
+ * Compatibility: normal paths and stream wrappers.
+ * @see http://drupal.org/node/515192
  *
  * @param $uri
  *   A string containing the URI to verify. If this value is omitted,
@@ -174,11 +184,14 @@ function file_create_path($uri = NULL, $stream = TRUE) {
 }
 
 /**
- * Check that the directory exists and is writable.
+ * Asserts that the directory exists and is writable.
  *
  * Directories need to have execute permissions to be considered a directory by
  * FTP servers, etc.
  *
+ * Compatibility: normal paths and stream wrappers.
+ * @see http://drupal.org/node/515192
+ *
  * @param &$directory
  *   A string reference containing the name of a directory path.
  * @param $mode
@@ -186,12 +199,12 @@ function file_create_path($uri = NULL, $stream = TRUE) {
  *   not exist (FILE_CREATE_DIRECTORY) or made writable if it is read-only
  *   (FILE_MODIFY_PERMISSIONS).
  * @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.
+ *   An optional string containing the name of a form item. Any errors will be
+ *   attached to this item making it 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
- *   Returns TRUE if the directory exists and is wriable. Otherwise, FALSE
+ *   Returns TRUE if the directory exists and is writable. Otherwise, FALSE
  *   is returned.
  */
 function file_check_directory(&$directory, $mode = 0, $form_item = NULL) {
@@ -256,13 +269,16 @@ function file_check_directory(&$directory, $mode = 0, $form_item = NULL) {
 }
 
 /**
- * Checks path to see if it is a directory, or a directory/file.
+ * Determines whether a path is a directory, or a directory/file.
+ *
+ * Compatibility: normal paths and stream wrappers.
+ * @see http://drupal.org/node/515192
  *
  * @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.
+ *   Returns the basename of the path. If the directory is not in a Drupal
+ *   writable directory FALSE is returned.
  */
 function file_check_path(&$path) {
   // Check if path is a directory.
@@ -281,7 +297,7 @@ function file_check_path(&$path) {
 }
 
 /**
- * Check if a file is really located inside $directory.
+ * Assert that a file is located inside the specified directory.
  *
  * This should be used to make sure a file specified is really located within
  * the directory to prevent exploits. Note that the file or path being checked
@@ -295,13 +311,16 @@ function file_check_path(&$path) {
  *   file_check_location('public://dir1/../example.txt', 'public://');
  * @endcode
  *
+ * Compatibility: normal paths and stream wrappers.
+ * @see http://drupal.org/node/515192
+ *
  * @param $source
  *   A string set to the file to check. May be a literal path or a stream wrapper URI.
  * @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.
+ *   Returns FALSE if the path does not exist in the directory. Otherwise,
+ *   returns the real path of the source.
  */
 function file_check_location($source, $directory = '') {
   $original_source = $source;
@@ -330,11 +349,11 @@ function file_check_location($source, $directory = '') {
 }
 
 /**
- * Load file objects from the database.
+ * Loads multiple file objects from the database.
  *
- * @param $fids
+ * @param array $fids
  *   An array of file IDs.
- * @param $conditions
+ * @param array $conditions
  *   An array of conditions to match against the {file} table. These
  *   should be supplied in the form array('field_name' => 'field_value').
  * @return
@@ -371,7 +390,7 @@ function file_load_multiple($fids = array(), $conditions = array()) {
 }
 
 /**
- * Load a file object from the database.
+ * Loads a file object from the database.
  *
  * @param $fid
  *  A file ID.
@@ -387,12 +406,12 @@ 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. Re-saving an
  * existing file will not change its status.
  *
- * @param $file
+ * @param object $file
  *   A file object returned by file_load().
  * @return
  *   The updated file object.
@@ -420,7 +439,7 @@ function file_save($file) {
 }
 
 /**
- * Copy a file to a new location and adds a file record to the database.
+ * Copies a file to a new location and adds a file record to the database.
  *
  * This function should be used when manipulating files that have records
  * stored in the database. This is a powerful function that in many ways
@@ -434,12 +453,17 @@ function file_save($file) {
  *   temporary file, the resulting file will also be a temporary file.
  *   @see file_save_upload() for details on temporary files.
  *
+ * Compatibility: only stream wrappers.
+ * @see http://drupal.org/node/515192
+ *
  * @param $source
  *   A file object.
  * @param $destination
- *   A string containing the destination that $source should be copied to. This 
- *   should a stream wrapped URI. If this value is omitted, Drupal's public files
- *   directory will be used [public://].
+ *   A string containing the destination that $source should be copied to. This should
+ *   be a stream wrapper URI. If this value is omitted, Drupal's public files directory
+ *   will be used [public://].
+ *   can be a complete file path, a directory path or, if this value is 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. If a managed file with
@@ -449,7 +473,8 @@ function file_save($file) {
  *       unique.
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
- *   File object if the copy is successful, or FALSE in the event of an error.
+ *   Returns file object if the copy is successful, or FALSE in the event of an
+ *   error.
  *
  * @see file_unmanaged_copy()
  * @see hook_file_copy()
@@ -484,11 +509,13 @@ function file_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME)
 
     return $file;
   }
+
   return FALSE;
 }
 
 /**
- * Copy a file to a new location without calling any hooks or making any
+ * Copies a file to a new location without calling any hooks or making any
+ * changes to the database.
  *
  * This is a powerful function that in many ways performs like an advanced
  * version of copy().
@@ -498,6 +525,9 @@ function file_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME)
  * - If file already exists in $destination either the call will error out,
  *   replace the file or rename the file based on the $replace parameter.
  *
+ * Compatibility: normal paths and stream wrappers.
+ * @see http://drupal.org/node/515192
+ *
  * @param $source
  *   A string specifying the file location of the original file.
  * @param $destination
@@ -511,7 +541,7 @@ function file_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME)
  *       unique.
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
- *   The path to the new file, or FALSE in the event of an error.
+ *   Returns the path to the new file, or FALSE in the event of an error.
  *
  * @see file_copy()
  */
@@ -575,6 +605,9 @@ 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.
  *
+ * Compatibility: only stream wrappers.
+ * @see http://drupal.org/node/515192
+ *
  * @param $destination
  *   A string specifying the desired path.
  * @param $replace
@@ -584,8 +617,8 @@ function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXIST
  *       unique.
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
- *   The destination file path or FALSE if the file already exists and
- *   FILE_EXISTS_ERROR was specified.
+ *   Returns the destination file path, or FALSE if the file already exists
+ *   and FILE_EXISTS_ERROR is speciefied.
  */
 function file_destination($destination, $replace) {
   if (file_exists($destination)) {
@@ -609,7 +642,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.
@@ -619,6 +652,9 @@ function file_destination($destination, $replace) {
  *   replace the file or rename the file based on the $replace parameter.
  * - Adds the new file to the files database.
  *
+ * Compatibility: only stream wrappers.
+ * @see http://drupal.org/node/515192
+ *
  * @param $source
  *   A file object.
  * @param $destination
@@ -636,7 +672,8 @@ function file_destination($destination, $replace) {
  *       unique.
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
- *   Resulting file object for success, or FALSE in the event of an error.
+ *   Returns the resulting file object for success, or FALSE in the event of an
+ *   error.
  *
  * @see file_unmanaged_move()
  * @see hook_file_move()
@@ -680,9 +717,12 @@ function file_move($source, $destination = NULL, $replace = FILE_EXISTS_RENAME)
 }
 
 /**
- * Move a file to a new location without calling any hooks or making any
+ * Moves a file to a new location without calling any hooks or making any
  * changes to the database.
  *
+ * Compatibility: only stream wrappers.
+ * @see http://drupal.org/node/515192
+ *
  * @param $source
  *   A string specifying the file location of the original file.
  * @param $destination
@@ -696,7 +736,7 @@ function file_move($source, $destination = NULL, $replace = FILE_EXISTS_RENAME)
  *       unique.
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
- *   The filepath of the moved file, or FALSE in the event of an error.
+ *   Returns the file path of the moved file, or FALSE in the event of an error.
  *
  * @see file_move()
  */
@@ -709,9 +749,9 @@ function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXIST
 }
 
 /**
- * Munge the filename as needed for security purposes.
+ * Munges the filename as needed for security purposes.
  *
- * For instance the file name "exploit.php.pps" would become "exploit.php_.pps".
+ * For example, the file name "exploit.php.pps" would become "exploit.php_.pps".
  *
  * @param $filename
  *   The name of a file to modify.
@@ -755,30 +795,33 @@ function file_munge_filename($filename, $extensions, $alerts = TRUE) {
 }
 
 /**
- * Undo the effect of upload_munge_filename().
+ * Reverses the effect of file_munge_filename().
  *
  * @param $filename
  *   String with the filename to be unmunged.
  * @return
- *   An unmunged filename string.
+ *   Returns the unmunged file name.
  */
 function file_unmunge_filename($filename) {
   return str_replace('_.', '.', $filename);
 }
 
 /**
- * Create a full file path from a directory and filename.
+ * Creates a full filepath from a directory and filename.
  *
  * If a file with the specified name already exists, an alternative will be
  * used.
  *
+ * Compatibility: normal paths and stream wrappers.
+ * @see http://drupal.org/node/515192
+ *
  * @param $basename
- *   String filename
+ *   String containing the filename.
  * @param $directory
- *   String directory
+ *   String containing the directory.
  * @return
- *   File path consisting of $directory and a unique filename based off
- *   of $basename.
+ *   Returns the filepath consisting of $directory and a unique filename
+ *   based off of $basename.
  */
 function file_create_filename($basename, $directory) {
   // Are we dealing with a stream?
@@ -813,7 +856,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 hook_file_references() will be called
  * to determine if the file is being used by any modules. If the file is being
@@ -824,8 +867,8 @@ function file_create_filename($basename, $directory) {
  * @param $force
  *   Boolean indicating that the file should be deleted even if
  *   hook_file_references() reports that the file is in use.
- * @return mixed
- *   TRUE for success, FALSE in the event of an error, or an array if the file
+ * @return
+ *   Returns 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.
  *
@@ -856,17 +899,20 @@ function file_delete($file, $force = FALSE) {
 }
 
 /**
- * Delete a file without calling any hooks or making any changes to the
+ * Deletes 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.
  *
+ * Compatibility: normal paths and stream wrappers.
+ * @see http://drupal.org/node/515192
+ *
  * @param $path
  *   A string containing a file path.
  * @return
- *   TRUE for success or path does not exist, or FALSE in the event of an
- *   error.
+ *   Returns TRUE for success or the path does not exists, or FALSE in the
+ *   event of an error.
  *
  * @see file_delete()
  * @see file_unmanaged_delete_recursive()
@@ -892,7 +938,7 @@ function file_unmanaged_delete($path) {
 }
 
 /**
- * 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
@@ -903,11 +949,14 @@ function file_unmanaged_delete($path) {
  *
  * Note that this only deletes visible files with write permission.
  *
+ * Compatibility: normal paths and stream wrappers.
+ * @see http://drupal.org/node/515192
+ *
  * @param $path
  *   A string containing a file or directory path.
  * @return
- *   TRUE for success or path does not exist, or FALSE in the event of an
- *   error.
+ *   Returns TRUE for success or path does not exist, or FALSE in the event
+ *   of an error.
  *
  * @see file_unmanaged_delete()
  */
@@ -928,7 +977,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
@@ -937,7 +986,7 @@ function file_unmanaged_delete_recursive($path) {
  *   Optional. File Status to return. Combine with a bitwise OR(|) to return
  *   multiple statuses. The default status is FILE_STATUS_PERMANENT.
  * @return
- *   An integer containing the number of bytes used.
+ *   Returns an integer containing the number of bytes used.
  */
 function file_space_used($uid = NULL, $status = FILE_STATUS_PERMANENT) {
   $query = db_select('file', 'f');
@@ -958,21 +1007,27 @@ function file_space_used($uid = NULL, $status = FILE_STATUS_PERMANENT) {
  * files are periodically cleaned. To make the file a permanent file, assign
  * the status and use file_save() to save the changes.
  *
+ * Compatibility: source may be a normal path or stream, but the destination must
+ * always be a stream.
+ * @see http://drupal.org/node/515192
+ *
  * @param $source
  *   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. 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.
+ *   A string containing the location $source should be copied to within the temp directory.
+ *   $destination can be a directory or directory and filename within the temp directory.
+ *   If not provided, the temporary directory will be used, and the $replace flag will
+ *   will be honored.
  * @param $replace
  *   A boolean indicating whether an existing file of the same name in the
  *   destination directory should overwritten. A false value will generate a
  *   new, unique filename in the destination directory.
  * @return
- *   An object containing the file information if the upload succeeded, FALSE
- *   in the event of an error, or NULL if no file was uploaded.
+ *   Returns an object containing the file information if the upload succeeded,
+ *   or FALSE in the event of an error, or NULL if no file was upload.
  */
 function file_save_upload($source, $validators = array(), $destination = FALSE, $replace = FILE_EXISTS_RENAME) {
   global $user;
@@ -1104,9 +1159,8 @@ function file_save_upload($source, $validators = array(), $destination = FALSE,
   return FALSE;
 }
 
-
 /**
- * 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.
@@ -1121,7 +1175,7 @@ function file_save_upload($source, $validators = array(), $destination = FALSE,
  *   indicates that the file passed validation. The functions will be called in
  *   the order specified.
  * @return
- *   An array contaning validation error messages.
+ *   Returns an array containing validation error messages.
  *
  * @see hook_file_validate()
  */
@@ -1140,12 +1194,12 @@ function file_validate(&$file, $validators = array()) {
 }
 
 /**
- * Check for files with names longer than we can store in the database.
+ * Asserts that a filename is short enough to 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.
+ *   Returns an array containing an error message if the filename is too long.
  */
 function file_validate_name_length($file) {
   $errors = array();
@@ -1160,15 +1214,15 @@ function file_validate_name_length($file) {
 }
 
 /**
- * Check that the filename ends with an allowed extension.
+ * Asserts that the filename ends with an allowed extension.
  *
  * @param $file
  *   A Drupal file object.
  * @param $extensions
  *   A string with a space separated list of allowed extensions.
  * @return
- *   An array. If the file extension is not allowed, it will contain an error
- *   message.
+ *   Returns an array containing an error message if the file extension
+ *   is not allowed.
  *
  * @see hook_file_validate()
  */
@@ -1183,7 +1237,7 @@ function file_validate_extensions($file, $extensions) {
 }
 
 /**
- * Check that the file's size is below certain limits.
+ * Asserts that the file's size is below certain limits.
  *
  * This check is not enforced for the user #1.
  *
@@ -1196,8 +1250,8 @@ function file_validate_extensions($file, $extensions) {
  *   An integer specifying the maximum number of bytes the user is allowed.
  *   Zero indicates that no limit should be enforced.
  * @return
- *   An array. If the file size exceeds limits, it will contain an error
- *   message.
+ *   Returns an array containing an error message if the file size exceeds
+ *   limits.
  *
  * @see hook_file_validate()
  */
@@ -1221,12 +1275,12 @@ function file_validate_size($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.
  * @return
- *   An array. If the file is not an image, it will contain an error message.
+ *   Returns an array containing an error message if the file is not an image.
  *
  * @see hook_file_validate()
  */
@@ -1242,10 +1296,9 @@ function file_validate_is_image($file) {
 }
 
 /**
- * If the file is an image verify that its dimensions are within the specified
- * maximum and minimum dimensions.
+ * Asserts that the dimensions of an image are within the specified parameters.
  *
- * Non-image files will be ignored. If a image toolkit is available the image
+ * Non-image files will be ignored. If an image toolkit is available the image
  * will be scalled to fit within the desired maximum dimensions.
  *
  * @param $file
@@ -1260,8 +1313,8 @@ function file_validate_is_image($file) {
  *   An optional string in the form WIDTHxHEIGHT. This will check that the
  *   image meets a minimum size. A value of 0 indicates no restriction.
  * @return
- *   An array. If the file is an image and did not meet the requirements, it
- *   will contain an error message.
+ *   Returns an array containing an error message if the file is an image and
+ *   exceeded the specified paramaters.
  *
  * @see hook_file_validate()
  */
@@ -1300,7 +1353,10 @@ function file_validate_image_resolution($file, $maximum_dimensions = 0, $minimum
 }
 
 /**
- * Save a string to the specified destination and create a database file entry.
+ * Saves a string to the specified destination and creates a database file entry.
+ *
+ * Compatibility: only stream wrappers.
+ * @see http://drupal.org/node/515192
  *
  * @param $data
  *   A string containing the contents of the file.
@@ -1317,7 +1373,7 @@ function file_validate_image_resolution($file, $maximum_dimensions = 0, $minimum
  *       unique.
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
- *   A file object, or FALSE on error.
+ *   Returns a file object, or FALSE on error.
  *
  * @see file_unmanaged_save_data()
  */
@@ -1354,7 +1410,7 @@ function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAM
 }
 
 /**
- * Save a string to the specified destination without calling any hooks or
+ * Saves a string to the specified destination without calling any hooks or
  * making any changes to the database.
  *
  * This function is identical to file_save_data() except the file will not be
@@ -1373,7 +1429,7 @@ function file_save_data($data, $destination = NULL, $replace = FILE_EXISTS_RENAM
  *                          unique.
  *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
  * @return
- *   A string with the path of the resulting file, or FALSE on error.
+ *   Returns a string with the path of the resulting file, or FALSE on error.
  *
  * @see file_save_data()
  */
@@ -1390,13 +1446,12 @@ function file_unmanaged_save_data($data, $destination = NULL, $replace = FILE_EX
 }
 
 /**
- * Transfer file using HTTP to client. Pipes a file through Drupal to the
- * client.
+ * Pipes a file through Drupal to the client using HTTP.
  *
  * @param $source
  *   String specifying the file path to transfer.
- * @param $headers
- *   An array of HTTP headers to send along with file.
+ * @param
+ *   Returns an array of HTTP headers to send along with the file.
  */
 function file_transfer($source, $headers) {
   if (ob_get_level()) {
@@ -1424,7 +1479,7 @@ function file_transfer($source, $headers) {
 }
 
 /**
- * Menu handler for private file transfers.
+ * Menu handler for private file transfers [private://].
  *
  * 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
@@ -1432,11 +1487,13 @@ function file_transfer($source, $headers) {
  * returned headers the download will start with the returned headers. If no
  * modules respond drupal_not_found() will be returned.
  *
+ * @see http://drupal.org/node/515192
+ *
  * @see hook_file_download()
  */
 function file_download() {
   // Merge remainder of arguments from GET['q'], into relative file path.
-  $args = func_get_args();
+  $args     = func_get_args();
   $filepath = SCHEME_PRIVATE . implode('/', $args);
 
   // Maintain compatibility with old ?file=paths saved in node bodies.
@@ -1465,6 +1522,9 @@ function file_download() {
  * prevents hidden files and directories (such as SVN working directories)
  * from being scanned.
  *
+ * Compatibility: only stream wrappers.
+ * @see http://drupal.org/node/515192
+ *
  * @param $dir
  *   The base directory for the scan, without trailing slash.
  * @param $mask
@@ -1491,7 +1551,7 @@ function file_download() {
  *   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
+ *   Returns an associative array (keyed on the provided key) of objects with
  *   'filepath', 'filename', and 'name' members corresponding to the
  *   matching files.
  */
@@ -1595,11 +1655,11 @@ function file_directory_strip($path) {
 }
 
 /**
- * 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
- *   post_max_size
+ *   Returns file size limit in bytes based on the PHP upload_max_filesize
+ *   and post_max_size directives.
  */
 function file_upload_max_size() {
   static $max_size = -1;