=== modified file 'wp-admin/admin-functions.php'
--- wp-admin/admin-functions.php	2007-03-13 23:54:45 +0000
+++ wp-admin/admin-functions.php	2007-03-15 17:32:54 +0000
@@ -1,5 +1,19 @@
 <?php
+/**
+ * admin-functions
+ *
+ * @author Wordpress team (FIXME)
+ * @version "$Id$"
+ * @copyright FIXME
+ * @package wordpress
+ * @subpackage admin-functions
+ */
 
+/**
+ * calls wp_write_post and handles the errors
+ *
+ * @return int post ID, dies in case of failure
+ */
 function write_post() {
 	$result = wp_write_post();
 	if( is_wp_error( $result ) )
@@ -8,7 +22,11 @@
 		return $result;
 }
 
-// Creates a new post from the "Write Post" form using $_POST information.
+/**
+ * Creates a new post from the "Write Post" form using $_POST information.
+ *
+ * @return mixed post ID on success, Wp_Error on failure
+ */
 function wp_write_post() {
 	global $user_ID;
 
@@ -131,7 +149,13 @@
 	return $post_ID;
 }
 
-// Move child posts to a new parent
+/**
+ * Move child posts to a new parent
+ *
+ * @param int $old_ID current parent ID
+ * @param int $new_ID ID of the new parent
+ * @return mixed number of affected rows on success, false on failure
+ */
 function relocate_children( $old_ID, $new_ID ) {
 	global $wpdb;
 	$old_ID = (int) $old_ID;
@@ -139,7 +163,12 @@
 	return $wpdb->query( "UPDATE $wpdb->posts SET post_parent = $new_ID WHERE post_parent = $old_ID" );
 }
 
-// Replace hrefs of attachment anchors with up-to-date permalinks.
+/**
+ * Replace hrefs of attachment anchors with up-to-date permalinks.
+ *
+ * @param int $post_ID
+ * @return int post ID 
+ */
 function fix_attachment_links( $post_ID ) {
 	global $wp_rewrite;
 
@@ -181,7 +210,12 @@
 	return wp_update_post( $post);
 }
 
-// Update an existing post with values provided in $_POST.
+/**
+ * Update an existing post with values provided in $_POST.
+ *
+ * @filter autosave_interval
+ * @return int post ID or dies on wrong permissions
+ */
 function edit_post() {
 	global $user_ID;
 
@@ -299,6 +333,11 @@
 	return $post_ID;
 }
 
+/**
+ * update a comment using data from $_POST
+ *
+ * @return int number of affected rows
+ */
 function edit_comment() {
 	global $user_ID;
 
@@ -332,7 +371,15 @@
 	wp_update_comment( $_POST);
 }
 
-// Get an existing post and format it for editing.
+/**
+ * Get an existing post and format it for editing.
+ *
+ * @filter content_edit_pre
+ * @filter excerpt_edit_pre
+ * @filter title_edit_pre
+ * @param int $id post ID
+ * @return object post
+ */
 function get_post_to_edit( $id ) {
 
 	$post = get_post( $id );
@@ -354,7 +401,14 @@
 	return $post;
 }
 
-// Default post information to use when populating the "Write Post" form.
+/**
+ * Default post information to use when populating the "Write Post" form.
+ *
+ * @filter default_content
+ * @filter default_title
+ * @filter default_excerpt
+ * @return object
+ */
 function get_default_post_to_edit() {
 	if ( !empty( $_REQUEST['post_title'] ) )
 		$post_title = wp_specialchars( stripslashes( $_REQUEST['post_title'] ));
@@ -394,6 +448,12 @@
 	return $post;
 }
 
+/**
+ * get a comment and format it for editing
+ *
+ * @filter comment_edit_pre
+ * @return object comment
+ */
 function get_comment_to_edit( $id ) {
 	$comment = get_comment( $id );
 
@@ -407,6 +467,12 @@
 	return $comment;
 }
 
+/**
+ * get a category for editing
+ *
+ * @param int $id category ID
+ * @return object 
+ */
 function get_category_to_edit( $id ) {
 	$category = get_category( $id );
 
@@ -425,6 +491,12 @@
 }
 
 
+/**
+ * get user information and format it for editing
+ *
+ * @param int $user_id user ID
+ * @return object
+ */
 function get_user_to_edit( $user_id ) {
 	$user = new WP_User( $user_id );
 	$user->user_login   = attribute_escape($user->user_login);
@@ -442,8 +514,11 @@
 	return $user;
 }
 
