- Patch #594518 by jhodgdon: better documentation for file_munge_filename().

includes/file.inc

@@ -797,18 +797,24 @@ function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXIST
 }
 
 /**
- * Munge the filename as needed for security purposes.
+ * Modify a filename as needed for security purposes.
  *
- * For instance the file name "exploit.php.pps" would become "exploit.php_.pps".
+ * Dangerous file names will be altered; for instance, the file name
+ * "exploit.php.pps" will become "exploit.php_.pps". All extensions that are
+ * between 2 and 5 characters in length, internal to the file name, and not
+ * included in $extensions will be altered by adding an underscore. If variable
+ * 'allow_insecure_uploads' evaluates to TRUE, no alterations will be made.
  *
  * @param $filename
- *   The name of a file to modify.
+ *   File name to modify.
  * @param $extensions
- *   A space separated list of extensions that should not be altered.
+ *   A space-separated list of extensions that should not be altered.
  * @param $alerts
- *   Whether alerts (watchdog, drupal_set_message()) should be displayed.
+ *   If TRUE, drupal_set_message() will be called to display a message if the
+ *   file name was changed.
+ *
  * @return
- *   $filename The potentially modified $filename.
+ *   The potentially modified $filename.
  */
 function file_munge_filename($filename, $extensions, $alerts = TRUE) {
   $original = $filename;