phpdoc for wp-admin. Props jacobsantos. see #7527

git-svn-id: http://svn.automattic.com/wordpress/trunk@9119 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/edit-form-advanced.php

@@ -55,6 +55,14 @@ if ( 0 == $post_ID ) {
 }
 
 // All meta boxes should be defined and added before the first do_meta_boxes() call (or potentially during the do_meta_boxes action).
+
+/**
+ * Display post submit form fields.
+ *
+ * @since 2.7.0
+ *
+ * @param object $post
+ */
 function post_submit_meta_box($post) {
 	global $action;
 
@@ -186,6 +194,13 @@ if ( !in_array( $post->post_status, array('publish', 'future') ) || 0 == $post->
 }
 add_meta_box('submitdiv', __('Publish'), 'post_submit_meta_box', 'post', 'side', 'core');
 
+/**
+ * Display post tags form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function post_tags_meta_box($post) {
 ?>
 <p id="jaxtag"><label class="hidden" for="newtag"><?php _e('Tags'); ?></label><input type="text" name="tags_input" class="tags-input" id="tags-input" size="40" tabindex="3" value="<?php echo get_tags_to_edit( $post->ID ); ?>" /></p>
@@ -195,6 +210,14 @@ function post_tags_meta_box($post) {
 }
 add_meta_box('tagsdiv', __('Tags'), 'post_tags_meta_box', 'post', 'side', 'core');
 
+/**
+ * Display add post media and current post media form fields and images.
+ *
+ * @todo Complete.
+ * @since 2.7.0
+ *
+ * @param object $post
+ */
 function post_media_meta_box($post) {
 	echo "<p><small><em>This feature isn't fully functional in this prototype.</em></small></p>";
 
@@ -231,6 +254,13 @@ function post_media_meta_box($post) {
 }
 add_meta_box( 'mediadiv', __('Media' ), 'post_media_meta_box', 'post', 'side', 'core' );
 
+/**
+ * Display post categories form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function post_categories_meta_box($post) {
 ?>
 <ul id="category-tabs">
@@ -265,6 +295,13 @@ function post_categories_meta_box($post) {
 }
 add_meta_box('categorydiv', __('Categories'), 'post_categories_meta_box', 'post', 'side', 'core');
 
+/**
+ * Display post excerpt form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function post_excerpt_meta_box($post) {
 ?>
 <label class="hidden" for="excerpt"><?php _e('Excerpt') ?></label><textarea rows="1" cols="40" name="excerpt" tabindex="6" id="excerpt"><?php echo $post->post_excerpt ?></textarea>
@@ -273,6 +310,13 @@ function post_excerpt_meta_box($post) {
 }
 add_meta_box('postexcerpt', __('Excerpt'), 'post_excerpt_meta_box', 'post', 'normal', 'core');
 
+/**
+ * Display trackback links form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function post_trackback_meta_box($post) {
 	$form_trackback = '<input type="text" name="trackback_url" id="trackback_url" tabindex="7" value="'. attribute_escape( str_replace("\n", ' ', $post->to_ping) ) .'" />';
 	if ('' != $post->pinged) {
@@ -296,6 +340,13 @@ if ( ! empty($pings) )
 }
 add_meta_box('trackbacksdiv', __('Trackbacks and Pings'), 'post_trackback_meta_box', 'post', 'normal', 'core');
 
+/**
+ * Display custom fields for the post form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function post_custom_meta_box($post) {
 ?>
 <div id="postcustomstuff">
@@ -318,6 +369,13 @@ add_meta_box('postcustom', __('Custom Fields'), 'post_custom_meta_box', 'post',
 
 do_action('dbx_post_advanced');
 
+/**
+ * Display comment status for post form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function post_comment_status_meta_box($post) {
 	global $wpdb, $post_ID;
 ?>
@@ -357,6 +415,13 @@ function post_comment_status_meta_box($post) {
 }
 add_meta_box('commentstatusdiv', __('Comments on this Post'), 'post_comment_status_meta_box', 'post', 'normal', 'core');
 
+/**
+ * Display post password form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function post_password_meta_box($post) {
 ?>
 <p>
@@ -369,6 +434,13 @@ function post_password_meta_box($post) {
 }
 add_meta_box('passworddiv', __('Privacy Options'), 'post_password_meta_box', 'post', 'normal', 'core');
 
+/**
+ * Display post slug form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function post_slug_meta_box($post) {
 ?>
 <label class="hidden" for="post_name"><?php _e('Post Slug') ?></label><input name="post_name" type="text" size="13" id="post_name" value="<?php echo attribute_escape( $post->post_name ); ?>" />
@@ -381,6 +453,13 @@ $authors = get_editable_user_ids( $current_user->id ); // TODO: ROLE SYSTEM
 if ( $post->post_author && !in_array($post->post_author, $authors) )
 	$authors[] = $post->post_author;
 if ( $authors && count( $authors ) > 1 ) :
+/**
+ * Display form field with list of authors.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function post_author_meta_box($post) {
 	global $current_user, $user_ID;
 	$authors = get_editable_user_ids( $current_user->id ); // TODO: ROLE SYSTEM
@@ -394,6 +473,13 @@ add_meta_box('authordiv', __('Post Author'), 'post_author_meta_box', 'post', 'no
 endif;
 
 if ( 0 < $post_ID && wp_get_post_revisions( $post_ID ) ) :
+/**
+ * Display list of post revisions.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function post_revisions_meta_box($post) {
 	wp_list_post_revisions();
 }

wp-admin/edit-form-comment.php

@@ -25,7 +25,16 @@ $form_extra = "' />\n<input type='hidden' name='comment_ID' value='" . $comment-
 <?php
 // All meta boxes should be defined and added before the first do_meta_boxes() call (or potentially during the do_meta_boxes action).
 
-function comment_submit_meta_box($comment) { // not used, but keeping for a bit longer in case it's needed
+/**
+ * Display comment edit meta box.
+ *
+ * Not used, but keeping for a bit longer in case it's needed.
+ *
+ * @since 2.7.0
+ *
+ * @param object $comment Comment data.
+ */
+function comment_submit_meta_box($comment) {
 ?>
 <div class="submitbox" id="submitcomment">
 <div class="inside-submitbox">

wp-admin/edit-link-form.php

@@ -18,6 +18,15 @@ if ( ! empty($link_id) ) {
 	$nonce_action = 'add-bookmark';
 }
 
+/**
+ * Display checked checkboxes attribute for xfn microformat options.
+ *
+ * @since 1.0.1
+ *
+ * @param string $class
+ * @param string $value
+ * @param mixed $deprecated Not used.
+ */
 function xfn_check($class, $value = '', $deprecated = '') {
 	global $link;
 
@@ -37,7 +46,16 @@ function xfn_check($class, $value = '', $deprecated = '') {
 }
 ?>
 
-<?php function link_submit_meta_box($link) { ?>
+<?php
+/**
+ * Display link create form fields.
+ *
+ * @since 2.7.0
+ *
+ * @param object $link
+ */
+function link_submit_meta_box($link) {
+?>
 <div class="submitbox" id="submitlink">
 
 <div class="inside-submitbox">
@@ -63,6 +81,13 @@ if ( 'edit' == $_GET['action'] && current_user_can('manage_links') )
 }
 add_meta_box('linksubmitdiv', __('Save'), 'link_submit_meta_box', 'link', 'side', 'core');
 
+/**
+ * Display link categories form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $link
+ */
 function link_categories_meta_box($link) { ?>
 <div id="category-adder" class="wp-hidden-children">
 	<h4><a id="category-add-toggle" href="#category-add"><?php _e( '+ Add New Category' ); ?></a></h4>
@@ -100,6 +125,13 @@ function link_categories_meta_box($link) { ?>
 }
 add_meta_box('linkcategorydiv', __('Categories'), 'link_categories_meta_box', 'link', 'normal', 'core');
 
+/**
+ * Display form fields for changing link target.
+ *
+ * @since 2.6.0
+ *
+ * @param object $link
+ */
 function link_target_meta_box($link) { ?>
 <fieldset><legend class="hidden"><?php _e('Target') ?></legend>
 <label for="link_target_blank" class="selectit">
@@ -117,6 +149,13 @@ function link_target_meta_box($link) { ?>
 }
 add_meta_box('linktargetdiv', __('Target'), 'link_target_meta_box', 'link', 'normal', 'core');
 
+/**
+ * Display xfn form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $link
+ */
 function link_xfn_meta_box($link) {
 ?>
 <table class="editform" style="width: 100%;" cellspacing="2" cellpadding="5">
@@ -230,6 +269,13 @@ function link_xfn_meta_box($link) {
 }
 add_meta_box('linkxfndiv', __('Link Relationship (XFN)'), 'link_xfn_meta_box', 'link', 'normal', 'core');
 
+/**
+ * Display advanced link options form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $link
+ */
 function link_advanced_meta_box($link) {
 ?>
 <table class="form-table" style="width: 100%;" cellspacing="2" cellpadding="5">

wp-admin/edit-page-form.php

@@ -7,7 +7,7 @@
  */
 
 /**
- * Post ID global
+ * Post ID global.
  * @name $post_ID
  * @var int
  */
@@ -47,6 +47,13 @@ $user_ID = (int) $user_ID;
 ?>
 
 <?php
+/**
+ * Display submit form fields.
+ *
+ * @since 2.7.0
+ *
+ * @param object $post
+ */
 function page_submit_meta_box($post) {
 	global $action;
 
@@ -172,6 +179,13 @@ if ( !in_array( $post->post_status, array('publish', 'future') ) || 0 == $post->
 }
 add_meta_box('pagesubmitdiv', __('Publish'), 'page_submit_meta_box', 'page', 'side', 'core');
 
+/**
+ * Display custom field for page form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function page_custom_meta_box($post){
 ?>
 <div id="postcustomstuff">
@@ -192,6 +206,13 @@ list_meta($metadata);
 }
 add_meta_box('pagecustomdiv', __('Custom Fields'), 'page_custom_meta_box', 'page', 'normal', 'core');
 
+/**
+ * Display comments status form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function page_comments_status_meta_box($post){
 ?>
 <input name="advanced_view" type="hidden" value="1" />
@@ -204,6 +225,13 @@ function page_comments_status_meta_box($post){
 }
 add_meta_box('pagecommentstatusdiv', __('Comments &amp; Pings'), 'page_comments_status_meta_box', 'page', 'normal', 'core');
 
+/**
+ * Display page password form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function page_password_meta_box($post){
 ?>
 <p><label for="post_status_private" class="selectit"><input id="post_status_private" name="post_status" type="checkbox" value="private" <?php checked($post->post_status, 'private'); ?> tabindex='4' /> <?php _e('Keep this page private') ?></label></p>
@@ -214,6 +242,13 @@ function page_password_meta_box($post){
 }
 add_meta_box('pagepassworddiv', __('Privacy Options'), 'page_password_meta_box', 'page', 'normal', 'core');
 
+/**
+ * Display page slug form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function page_slug_meta_box($post){
 ?>
 <label class="hidden" for="post_name"><?php _e('Page Slug') ?></label><input name="post_name" type="text" size="13" id="post_name" value="<?php echo attribute_escape( $post->post_name ); ?>" />
@@ -221,6 +256,13 @@ function page_slug_meta_box($post){
 }
 add_meta_box('pageslugdiv', __('Page Slug'), 'page_slug_meta_box', 'page', 'normal', 'core');
 
+/**
+ * Display page parent form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function page_parent_meta_box($post){
 ?>
 <label class="hidden" for="parent_id"><?php _e('Page Parent') ?></label>
@@ -231,6 +273,13 @@ function page_parent_meta_box($post){
 add_meta_box('pageparentdiv', __('Page Parent'), 'page_parent_meta_box', 'page', 'normal', 'core');
 
 if ( 0 != count( get_page_templates() ) ) {
+	/**
+	 * Display page template form fields.
+	 *
+	 * @since 2.6.0
+	 *
+	 * @param object $post
+	 */
 	function page_template_meta_box($post){
 ?>
 <label class="hidden" for="page_template"><?php _e('Page Template') ?></label><select name="page_template" id="page_template">
@@ -243,6 +292,13 @@ if ( 0 != count( get_page_templates() ) ) {
 	add_meta_box('pagetemplatediv', __('Page Template'), 'page_template_meta_box', 'page', 'normal', 'core');
 }
 
+/**
+ * Display page order form fields.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function page_order_meta_box($post){
 ?>
 <p><label class="hidden" for="menu_order"><?php _e('Page Order') ?></label><input name="menu_order" type="text" size="4" id="menu_order" value="<?php echo $post->menu_order ?>" /></p>
@@ -256,6 +312,13 @@ $authors = get_editable_user_ids( $current_user->id ); // TODO: ROLE SYSTEM
 if ( $post->post_author && !in_array($post->post_author, $authors) )
 	$authors[] = $post->post_author;
 if ( $authors && count( $authors ) > 1 ) {
+	/**
+	 * Display page author form fields, when more than one author exists.
+	 *
+	 * @since 2.6.0
+	 *
+	 * @param object $post
+	 */
 	function page_author_meta_box($post){
 		global $current_user, $user_ID;
 		$authors = get_editable_user_ids( $current_user->id ); // TODO: ROLE SYSTEM
@@ -270,6 +333,13 @@ if ( $authors && count( $authors ) > 1 ) {
 
 
 if ( 0 < $post_ID && wp_get_post_revisions( $post_ID ) ) :
+/**
+ * Display list of page revisions.
+ *
+ * @since 2.6.0
+ *
+ * @param object $post
+ */
 function page_revisions_meta_box($post) {
 	wp_list_post_revisions();
 }

wp-admin/includes/comment.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * WordPress Comment Administration API
+ * WordPress Comment Administration API.
  *
  * @package WordPress
  * @subpackage Administration

wp-admin/includes/image.php

@@ -13,7 +13,7 @@
  * does not have the functionality to save in a file of the same format, the
  * thumbnail will be created as a jpeg.
  *
- * @since unknown
+ * @since 1.2.0
  *
  * @param mixed $file Filename of the original image, Or attachment id.
  * @param int $max_side Maximum length of a single side for the thumbnail.
@@ -27,11 +27,9 @@ function wp_create_thumbnail( $file, $max_side, $deprecated = '' ) {
 /**
  * Crop an Image to a given size.
  *
- * @internal Missing Long Description
+ * @since 2.1.0
  *
- * @since unknown
+ * @param string|int $src_file The source file or Attachment ID.
- *
- * @param string|int $src_file The source file or Attachment ID
  * @param int $src_x The start x position to crop from.
  * @param int $src_y The start y position to crop from.
  * @param int $src_w The width to crop.
@@ -77,15 +75,13 @@ function wp_crop_image( $src_file, $src_x, $src_y, $src_w, $src_h, $dst_w, $dst_
 }
 
 /**
- * Generate post Image attachment Metadata.
+ * Generate post image attachment meta data.
  *
- * @internal Missing Long Description
+ * @since 2.1.0
  *
- * @since unknown
+ * @param int $attachment_id Attachment Id to process.
- *
+ * @param string $file Filepath of the Attached image.
- * @param int $attachment_id Attachment Id to process
+ * @return mixed Metadata for attachment.
- * @param string $file Filepath of the Attached image
- * @return mixed Metadata for attachment
  */
 function wp_generate_attachment_metadata( $attachment_id, $file ) {
 	$attachment = get_post( $attachment_id );
@@ -129,11 +125,9 @@ function wp_generate_attachment_metadata( $attachment_id, $file ) {
 }
 
 /**
- * Load an image which PHP Supports.
+ * Load an image from a string, if PHP supports it.
  *
- * @internal Missing Long Description
+ * @since 2.1.0
- *
- * @since unknown
  *
  * @param string $file Filename of the image to load.
  * @return resource The resulting image resource on success, Error string on failure.
@@ -159,15 +153,14 @@ function wp_load_image( $file ) {
 }
 
 /**
- * Calculated the new dimentions for downsampled images.
+ * Calculated the new dimentions for a downsampled image.
  *
- * @since unknown
+ * @since 2.0.0
  * @see wp_shrink_dimensions()
  *
  * @param int $width Current width of the image
  * @param int $height Current height of the image
  * @return mixed Array(height,width) of shrunk dimensions.
- *
  */
 function get_udims( $width, $height) {
 	return wp_shrink_dimensions( $width, $height );
@@ -176,7 +169,7 @@ function get_udims( $width, $height) {
 /**
  * Calculates the new dimentions for a downsampled image.
  *
- * @since unknown
+ * @since 2.0.0
  * @see wp_constrain_dimensions()
  *
  * @param int $width Current width of the image
@@ -184,7 +177,6 @@ function get_udims( $width, $height) {
  * @param int $wmax Maximum wanted width
  * @param int $hmax Maximum wanted height
  * @return mixed Array(height,width) of shrunk dimensions.
- *
  */
 function wp_shrink_dimensions( $width, $height, $wmax = 128, $hmax = 96 ) {
 	return wp_constrain_dimensions( $width, $height, $wmax, $hmax );
@@ -193,7 +185,7 @@ function wp_shrink_dimensions( $width, $height, $wmax = 128, $hmax = 96 ) {
 /**
  * Convert a fraction string to a decimal.
  *
- * @since unknown
+ * @since 2.5.0
  *
  * @param string $str
  * @return int|float
@@ -208,7 +200,7 @@ function wp_exif_frac2dec($str) {
 /**
  * Convert the exif date format to a unix timestamp.
  *
- * @since unknown
+ * @since 2.5.0
  *
  * @param string $str
  * @return int
@@ -223,7 +215,15 @@ function wp_exif_date2ts($str) {
 /**
  * Get extended image metadata, exif or iptc as available.
  *
- * @since unknown
+ * Retrieves the EXIF metadata aperture, credit, camera, caption, copyright, iso
+ * created_timestamp, focal_length, shutter_speed, and title.
+ *
+ * The IPTC metadata that is retrieved is APP13, credit, byline, created date
+ * and time, caption, copyright, and title. Also includes FNumber, Model,
+ * DateTimeDigitized, FocalLength, ISOSpeedRatings, and ExposureTime.
+ *
+ * @todo Try other exif libraries if available.
+ * @since 2.5.0
  *
  * @param string $file
  * @return bool|array False on failure. Image metadata array on success.
@@ -288,7 +288,6 @@ function wp_read_image_metadata( $file ) {
 		if (!empty($exif['ExposureTime']))
 			$meta['shutter_speed'] = wp_exif_frac2dec( $exif['ExposureTime'] );
 	}
-	/** @todo FIXME: try other exif libraries if available */
 
 	return apply_filters( 'wp_read_image_metadata', $meta, $file, $sourceImageType );
 
@@ -297,7 +296,7 @@ function wp_read_image_metadata( $file ) {
 /**
  * Validate that file is an image.
  *
- * @since unknown
+ * @since 2.5.0
  *
  * @param string $path File path to test if valid image.
  * @return bool True if valid image, false if not valid image.
@@ -310,7 +309,7 @@ function file_is_valid_image($path) {
 /**
  * Validate that file is suitable for displaying within a web page.
  *
- * @since unknown
+ * @since 2.5.0
  * @uses apply_filters() Calls 'file_is_displayable_image' on $result and $path.
  *
  * @param string $path File path to test.

wp-admin/includes/import.php

@@ -7,11 +7,11 @@
  */
 
 /**
- * {@internal Missing Short Description}}
+ * Retrieve list of importers.
  *
- * @since unknown
+ * @since 2.0.0
  *
- * @return unknown
+ * @return array
  */
 function get_importers() {
 	global $wp_importers;
@@ -21,15 +21,15 @@ function get_importers() {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Register importer for WordPress.
  *
- * @since unknown
+ * @since 2.0.0
  *
- * @param unknown_type $id
+ * @param string $id Importer tag. Used to uniquely identify importer.
- * @param unknown_type $name
+ * @param string $name Importer name and title.
- * @param unknown_type $description
+ * @param string $description Importer description.
- * @param unknown_type $callback
+ * @param callback $callback Callback to run.
- * @return unknown
+ * @return WP_Error Returns WP_Error when $callback is WP_Error.
  */
 function register_importer( $id, $name, $description, $callback ) {
 	global $wp_importers;
@@ -39,22 +39,24 @@ function register_importer( $id, $name, $description, $callback ) {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Cleanup importer.
  *
- * @since unknown
+ * Removes attachment based on ID.
  *
- * @param unknown_type $id
+ * @since 2.0.0
+ *
+ * @param string $id Importer ID.
  */
 function wp_import_cleanup( $id ) {
 	wp_delete_attachment( $id );
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Handle importer uploading and add attachment.
  *
- * @since unknown
+ * @since 2.0.0
  *
- * @return unknown
+ * @return array
  */
 function wp_import_handle_upload() {
 	$overrides = array( 'test_form' => false, 'test_type' => false );

wp-admin/includes/plugin-install.php

@@ -20,6 +20,8 @@
  *
  * The second filter, 'plugins_api', is the result that would be returned.
  *
+ * @since 2.7.0
+ *
  * @param string $action
  * @param array|object $args Optional. Arguments to serialize for the Plugin Info API.
  * @return mixed
@@ -44,10 +46,12 @@ function plugins_api($action, $args = null) {
 }
 
 /**
+ * Retrieve popular WordPress plugin tags.
  *
+ * @since 2.7.0
  *
- * @param unknown_type $args
+ * @param array $args
- * @return unknown
+ * @return array
  */
 function install_popular_tags( $args = array() ) {
 	if ( ! ($cache = wp_cache_get('popular_tags', 'api')) && ! ($cache = get_option('wporg_popular_tags')) )
@@ -67,6 +71,14 @@ function install_popular_tags( $args = array() ) {
 }
 
 add_action('install_plugins_search', 'install_search', 10, 1);
+
+/**
+ * Display search results and display as tag cloud.
+ *
+ * @since 2.7.0
+ *
+ * @param string $page
+ */
 function install_search($page) {
 	$type = isset($_REQUEST['type']) ? $_REQUEST['type'] : '';
 	$term = isset($_REQUEST['s']) ? $_REQUEST['s'] : '';
@@ -123,6 +135,11 @@ function install_search($page) {
 	echo wp_generate_tag_cloud($tags, array( 'single_text' => __('%d plugin'), 'multiple_text' => __('%d plugins') ) );
 }
 
+/**
+ * Display search form for searching plugins.
+ *
+ * @since 2.7.0
+ */
 function install_search_form(){
 	$type = isset($_REQUEST['type']) ? $_REQUEST['type'] : '';
 	$term = isset($_REQUEST['s']) ? $_REQUEST['s'] : '';
@@ -139,30 +156,70 @@ function install_search_form(){
 }
 
 add_action('install_plugins_featured', 'install_featured', 10, 1);
+
+/**
+ * Display featured plugins.
+ *
+ * @since 2.7.0
+ *
+ * @param string $page
+ */
 function install_featured($page){
 	$args = array('browse' => 'featured', 'page' => $page);
 	$api = plugins_api('query_plugins', $args);
 	display_plugins_table($api->plugins, $api->info['page'], $api->info['pages']);
 }
 add_action('install_plugins_popular', 'install_popular', 10, 1);
+
+/**
+ * Display popular plugins.
+ *
+ * @since 2.7.0
+ *
+ * @param string $page
+ */
 function install_popular($page){
 	$args = array('browse' => 'popular', 'page' => $page);
 	$api = plugins_api('query_plugins', $args);
 	display_plugins_table($api->plugins, $api->info['page'], $api->info['pages']);
 }
 add_action('install_plugins_new', 'install_new', 10, 1);
+
+/**
+ * Display new plugins.
+ *
+ * @since 2.7.0
+ *
+ * @param string $page
+ */
 function install_new($page){
 	$args = array('browse' => 'new', 'page' => $page);
 	$api = plugins_api('query_plugins', $args);
 	display_plugins_table($api->plugins, $api->info['page'], $api->info['pages']);
 }
 add_action('install_plugins_updated', 'install_updated', 10, 1);
+
+/**
+ * Display recently updated plugins.
+ *
+ * @since 2.7.0
+ *
+ * @param string $page
+ */
 function install_updated($page){
 	$args = array('browse' => 'updated', 'page' => $page);
 	$api = plugins_api('query_plugins', $args);
 	display_plugins_table($api->plugins, $api->info['page'], $api->info['pages']);
 }
 add_action('install_plugins_upload', 'install_upload_custom', 10, 1);
+
+/**
+ * Display upload plugin form for adding plugins by uploading them manually.
+ *
+ * @since 2.7.0
+ *
+ * @param string $page
+ */
 function install_upload_custom($page){
 	//$args = array('browse' => 'updated', 'page' => $page);
 	//$api = plugins_api('query_plugins', $args);
@@ -170,6 +227,15 @@ function install_upload_custom($page){
 	echo '<h1>Not Implemented</h1> <p>Will utilise SwfUpload(if available) & unzip .zip plugin packages</p>';
 }
 
+/**
+ * Display plugin content based on plugin list.
+ *
+ * @since 2.7.0
+ *
+ * @param array $plugins List of plugins.
+ * @param string $page
+ * @param int $totalpages Number of pages.
+ */
 function display_plugins_table($plugins, $page = 1, $totalpages = 1){
 	global $tab;
 
@@ -285,6 +351,13 @@ function display_plugins_table($plugins, $page = 1, $totalpages = 1){
 <?php
 }
 
+/**
+ * Display iframe header.
+ *
+ * @since 2.7.0
+ *
+ * @param string $title Title for iframe.
+ */
 function install_iframe_header($title = '') {
 if( empty($title) )
 	$title = __('Plugin Install &#8212; WordPress');
@@ -317,6 +390,11 @@ do_action('admin_head');
 <?php
 }
 
+/**
+ * Display iframe footer.
+ *
+ * @since 2.7.0
+ */
 function install_iframe_footer() {
 echo '
 </body>
@@ -324,6 +402,12 @@ echo '
 }
 
 add_action('install_plugins_pre_plugin-information', 'install_plugin_information');
+
+/**
+ * Display plugin information in dialog box form.
+ *
+ * @since 2.7.0
+ */
 function install_plugin_information() {
 	global $tab;
 
@@ -447,6 +531,12 @@ function install_plugin_information() {
 }
 
 add_action('install_plugins_pre_install', 'install_plugin');
+
+/**
+ * Display plugin link and execute install.
+ *
+ * @since 2.7.0
+ */
 function install_plugin() {
 
 	$plugin = isset($_REQUEST['plugin']) ? $_REQUEST['plugin'] : '';
@@ -465,7 +555,16 @@ function install_plugin() {
 
 	exit;
 }
-function do_plugin_install($download_url = '', $plugin_information = NULL) {
+
+/**
+ * Retrieve plugin and install.
+ *
+ * @since 2.7.0
+ *
+ * @param string $download_url Optional. Download URL.
+ * @param object $plugin_information Optional. Plugin information
+ */
+function do_plugin_install($download_url = '', $plugin_information = null) {
 	global $wp_filesystem;
 
 	if ( empty($download_url) ) {
@@ -512,6 +611,15 @@ function do_plugin_install($download_url = '', $plugin_information = NULL) {
 	}
 }
 
+/**
+ * Install plugin.
+ *
+ * @since 2.7.0
+ *
+ * @param string $package
+ * @param string $feedback Optional.
+ * @return mixed.
+ */
 function wp_install_plugin($package, $feedback = '') {
 	global $wp_filesystem;
 

wp-admin/includes/post.php

@@ -467,7 +467,7 @@ function wp_write_post() {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Calls wp_write_post() and handles the errors.
  *
  * @since unknown
  *

wp-admin/includes/schema.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * WordPress Schema for installation and upgrading.
+ * WordPress Administration Scheme API
  *
  * Here we keep the DB structure and option values.
  *
@@ -8,7 +8,12 @@
  * @subpackage Administration
  */
 
-/** WordPress Database collate charset */
+/**
+ * The database character collate.
+ * @var string
+ * @global string
+ * @name $charset_collate
+ */
 $charset_collate = '';
 
 // Declare these as global in case schema.php is included from a function.
@@ -164,7 +169,7 @@ CREATE TABLE $wpdb->usermeta (
 /**
  * Create WordPress options and set the default values.
  *
- * @since unknown
+ * @since 1.5.0
  * @uses $wpdb
  * @uses $wp_db_version
  */
@@ -299,7 +304,7 @@ function populate_options() {
 /**
  * Execute WordPress role creation for the various WordPress versions.
  *
- * @since unknown (2.0.0)
+ * @since 2.0.0
  */
 function populate_roles() {
 	populate_roles_160();

wp-admin/includes/update.php

@@ -1,4 +1,10 @@
 <?php
+/**
+ * WordPress Administration Update API
+ *
+ * @package WordPress
+ * @subpackage Admin
+ */
 
 // The admin side of our 1.1 update system
 

wp-admin/menu-header.php

@@ -20,6 +20,16 @@ global $menu, $submenu, $parent_file; //For when admin-header is included from w
 
 get_admin_page_parent();
 
+/**
+ * Display menu.
+ *
+ * @access private
+ * @since 2.7.0
+ *
+ * @param array $menu
+ * @param array $submenu
+ * @param bool $submenu_as_parent
+ */
 function _wp_menu_output( &$menu, &$submenu, $submenu_as_parent = true ) {
 	global $self, $parent_file, $submenu_file, $plugin_page, $pagenow;
 

wp-admin/plugins.php

@@ -266,6 +266,12 @@ foreach( (array)$all_plugins as $plugin_file => $plugin_data) {
 ?>
 
 <?php
+/**
+ * @ignore
+ *
+ * @param array $plugins
+ * @param string $context
+ */
 function print_plugins_table($plugins, $context = '') {
 ?>
 <table class="widefat" id="<?php echo $context ?>-plugins-table">

wp-admin/press-this.php

@@ -16,7 +16,7 @@ if ( ! current_user_can('publish_posts') ) wp_die( __( 'Cheatin’ uh?' ) );
  *
  * @package WordPress
  * @subpackage Press_This
- * @since unknown
+ * @since 2.6.0
  *
  * @param string $string
  * @return string
@@ -30,7 +30,7 @@ function preg_quote2($string) {
  *
  * @package WordPress
  * @subpackage Press_This
- * @since unknown
+ * @since 2.6.0
  *
  * @param string $text
  * @return string
@@ -47,7 +47,7 @@ function aposfix($text) {
  *
  * @package WordPress
  * @subpackage Press_This
- * @since unknown
+ * @since 2.6.0
  *
  * @return int Post ID
  */
@@ -173,6 +173,16 @@ switch ($_REQUEST['ajax']) {
 		<p id="options"><a href="#" class="select"><?php _e('Insert Image'); ?></a> | <a href="#" class="cancel"><?php _e('Cancel'); ?></a></p>
 		<?php break;
 	case 'photo_images':
+		/**
+		 * Retrieve all image URLs from given URI.
+		 *
+		 * @package WordPress
+		 * @subpackage Press_This
+		 * @since 2.6.0
+		 *
+		 * @param string $uri
+		 * @return string
+		 */
 		function get_images_from_uri($uri) {
 			if( preg_match('/\.(jpg|jpe|jpeg|png|gif)$/', $uri) && !strpos($uri,'blogger.com') )
 				return "'".$uri."'";

wp-admin/setup-config.php

@@ -12,7 +12,6 @@
 /**
  * We are installing.
  *
- * @since unknown
  * @package WordPress
  */
 define('WP_INSTALLING', true);
@@ -49,7 +48,8 @@ else
 /**
  * Display setup wp-config.php file header.
  *
- * @since unknown
+ * @ignore
+ * @since 2.3.0
  * @package WordPress
  * @subpackage Installer_WP_Config
  */

wp-admin/themes.php

@@ -59,6 +59,16 @@ $page_links = paginate_links( array(
 
 $themes = array_slice( $themes, $start, $per_page );
 
+/**
+ * Check if there is an update for a theme available.
+ *
+ * Will display link, if there is an update available.
+ *
+ * @since 2.7.0
+ *
+ * @param object $theme Theme data object.
+ * @return bool False if no valid info was passed.
+ */
 function theme_update_available( $theme ) {
 	static $themes_update;
 	if ( !isset($themes_update) )

wp-admin/user-edit.php

@@ -17,8 +17,7 @@ else
 /**
  * Display JavaScript for profile page.
  *
- * @package WordPress
+ * @since 2.5.0
- * @subpackage Administration
  */
 function profile_js ( ) {
 ?>
@@ -101,7 +100,13 @@ if ( !$user_id ) {
 	}
 }
 
-// Optional SSL preference that can be turned on by hooking to the 'personal_options' action 
+/**
+ * Optional SSL preference that can be turned on by hooking to the 'personal_options' action.
+ *
+ * @since 2.7.0
+ *
+ * @param object $user User data object
+ */
 function use_ssl_preference($user) {
 ?>
 	<tr>