-// Creates a new user from the "Users" form using $_POST information.
-
+/**
+ * Creates a new user from the "Users" form using $_POST information.
+ *
+ * @return object
+ */
 function add_user() {
 	if ( func_num_args() ) { // The hackiest hack that ever did hack
 		global $current_user, $wp_roles;
@@ -461,6 +536,12 @@
 	}
 }
 
+/**
+ * update user information or create a new user
+ *
+ * @param int $user_id user ID
+ * @return mixed user ID or WP_Error
+ */
 function edit_user( $user_id = 0 ) {
 	global $current_user, $wp_roles, $wpdb;
 	if ( $user_id != 0 ) {
@@ -571,6 +652,12 @@
 }
 
 
+/**
+ * get a link and format it for editing
+ *
+ * @param int $link_id
+ * @return object
+ */
 function get_link_to_edit( $link_id ) {
 	$link = get_link( $link_id );
 
@@ -586,6 +673,11 @@
 	return $link;
 }
 
+/**
+ * default information for link editing
+ *
+ * @return object
+ */
 function get_default_link_to_edit() {
 	if ( isset( $_GET['linkurl'] ) )
 		$link->link_url = attribute_escape( $_GET['linkurl']);
@@ -606,7 +698,13 @@
 	return edit_link();
 }
 
-function edit_link( $link_id = '' ) {
+/**
+ * update a link information or create  new one
+ *
+ * @param int $link_id
+ * @return mixed link ID or Wp_Error
+ */
+function edit_link( $link_id = '' ) { //FIXME this is not very consistent; default for $link_id should be int
 	if (!current_user_can( 'manage_links' ))
 		wp_die( __( 'Cheatin&#8217; uh?' ));
 
@@ -625,6 +723,12 @@
 	}
 }
 
+/**
+ * make a short version of the url
+ *
+ * @param string $url
+ * @return string
+ */
 function url_shorten( $url ) {
 	$short_url = str_replace( 'http://', '', stripslashes( $url ));
 	$short_url = str_replace( 'www.', '', $short_url );
@@ -635,21 +739,46 @@
 	return $short_url;
 }
 
+/**
+ * select helper; output selected status
+ *
+ * @param string $selected value to be selected
+ * @param string $current current value
+ */
 function selected( $selected, $current) {
 	if ( $selected == $current)
 		echo ' selected="selected"';
 }
 
+/**
+ * input helper; output checked status
+ *
+ * @param string $checked value to be checked
+ * @param string $current current value
+ */
 function checked( $checked, $current) {
 	if ( $checked == $current)
 		echo ' checked="checked"';
 }
 
+/**
+ * get a list of categories
+ *
+ * @param int $parent category parent ID
+ * @return array 
+ */
 function return_categories_list( $parent = 0 ) {
 	global $wpdb;
 	return $wpdb->get_col( "SELECT cat_ID FROM $wpdb->categories WHERE category_parent = $parent AND ( link_count = 0 OR category_count != 0 OR ( link_count = 0 AND category_count = 0 ) ) ORDER BY category_count DESC" );
 }
 
+/**
+ * sorting helper
+ *
+ * @param string $cat1
+ * @param string $cat2
+ * @return bool
+ */
 function sort_cats( $cat1, $cat2 ) {
 	if ( $cat1['checked'] || $cat2['checked'] )
 		return ( $cat1['checked'] && !$cat2['checked'] ) ? -1 : 1;
@@ -657,6 +786,13 @@
 		return strcasecmp( $cat1['cat_name'], $cat2['cat_name'] );
 }
 
+/**
+ * get the (sorted) list of categories as a tree
+ *
+ * @param int $default default category
+ * @param int $parent parent category
+ * @return array 
+ */
 function get_nested_categories( $default = 0, $parent = 0 ) {
 	global $post_ID, $link_id, $mode, $wpdb;
 
@@ -703,6 +839,12 @@
 	return $result;
 }
 
+/**
+ * output category list together with checkboxes for selecting
+ *
+ * @filter the_category
+ * @param array $categories category tree
+ */
 function write_nested_categories( $categories ) {
 	foreach ( $categories as $category ) {
 		echo '<li id="category-', $category['cat_ID'], '"><label for="in-category-', $category['cat_ID'], '" class="selectit"><input value="', $category['cat_ID'], '" type="checkbox" name="post_category[]" id="in-category-', $category['cat_ID'], '"', ($category['checked'] ? ' checked="checked"' : "" ), '/> ', wp_specialchars( apply_filters('the_category', $category['cat_name'] )), "</label></li>";
@@ -715,15 +857,33 @@
 	}
 }
 
+/**
+ * get the list of categories from the database and display it
+ *
+ * @param int $default
+ */
 function dropdown_categories( $default = 0 ) {
 	write_nested_categories( get_nested_categories( $default) );
 }
 
+/**
+ * get the list of link categories
+ *
+ * @param array $parent
+ * @return array 
+ */
 function return_link_categories_list( $parent = 0 ) {
 	global $wpdb;
 	return $wpdb->get_col( "SELECT cat_ID FROM $wpdb->categories WHERE category_parent = $parent AND ( category_count = 0  OR link_count != 0 OR ( link_count = 0 AND category_count = 0 ) ) ORDER BY link_count DESC" );
 }
 
+/**
+ * get the link categories as a tree
+ *
+ * @param int $default
+ * @param int $parent
+ * @return array 
+ */
 function get_nested_link_categories( $default = 0, $parent = 0 ) {
 	global $post_ID, $link_id, $mode, $wpdb;
 
@@ -759,12 +919,24 @@
 	return $result;
 }
 
+/**
+ * get the link categories from the database and output them
+ *
+ * @param int $parent
+ */
 function dropdown_link_categories( $default = 0 ) {
 	write_nested_categories( get_nested_link_categories( $default) );
 }
 
-// Dandy new recursive multiple category stuff.
-function cat_rows( $parent = 0, $level = 0, $categories = 0 ) {
+/**
+ * output table rows for the category management page
+ *
+ * @filter cat_rows
+ * @param int $parent
+ * @param int $level
+ * @param array $categories
+ */
+function cat_rows( $parent = 0, $level = 0, $categories = 0 ) { //FIXME categories int or array?
 	if (!$categories )
 		$categories = get_categories( 'hide_empty=0' );
 
@@ -787,6 +959,13 @@
 	}
 }
 
+/**
+ * output a table row with category information and edit/delete links
+ *
+ * @param object $category
+ * @param int $level indent level
+ * @param bool $name_override
+ */
 function _cat_row( $category, $level, $name_override = false ) {
 	global $class;
 
@@ -797,7 +976,7 @@
 		$default_link_cat_id = get_option( 'default_link_category' );
 
 		if ( ($category->cat_ID != $default_cat_id ) && ($category->cat_ID != $default_link_cat_id ) )
-			$edit .= "<td><a href='" . wp_nonce_url( "categories.php?action=delete&amp;cat_ID=$category->cat_ID", 'delete-category_' . $category->cat_ID ) . "' onclick=\"return deleteSomething( 'cat', $category->cat_ID, '" . js_escape(sprintf( __("You are about to delete the category '%s'.\nAll posts that were only assigned to this category will be assigned to the '%s' category.\nAll links that were only assigned to this category will be assigned to the '%s' category.\n'OK' to delete, 'Cancel' to stop." ), $category->cat_name, get_catname( $default_cat_id ), get_catname( $default_link_cat_id ) )) . "' );\" class='delete'>".__( 'Delete' )."</a>";
+			$edit .= "<td><a href='" . wp_nonce_url( "categories.php?action=delete&amp;cat_ID=$category->cat_ID", 'delete-category_' . $category->cat_ID ) . "' onclick=\"return deleteSomething( 'cat', $category->cat_ID, '" . js_escape(sprintf( __("You are about to delete the category '%s'.\nAll of its posts will go into the default category of '%s'\nAll of its bookmarks will go into the default category of '%s'.\n'OK' to delete, 'Cancel' to stop." ), $category->cat_name, get_catname( $default_cat_id ), get_catname( $default_link_cat_id ) )) . "' );\" class='delete'>".__( 'Delete' )."</a>";
 		else
 			$edit .= "<td style='text-align:center'>".__( "Default" );
 	} else
@@ -817,6 +996,14 @@
 		<td>$edit</td>\n\t</tr>\n";
 }
 
