Changeset 16024 for trunk/wp-admin/includes/file.php

Timestamp:

10/27/2010 10:24:06 PM (15 years ago)

Author:

nacin

Message:

Docs for wp-admin/includes/file.php. props sivel, see #14783.

File:

• trunk/wp-admin/includes/file.php (modified) (6 diffs)

trunk/wp-admin/includes/file.php

@@ -40 +40 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @param unknown_type $file
- * @return unknown
+ * Get the description for standard WordPress theme files and other various standard
+ * WordPress files
+ *
+ * @since 1.5.0
+ *
+ * @uses _cleanup_header_comment
+ * @uses $wp_file_descriptions
+ * @param string $file Filesystem path or filename
+ * @return string Description of file from $wp_file_descriptions or basename of $file if description doesn't exist
  */
 function get_file_description( $file ) {
@@ -63 +66 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @return unknown
+ * Get the absolute filesystem path to the root of the WordPress installation
+ *
+ * @since 1.5.0
+ *
+ * @uses get_option
+ * @return string Full filesystem path to the root of the WordPress installation
  */
 function get_home_path() {
@@ -85 +89 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @param unknown_type $file
- * @return unknown
+ * Get the real file system path to a file to edit within the admin
+ *
+ * If the $file is index.php or .htaccess this function will assume it is relative
+ * to the install root, otherwise it is assumed the file is relative to the wp-content
+ * directory
+ *
+ * @since 1.5.0
+ *
+ * @uses get_home_path 
+ * @uses WP_CONTENT_DIR full filesystem path to the wp-content directory
+ * @param string $file filesystem path relative to the WordPress install directory or to the wp-content directory
+ * @return string full file system path to edit
  */
 function get_real_file_to_edit( $file ) {
@@ -202 +212 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @param unknown_type $file
- * @param unknown_type $allowed_files
- * @return unknown
+ * Make sure that the file that was requested to edit, is allowed to be edited
+ *
+ * Function will die if if you are not allowed to edit the file
+ *
+ * @since 1.5.0
+ *
+ * @uses wp_die
+ * @uses validate_file
+ * @param string $file file the users is attempting to edit
+ * @param array $allowed_files Array of allowed files to edit, $file must match an entry exactly
+ * @return null
  */
 function validate_file_to_edit( $file, $allowed_files = '' ) {
@@ -229 +243 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
+ * Handle PHP uploads in WordPress, sanitizing file names, checking extensions for mime type,
+ * and moving the file to the appropriate directory within the uploads directory.
+ *
+ * @since 2.0
+ *
+ * @uses wp_handle_upload_error
+ * @uses apply_filters
+ * @uses is_multisite
+ * @uses wp_check_filetype_and_ext
+ * @uses current_user_can
+ * @uses wp_upload_dir
+ * @uses wp_unique_filename
+ * @uses delete_transient   
  * @param array $file Reference to a single element of $_FILES. Call the function once for each uploaded file.
  * @param array $overrides Optional. An associative array of names=>values to override default variables with extract( $overrides, EXTR_OVERWRITE ).
@@ -353 +376 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * Pass this function an array similar to that of a $_FILES POST array.
- *
- * @since unknown
- *
- * @param unknown_type $file
- * @param unknown_type $overrides
- * @return unknown
+ * Handle sideloads, which is the process of retriving a media item from another server instead of
+ * a traditional media upload.  This process involves sanitizing the filename, checking extensions
+ * for mime type, and moving the file to the appropriate directory within the uploads directory.
+ *
+ * @since 2.6.0
+ *
+ * @uses wp_handle_upload_error
+ * @uses apply_filters
+ * @uses wp_check_filetype_and_ext
+ * @uses current_user_can
+ * @uses wp_upload_dir
+ * @uses wp_unique_filename
+ * @param array $file an array similar to that of a PHP $_FILES POST array
+ * @param array $overrides Optional. An associative array of names=>values to override default variables with extract( $overrides, EXTR_OVERWRITE ).
+ * @return array On success, returns an associative array of file attributes. On failure, returns $overrides['upload_error_handler'](&$file, $message ) or array( 'error'=>$message ).
  */
 function wp_handle_sideload( &$file, $overrides = false ) {