Ticket #3970: admin-functions-phpdoc.diff

wp-admin/admin-functions.php

@@ -1 +1 @@
 <?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 +22 @@
                 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 +149 @@
         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 +163 @@
         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 +210 @@
         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 +333 @@
         return $post_ID;
 }
 
+/**
+ * update a comment using data from $_POST
+ *
+ * @return int number of affected rows
+ */
 function edit_comment() {
         global $user_ID;
 
@@ -332 +371 @@
         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 +401 @@
         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 +448 @@
         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 +467 @@
         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 +491 @@
 }
 
 
+/**
+ * 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 +514 @@
         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 +536 @@
         }
 }
 
+/**
+ * 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 +652 @@
 }
 
 
+/**
+ * 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 +673 @@
         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 +698 @@
         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 +723 @@
         }
 }
 
+/**
+ * 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 +739 @@
         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 +786 @@
                 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 +839 @@
         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 +857 @@
         }
 }
 
+/**
+ * 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 +919 @@
         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 +959 @@
         }
 }
 
+/**
+ * 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 +976 @@
                 $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 +996 @@
                 <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 +1040 @@
         }
 }
 
+/**
+ * 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 +1080 @@
         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 +1111 @@
         }
 }
 
-// Some postmeta stuff
+/**
+ * get meta information for post
+ *
+ * @param int $postid
+ * @return array 
+ */
 function has_meta( $postid ) {
         global $wpdb;
 
@@ -920 +1128 @@
 
 }
 
+/**
+ * output post meta
+ *
+ * @param array $meta
+ */
 function list_meta( $meta ) {
         global $post_ID;
         // Exit if no meta
@@ -974 +1187 @@
         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 +1204 @@
         return $keys;
 }
 
+/**
+ * output meta editing form
+ *
+ * @filter postmeta_form_limit
+ */
 function meta_form() {
         global $wpdb;
         $limit = (int) apply_filters( 'postmeta_form_limit', 30 );
@@ -1030 +1252 @@
 
 }
 
+/**
+ * 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 +1287 @@
         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 +1300 @@
         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 +1316 @@
         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 +1332 @@
         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 +1379 @@
 
 }
 
-// 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 +1434 @@
         }
 }
 
-// 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 +1465 @@
         return $result;
 }
 
+/**
+ * find out if we have mod_rewrite
+ *
+ * @return bool
+ */
 function got_mod_rewrite() {
         global $is_apache;
 
@@ -1216 +1485 @@
         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 +1507 @@
         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 +1519 @@
         return $wp_broken_themes;
 }
 
+/**
+ * build the page template list
+ *
+ * @return array 
+ */
 function get_page_templates() {
         $themes = get_themes();
         $theme = get_current_theme();
@@ -1264 +1548 @@
         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 +1564 @@
         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 +1597 @@
         }
 }
 
+/**
+ * check if the user can access the current admin page
+ *
+ * @return bool
+ */
 function user_can_access_admin_page() {
         global $pagenow;
         global $menu;
@@ -1361 +1662 @@
         return true;
 }
 
+/**
+ * get title of the current admin page
+ *
+ * @return string
+ */
 function get_admin_page_title() {
         global $title;
         global $menu;
@@ -1419 +1725 @@
         return $title;
 }
 
+/**
+ * get the parent for the current admin page
+ *
+ * @return string
+ */
 function get_admin_page_parent() {
         global $parent_file;
         global $menu;
@@ -1479 +1790 @@
         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 +1816 @@
         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 +1865 @@
         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 +1925 @@
         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 +1945 @@
         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 +1971 @@
         }
 }
 
+/**
+ * get the home path
+ *
+ * @return string
+ */
 function get_home_path() {
         $home = get_option( 'home' );
         if ( $home != '' && $home != get_option( 'siteurl' ) ) {
@@ -1600 +1990 @@
         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 +2009 @@
         // 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 +2030 @@
         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 +2050 @@
         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 +2086 @@
         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 +2144 @@
         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 +2174 @@
         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 +2217 @@
         return $wp_importers;
 }
 
+/**
+ * get current theme info
+ *
+ * @return object
+ */
 function current_theme_info() {
         $themes = get_themes();
         $current_theme = get_current_theme();
@@ -1803 +2239 @@
         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 +2351 @@
         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 +2369 @@
                 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 +2407 @@
 <?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 +2437 @@
         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 +2485 @@
 <?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 +2499 @@
                 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 +2522 @@
         }
 }
 
-
+/**
+ * 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 +2533 @@
 }
 
 
-// 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 +2556 @@
 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 +2602 @@
                 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 +2628 @@
         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 +2663 @@
         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