+/**
+ * output table rows for the page management page
+ *
+ * @param int $parent
+ * @param int $level
+ * @param array $pages
+ * @param bool $hierarchy
+ */
 function page_rows( $parent = 0, $level = 0, $pages = 0, $hierarchy = true ) {
 	global $wpdb, $class, $post;
 
@@ -853,6 +1040,13 @@
 	}
 }
 
+/**
+ * format user information as a table row
+ *
+ * @param object $user_object 
+ * @param string $style
+ * @return string
+ */
 function user_row( $user_object, $style = '' ) {
 	if ( !(is_object( $user_object) && is_a( $user_object, 'WP_User' ) ) )
 		$user_object = new WP_User( (int) $user_object );
@@ -886,7 +1080,16 @@
 	return $r;
 }
 
-function wp_dropdown_cats( $currentcat = 0, $currentparent = 0, $parent = 0, $level = 0, $categories = 0 ) {
+/**
+ * output category list as select options
+ *
+ * @param int $currentcat
+ * @param int $currentparent
+ * @param int $parent
+ * @param int $level
+ * @param int $categories
+ */
+function wp_dropdown_cats( $currentcat = 0, $currentparent = 0, $parent = 0, $level = 0, $categories = 0 ) {//FIXME $categories array or int?
 	global $wpdb;
 	if (!$categories )
 		$categories = get_categories( 'hide_empty=0' );
@@ -908,7 +1111,12 @@
 	}
 }
 
