From 9cb09fd090f8febf8265d2e6af0313e4ad972e43 Mon Sep 17 00:00:00 2001
From: Andrew Nacin <nacin@git.wordpress.org>
Date: Wed, 27 Oct 2010 22:24:06 +0000
Subject: [PATCH] Docs for wp-admin/includes/file.php. props sivel, see #14783.

git-svn-id: https://develop.svn.wordpress.org/trunk@16024 602fd350-edb4-49c9-b593-d223f7449a82
---
 wp-admin/includes/file.php | 79 ++++++++++++++++++++++++++------------
 1 file changed, 54 insertions(+), 25 deletions(-)

diff --git a/wp-admin/includes/file.php b/wp-admin/includes/file.php
index 230b806b8a..2d3b282e28 100644
--- a/wp-admin/includes/file.php
+++ b/wp-admin/includes/file.php
@@ -39,12 +39,15 @@ $wp_file_descriptions = array (
 	'wp-layout.css' => __( 'Stylesheet' ), 'wp-comments.php' => __( 'Comments Template' ), 'wp-comments-popup.php' => __( 'Popup Comments Template' ));
 
 /**
- * {@internal Missing Short Description}}
+ * Get the description for standard WordPress theme files and other various standard
+ * WordPress files
  *
- * @since unknown
+ * @since 1.5.0
  *
- * @param unknown_type $file
- * @return unknown
+ * @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 ) {
 	global $wp_file_descriptions;
@@ -62,11 +65,12 @@ function get_file_description( $file ) {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Get the absolute filesystem path to the root of the WordPress installation
  *
- * @since unknown
+ * @since 1.5.0
  *
- * @return unknown
+ * @uses get_option
+ * @return string Full filesystem path to the root of the WordPress installation
  */
 function get_home_path() {
 	$home = get_option( 'home' );
@@ -84,12 +88,18 @@ function get_home_path() {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Get the real file system path to a file to edit within the admin
  *
- * @since unknown
+ * 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
  *
- * @param unknown_type $file
- * @return unknown
+ * @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 ) {
 	if ('index.php' == $file || '.htaccess' == $file ) {
@@ -201,13 +211,17 @@ function wp_tempnam($filename = '', $dir = '') {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Make sure that the file that was requested to edit, is allowed to be edited
  *
- * @since unknown
+ * Function will die if if you are not allowed to edit the file
  *
- * @param unknown_type $file
- * @param unknown_type $allowed_files
- * @return unknown
+ * @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 = '' ) {
 	$code = validate_file( $file, $allowed_files );
@@ -228,10 +242,19 @@ function validate_file_to_edit( $file, $allowed_files = '' ) {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * 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 unknown
+ * @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 ).
  * @return array On success, returns an associative array of file attributes. On failure, returns $overrides['upload_error_handler'](&$file, $message ) or array( 'error'=>$message ).
@@ -352,15 +375,21 @@ function wp_handle_upload( &$file, $overrides = false, $time = null ) {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * 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.
  *
- * Pass this function an array similar to that of a $_FILES POST array.
+ * @since 2.6.0
  *
- * @since unknown
- *
- * @param unknown_type $file
- * @param unknown_type $overrides
- * @return unknown
+ * @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 ) {
 	// The default error handler.