Ticket #14928: 14928.docs-only.patch

wp-includes/functions.php

@@ -2015 +2015 @@
 }
 
 /**
+ * Make Directories.
+ *
  * Recursive directory creation based on full path.
+ * Attempts to set permissions on newly created folders.
  *
- * Will attempt to set permissions on folders.
+ * As php mkdir() (PHP < 5.0.0) does not support recursive paths, this function mimics 
+ * the *nix `mkdir -p` / `mkdir --parent` command.
  *
+ * In difference to mkdir, the permissions set on newly created folders 
+ * is based on the parent folder permissions - not umask.
+ *
+ * @link http://www.gnu.org/software/coreutils/manual/coreutils.html#mkdir-invocation
+ * @link http://php.net/mkdir
  * @since 2.0.1
  *
- * @param string $target Full path to attempt to create.
- * @return bool Whether the path was created. True if path already exists.
+ * @param string $target Path of a directory to create.
+ * @return bool Whether the target path exists (already or just created does not make a difference).
  */
 function wp_mkdir_p( $target ) {
-        // from php.net/mkdir user contributed notes
+        // undocumented, from a removed php.net/mkdir user contributed notes
         $target = str_replace( '//', '/', $target );
 
         // safe mode fails with a trailing slash under certain PHP versions.
@@ -2033 +2042 @@
         if ( empty($target) )
                 $target = '/';
 
+        // Handle existing target.
         if ( file_exists( $target ) )
                 return @is_dir( $target );