-// Some postmeta stuff
+/**
+ * get meta information for post
+ *
+ * @param int $postid
+ * @return array 
+ */
 function has_meta( $postid ) {
 	global $wpdb;
 
@@ -920,6 +1128,11 @@
 
 }
 
+/**
+ * output post meta
+ *
+ * @param array $meta
+ */
 function list_meta( $meta ) {
 	global $post_ID;
 	// Exit if no meta
@@ -974,7 +1187,11 @@
 	echo "\n\t</tbody>";
 }
 
-// Get a list of previously defined keys
+/**
+ * Get a list of previously defined keys
+ *
+ * @return array
+ */
 function get_meta_keys() {
 	global $wpdb;
 
@@ -987,6 +1204,11 @@
 	return $keys;
 }
 
+/**
+ * output meta editing form
+ *
+ * @filter postmeta_form_limit
+ */
 function meta_form() {
 	global $wpdb;
 	$limit = (int) apply_filters( 'postmeta_form_limit', 30 );
@@ -1030,6 +1252,12 @@
 
 }
 
+/**
+ * add meta from $_POST
+ *
+ * @param int $post_ID
+ * @return mixed meta ID or false
+ */
 function add_meta( $post_ID ) {
 	global $wpdb;
 	$post_ID = (int) $post_ID;
@@ -1059,6 +1287,12 @@
 	return false;
 } // add_meta
 
+/**
+ * delete meta
+ *
+ * @param int $mid meta ID
+ * @return mixed number of accected rows or false
+ */
 function delete_meta( $mid ) {
 	global $wpdb;
 	$mid = (int) $mid;
@@ -1066,6 +1300,14 @@
 	return $wpdb->query( "DELETE FROM $wpdb->postmeta WHERE meta_id = '$mid'" );
 }
 
+/**
+ * update meta
+ *
+ * @param int $mid
+ * @param string $mkey
+ * @param mixed $mvalue
+ * @return mixed number of affected rows or false
+ */
 function update_meta( $mid, $mkey, $mvalue ) {
 	global $wpdb;
 	$mvalue = maybe_serialize( stripslashes( $mvalue ));
@@ -1074,6 +1316,12 @@
 	return $wpdb->query( "UPDATE $wpdb->postmeta SET meta_key = '$mkey', meta_value = '$mvalue' WHERE meta_id = '$mid'" );
 }
 
+/**
+ * get post meta by ID
+ *
+ * @param int $mid
+ * @return object
+ */
 function get_post_meta_by_id( $mid ) {
 	global $wpdb;
 	$mid = (int) $mid;
@@ -1084,6 +1332,12 @@
 	return $meta;
 }
 
+/**
+ * output timestamp editing form
+ *
+ * @param int $edit
+ * @param int $for_post
+ */
 function touch_time( $edit = 1, $for_post = 1 ) {
 	global $wp_locale, $post, $comment;
 
@@ -1125,11 +1379,16 @@
 
 }
 
-// insert_with_markers: Owen Winkler, fixed by Eric Anderson
-// Inserts an array of strings into a file (.htaccess ), placing it between
-// BEGIN and END markers.  Replaces existing marked info.  Retains surrounding
-// data.  Creates file if none exists.
-// Returns true on write success, false on failure.
+/**
+ * Inserts an array of strings into a file (.htaccess ), placing it between
+ * BEGIN and END markers.  Replaces existing marked info.  Retains surrounding
+ * data.  Creates file if none exists.
+ *
+ * @param string $filename
+ * @param string $marker
+ * @param string $insertion
+ * @return bool
+ */
 function insert_with_markers( $filename, $marker, $insertion ) {
 	if (!file_exists( $filename ) || is_writeable( $filename ) ) {
 		if (!file_exists( $filename ) ) {
@@ -1175,9 +1434,14 @@
 	}
 }
 
-// extract_from_markers: Owen Winkler
-// Returns an array of strings from a file (.htaccess ) from between BEGIN
-// and END markers.
+/**
+ * extracts text between some markers in a file
+ *
+ * @param string $filename
+ * @param string marker
+ * @return array array of strings from a file (.htaccess ) from between BEGIN
+ * and END markers.
+ */
 function extract_from_markers( $filename, $marker ) {
 	$result = array ();
 
@@ -1201,6 +1465,11 @@
 	return $result;
 }
 
+/**
+ * find out if we have mod_rewrite
+ *
+ * @return bool
+ */
 function got_mod_rewrite() {
 	global $is_apache;
 
@@ -1216,6 +1485,11 @@
 	return true;
 }
 
+/**
+ * save mod_rewrite rules to .htaccess
+ *
+ * @return bool
+ */
 function save_mod_rewrite_rules() {
 	global $is_apache, $wp_rewrite;
 	$home_path = get_home_path();
@@ -1233,6 +1507,11 @@
 	return insert_with_markers( $home_path.'.htaccess', 'WordPress', $rules );
 }
 
+/**
+ * get the list of broken themes
+ *
+ * @return array 
+ */
 function get_broken_themes() {
 	global $wp_broken_themes;
 
@@ -1240,6 +1519,11 @@
 	return $wp_broken_themes;
 }
 
+/**
+ * build the page template list
+ *
+ * @return array 
+ */
 function get_page_templates() {
 	$themes = get_themes();
 	$theme = get_current_theme();
@@ -1264,6 +1548,11 @@
 	return $page_templates;
 }
 
+/**
+ * output the template dropdown for the current page
+ *
+ * @param string default the currently selected template
+ */
 function page_template_dropdown( $default = '' ) {
 	$templates = get_page_templates();
 	foreach (array_keys( $templates ) as $template )
@@ -1275,6 +1564,13 @@
 	endforeach;
 }
 
+/**
+ * get the page parent dropdown
+ *
+ * @param int $default the ID of the selected item
+ * @param int $parent the ID of the parent
+ * @param int $level the current nesting level
+ */
 function parent_dropdown( $default = 0, $parent = 0, $level = 0 ) {
 	global $wpdb, $post_ID;
 	$items = $wpdb->get_results( "SELECT ID, post_parent, post_title FROM $wpdb->posts WHERE post_parent = $parent AND post_type = 'page' ORDER BY menu_order" );
@@ -1301,6 +1597,11 @@
 	}
 }
 
+/**
+ * check if the user can access the current admin page
+ *
+ * @return bool
+ */
 function user_can_access_admin_page() {
 	global $pagenow;
 	global $menu;
@@ -1361,6 +1662,11 @@
 	return true;
 }
 
+/**
+ * get title of the current admin page
+ *
+ * @return string
+ */
 function get_admin_page_title() {
 	global $title;
 	global $menu;
@@ -1419,6 +1725,11 @@
 	return $title;
 }
 
+/**
+ * get the parent for the current admin page
+ *
+ * @return string
+ */
 function get_admin_page_parent() {
 	global $parent_file;
 	global $menu;
@@ -1479,6 +1790,16 @@
 	return '';
 }
 
+/**
+ * add a toplevel menu item
+ *
+ * @param string $page_title page title
+ * @param string $menu_title menu item label
+ * @param int $access_level minimum user level
+ * @param string $file filename (relative to wp-content/plugins)
+ * @param callback $function function that generates the page
+ * @return string th page hook name
+ */
 function add_menu_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
 	global $menu, $admin_page_hooks;
 
@@ -1495,6 +1816,17 @@
 	return $hookname;
 }
 
+/**
+ * add a subpage to the menu
+ * 
+ * @param string $parent parent page
+ * @param string $page_title subpage title
+ * @param string $menu_title menu item label
+ * @param int $access_level minimum user level
+ * @param string $file filename (relative to wp-content/plugins)
+ * @param callback $function function that generates the subpage
+ * @return string the page hook name
+ */
 function add_submenu_page( $parent, $page_title, $menu_title, $access_level, $file, $function = '' ) {
 	global $submenu;
 	global $menu;
@@ -1533,18 +1865,58 @@
 	return $hookname;
 }
 
+/**
+ * add an options subpage
+ *
+ * @param string $page_title @see add_submenu_page()
+ * @param string $menu_title @see add_submenu_page()
+ * @param int $access_level @see add_submenu_page()
+ * @param string $file @see add_submenu_page()
+ * @param callback $function @see add_submenu_page()
+ * @return string @see add_submenu_page()
+ */
 function add_options_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
 	return add_submenu_page( 'options-general.php', $page_title, $menu_title, $access_level, $file, $function );
 }
 
+/**
+ * add a management subpage
+ *
+ * @param string $page_title @see add_submenu_page()
+ * @param string $menu_title @see add_submenu_page()
+ * @param int $access_level @see add_submenu_page()
+ * @param string $file @see add_submenu_page()
+ * @param callback $function @see add_submenu_page()
+ * @return string @see add_submenu_page()
+ */
 function add_management_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
 	return add_submenu_page( 'edit.php', $page_title, $menu_title, $access_level, $file, $function );
 }
 
+/**
+ * add a theme subpage
+ *
+ * @param string $page_title @see add_submenu_page()
+ * @param string $menu_title @see add_submenu_page()
+ * @param int $access_level @see add_submenu_page()
+ * @param string $file @see add_submenu_page()
+ * @param callback $function @see add_submenu_page()
+ * @return string @see add_submenu_page()
+ */
 function add_theme_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
 	return add_submenu_page( 'themes.php', $page_title, $menu_title, $access_level, $file, $function );
 }
 
+/**
+ * add a users subpage
+ *
+ * @param string $page_title @see add_submenu_page()
+ * @param string $menu_title @see add_submenu_page()
+ * @param int $access_level @see add_submenu_page()
+ * @param string $file @see add_submenu_page()
+ * @param callback $function @see add_submenu_page()
+ * @return string @see add_submenu_page()
+ */
 function add_users_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
 	if ( current_user_can('edit_users') )
 		$parent = 'users.php';
@@ -1553,6 +1925,13 @@
 	return add_submenu_page( $parent, $page_title, $menu_title, $access_level, $file, $function );
 }
 
+/**
+ * validate a file
+ *
+ * @param string $file
+ * @param array $allowed_files
+ * @return int
+ */
 function validate_file( $file, $allowed_files = '' ) {
 	if ( false !== strpos( $file, './' ))
 		return 1;
@@ -1566,6 +1945,12 @@
 	return 0;
 }
 
+/**
+ * validate a file before editing and abort with a friendly error message
+ *
+ * @param string $file
+ * @param array $allowed_files
+ */
 function validate_file_to_edit( $file, $allowed_files = '' ) {
 	$file = stripslashes( $file );
 
@@ -1586,6 +1971,11 @@
 	}
 }
 
+/**
+ * get the home path
+ *
+ * @return string
+ */
 function get_home_path() {
 	$home = get_option( 'home' );
 	if ( $home != '' && $home != get_option( 'siteurl' ) ) {
@@ -1600,6 +1990,11 @@
 	return $home_path;
 }
 
+/**
+ * resolve the file path
+ *
+ * @return string
+ */
 function get_real_file_to_edit( $file ) {
 	if ('index.php' == $file || '.htaccess' == $file ) {
 		$real_file = get_home_path().$file;
@@ -1614,6 +2009,12 @@
 	// Deprecated files
 	'wp-layout.css' => __( 'Stylesheet' ), 'wp-comments.php' => __( 'Comments Template' ), 'wp-comments-popup.php' => __( 'Popup Comments Template' ));
 
+/**
+ * get description for a template file
+ *
+ * @param string $file
+ * @return string
+ */
 function get_file_description( $file ) {
 	global $wp_file_descriptions;
 
@@ -1629,6 +2030,11 @@
 	return basename( $file );
 }
 
+/**
+ * update the list of recently edited files
+ *
+ * @param string $file
+ */
 function update_recently_edited( $file ) {
 	$oldfiles = (array ) get_option( 'recently_edited' );
 	if ( $oldfiles ) {
@@ -1644,6 +2050,12 @@
 	update_option( 'recently_edited', $oldfiles );
 }
 
+/**
+ * read the plugin data
+ *
+ * @param string $plugin_file
+ * @return array 
+ */
 function get_plugin_data( $plugin_file ) {
 	$plugin_data = implode( '', file( $plugin_file ));
 	preg_match( "|Plugin Name:(.*)|i", $plugin_data, $plugin_name );
@@ -1674,6 +2086,11 @@
 	return array ('Name' => $name, 'Title' => $plugin, 'Description' => $description, 'Author' => $author, 'Version' => $version, 'Template' => $template[1] );
 }
 
+/**
+ * build the list of plugins in the wp-content/plugins directory
+ *
+ * @return array 
+ */
 function get_plugins() {
 	global $wp_plugins;
 
@@ -1727,6 +2144,13 @@
 	return $wp_plugins;
 }
 
+/**
+ * compose a plugin page hook name from the nme of the plugin page and the name of its parent page
+ *
+ * @param string $plugin_page plugin page name
+ * @param string $parent_page parent page name
+ * @return string
+ */
 function get_plugin_page_hookname( $plugin_page, $parent_page ) {
 	global $admin_page_hooks;
 
@@ -1750,6 +2174,13 @@
 	return $page_type.'_page_'.$plugin_name;
 }
 
+/**
+ * the hook name for a plugin page, if it is defined
+ *
+ * @param string $plugin_page @see get_plugin_page_hookname
+ * @param string $parent_page @see get_plugin_page_hookname
+ * @return string
+ */
 function get_plugin_page_hook( $plugin_page, $parent_page ) {
 	global $wp_filter;
 
@@ -1786,6 +2217,11 @@
 	return $wp_importers;
 }
 
+/**
+ * get current theme info
+ *
+ * @return object
+ */
 function current_theme_info() {
 	$themes = get_themes();
 	$current_theme = get_current_theme();
@@ -1803,12 +2239,15 @@
 	return $ct;
 }
 
-
-// array wp_handle_upload ( array &file [, array overrides] )
-// file: reference to a single element of $_FILES. Call the function once for each uploaded file.
-// overrides: an associative array of names=>values to override default variables with extract( $overrides, EXTR_OVERWRITE ).
-// On success, returns an associative array of file attributes.
-// On failure, returns $overrides['upload_error_handler'](&$file, $message ) or array( 'error'=>$message ).
+/**
+ * handle an uploaded file
+ *
+ * @filter wp_handle_upload
+ * @param array &$file file info; reference to a single element if $_FILES
+ * @param array $overrides associative array of names=>values to override default variables with extract($overrides, EXTR_OVERWRITE)
+ * @return mixed associative array of file attributes on success, 
+ * $overrides['upload_error_handler'](&$file, $message ) or array( 'error'=>$message ) on failure
+ */
 function wp_handle_upload( &$file, $overrides = false ) {
 	// The default error handler.
 	if (! function_exists( 'wp_handle_upload_error' ) ) {
@@ -1912,6 +2351,15 @@
 	return $return;
 }
 
+/**
+ * compute dimensions for display in the upload list
+ *
+ * @param int $width image width
+ * @param int $height image height
+ * @param int $wmax maximum width of the resized image
+ * @param int $hmax maximum height of the resized image
+ * @return array 
+ */
 function wp_shrink_dimensions( $width, $height, $wmax = 128, $hmax = 96 ) {
 	if ( $height <= $hmax && $width <= $wmax )
 		return array( $width, $height);
@@ -1921,10 +2369,20 @@
 		return array( (int) ($width / $height * $hmax ), $hmax );
 }
 
+/**
+ * delete an attachment
+ *
+ * @param int $id attachment ID
+ */
 function wp_import_cleanup( $id ) {
 	wp_delete_attachment( $id );
 }
 
+/**
+ * outputs the file upload form for importing
+ *
+ * @param string $action form action
+ */
 function wp_import_upload_form( $action ) {
 	$size = strtolower( ini_get( 'upload_max_filesize' ) );
 	$bytes = 0;
@@ -1949,6 +2407,11 @@
 <?php
 }
 
+/**
+ * handles an import file upload
+ *
+ * @return array array containing attachment data
+ */
 function wp_import_handle_upload() {
 	$overrides = array( 'test_form' => false, 'test_type' => false );
 	$file = wp_handle_upload( $_FILES['import'], $overrides );
@@ -1974,6 +2437,11 @@
 	return array( 'file' => $file, 'id' => $id );
 }
 
+/**
+ * output the attachment links form 
+ *
+ * @param int $id attachment ID 
+ */
 function the_attachment_links( $id = false ) {
 	$id = (int) $id;
 	$post = & get_post( $id );
@@ -2017,6 +2485,11 @@
 <?php
 }
 
+/**
+ * compute and return dimensions for displaying a "thumbnail"; apparently not used
+ *
+ * @return array
+ */
 function get_udims( $width, $height) {
 	if ( $height <= 96 && $width <= 128 )
 		return array( $width, $height);
@@ -2026,6 +2499,11 @@
 		return array( (int) ($width / $height * 96 ), 96 );
 }
 
+/**
+ * resets the variables passed
+ *
+ * @param array $vars array of variable names
+ */
 function wp_reset_vars( $vars ) {
 	for ( $i=0; $i<count( $vars ); $i += 1 ) {
 		$var = $vars[$i];
@@ -2044,7 +2522,9 @@
 	}
 }
 
-
+/**
+ * output a hidden input field with the current post slug
+ */
 function wp_remember_old_slug() {
 	global $post;
 	$name = attribute_escape($post->post_name); // just in case
@@ -2053,7 +2533,12 @@
 }
 
 
-// If siteurl or home changed, reset cookies and flush rewrite rules.
+/**
+ * If siteurl or home changed, reset cookies and flush rewrite rules.
+ *
+ * @param string $old_value
+ * @param string $value
+ */
 function update_home_siteurl( $old_value, $value ) {
 	global $wp_rewrite, $user_login, $user_pass_md5;
 
@@ -2071,6 +2556,20 @@
 add_action( 'update_option_home', 'update_home_siteurl', 10, 2 );
 add_action( 'update_option_siteurl', 'update_home_siteurl', 10, 2 );
 
+/**
+ * crop an image
+ *
+ * @param mixed $src_file filename or attachment ID
+ * @param int $src_x starting x
+ * @param int $src_y starting y
+ * @param int $src_w crop width
+ * @param int $src_h crop height
+ * @param int $dst_w output width
+ * @param int $dst_h output width
+ * @param bool $src_abs whether $src_w and $src_h are absolute coordinates instead of width and height
+ * @param string $dst_file destination filename
+ * @return mixed the path to the cropped file or false on error
+ */
 function wp_crop_image( $src_file, $src_x, $src_y, $src_w, $src_h, $dst_w, $dst_h, $src_abs = false, $dst_file = false ) {
 	if ( ctype_digit( $src_file ) ) // Handle int as attachment ID
 		$src_file = get_attached_file( $src_file );
@@ -2103,6 +2602,12 @@
 		return false;
 }
 
+/**
+ * load an image
+ *
+ * @param mixed $file file name or attachment ID
+ * @return int resource
+ */
 function wp_load_image( $file ) {
 	if ( ctype_digit( $file ) )
 		$file = get_attached_file( $file );
@@ -2123,6 +2628,16 @@
 	return $image;
 }
 
+/**
+ * retrieve metadata for an image attachment
+ *
+ * @filter wp_generate_attachment_metadata
+ * @filter wp_thumbnail_creation_size_limit
+ * @filter wp_thumbnail_max_side_length
+ * @param int $attachment_id attachment ID
+ * @param string $file file path
+ * @return array
+ */
 function wp_generate_attachment_metadata( $attachment_id, $file ) {
 	$attachment = get_post( $attachment_id );
 
@@ -2148,6 +2663,16 @@
 	return apply_filters( 'wp_generate_attachment_metadata', $metadata );
 }
 
+/**
+ * create a thumbnail
+ *
+ * @filter thumbnail_filename 
+ * @filter wp_create_thumbnail
+ * @param string $file file name
+ * @param int $max_side length of the longest side
+ * @param string $effect apparently unused
+ * @return string thumbnail path
+ */
 function wp_create_thumbnail( $file, $max_side, $effect = '' ) {
 
 		// 1 = GIF, 2 = JPEG, 3 = PNG