More phpdoc updates for wp-adming. See #7496 props santosj.

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

wp-admin/custom-header.php

@@ -1,12 +1,45 @@
 <?php
+/**
+ * The custom header image script.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 
+/**
+ * The custom header image class.
+ *
+ * @since unknown
+ * @package WordPress
+ * @subpackage Administration
+ */
 class Custom_Image_Header {
+
+	/**
+	 * Callback for administration header.
+	 *
+	 * @var callback
+	 * @since unknown
+	 * @access private
+	 */
 	var $admin_header_callback;
 
+	/**
+	 * PHP4 Constructor - Register administration header callback.
+	 *
+	 * @since unknown
+	 * @param callback $admin_header_callback
+	 * @return Custom_Image_Header
+	 */
 	function Custom_Image_Header($admin_header_callback) {
 		$this->admin_header_callback = $admin_header_callback;
 	}
 
+	/**
+	 * Setup the hooks for the Custom Header admin page.
+	 *
+	 * @since unknown
+	 */
 	function init() {
 		$page = add_theme_page(__('Custom Image Header'), __('Custom Image Header'), 'edit_themes', 'custom-header', array(&$this, 'admin_page'));
 
@@ -16,21 +49,43 @@ class Custom_Image_Header {
 		add_action("admin_head-$page", $this->admin_header_callback, 51);
 	}
 
+	/**
+	 * Get the current step.
+	 *
+	 * @since unknown
+	 *
+	 * @return int Current step
+	 */
 	function step() {
-		$step = (int) @$_GET['step'];
+		if ( ! isset( $_GET['step'] ) )
+			return 1;
+
+		$step = (int) $_GET['step'];
 		if ( $step < 1 || 3 < $step )
 			$step = 1;
+
 		return $step;
 	}
 
+	/**
+	 * Setup the enqueue for the JavaScript files.
+	 *
+	 * @since unknown
+	 */
 	function js_includes() {
 		$step = $this->step();
+
 		if ( 1 == $step )
 			wp_enqueue_script('colorpicker');
 		elseif ( 2 == $step )
 			wp_enqueue_script('cropper');
 	}
 
+	/**
+	 * Execute custom header modification.
+	 *
+	 * @since unknown
+	 */
 	function take_action() {
 		if ( isset( $_POST['textcolor'] ) ) {
 			check_admin_referer('custom-header');
@@ -48,6 +103,11 @@ class Custom_Image_Header {
 		}
 	}
 
+	/**
+	 * Execute Javascript depending on step.
+	 *
+	 * @since unknown
+	 */
 	function js() {
 		$step = $this->step();
 		if ( 1 == $step )
@@ -56,6 +116,11 @@ class Custom_Image_Header {
 			$this->js_2();
 	}
 
+	/**
+	 * Display Javascript based on Step 1.
+	 *
+	 * @since unknown
+	 */
 	function js_1() { ?>
 <script type="text/javascript">
 	var cp = new ColorPicker();
@@ -129,6 +194,11 @@ Event.observe( window, 'load', hide_text );
 <?php
 	}
 
+	/**
+	 * Display Javascript based on Step 2.
+	 *
+	 * @since unknown
+	 */
 	function js_2() { ?>
 <script type="text/javascript">
 	function onEndCrop( coords, dimensions ) {
@@ -173,6 +243,11 @@ Event.observe( window, 'load', hide_text );
 <?php
 	}
 
+	/**
+	 * Display first step of custom header image page.
+	 *
+	 * @since unknown
+	 */
 	function step_1() {
 		if ( $_GET['updated'] ) { ?>
 <div id="message" class="updated fade">
@@ -226,6 +301,11 @@ Event.observe( window, 'load', hide_text );
 
 	}
 
+	/**
+	 * Display second step of custom header image page.
+	 *
+	 * @since unknown
+	 */
 	function step_2() {
 		check_admin_referer('custom-header');
 		$overrides = array('test_form' => false);
@@ -298,6 +378,11 @@ Event.observe( window, 'load', hide_text );
 		<?php
 	}
 
+	/**
+	 * Display third step of custom header image page.
+	 *
+	 * @since unknown
+	 */
 	function step_3() {
 		check_admin_referer('custom-header');
 		if ( $_POST['oitar'] > 1 ) {
@@ -339,6 +424,11 @@ Event.observe( window, 'load', hide_text );
 		return $this->finished();
 	}
 
+	/**
+	 * Display last step of custom header image page.
+	 *
+	 * @since unknown
+	 */
 	function finished() {
 		?>
 <div class="wrap">
@@ -350,6 +440,11 @@ Event.observe( window, 'load', hide_text );
 		<?php
 	}
 
+	/**
+	 * Display the page based on the current step.
+	 *
+	 * @since unknown
+	 */
 	function admin_page() {
 		$step = $this->step();
 		if ( 1 == $step )

wp-admin/edit-attachment-rows.php

@@ -1,4 +1,13 @@
-<?php if ( ! defined('ABSPATH') ) die(); ?>
+<?php
+/**
+ * Edit attachments table for inclusion in administration panels.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+if ( ! defined('ABSPATH') ) die();
+?>
 <table class="widefat">
 	<thead>
 	<tr>

wp-admin/edit-category-form.php

@@ -1,5 +1,15 @@
 <?php
+/**
+ * Edit category form for inclusion in administration panels.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
 if ( ! empty($cat_ID) ) {
+	/**
+	 * @var string
+	 */
 	$heading = __('Edit Category');
 	$submit_text = __('Edit Category');
 	$form = '<form name="editcat" id="editcat" method="post" action="categories.php" class="validate">';

wp-admin/edit-comments.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Edit Comments Administration Panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $title = __('Edit Comments');

wp-admin/edit-form-advanced.php

@@ -1,5 +1,16 @@
 <?php
+/**
+ * Post advanced form for inclusion in the administration panels.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 
+/**
+ * Post ID global
+ * @name $post_ID
+ * @var int
+ */
 if ( ! isset( $post_ID ) )
 	$post_ID = 0;
 

wp-admin/edit-form-comment.php

@@ -1,4 +1,14 @@
 <?php
+/**
+ * Edit comment form for inclusion in another file.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/**
+ * @var string
+ */
 $submitbutton_text = __('Edit Comment');
 $toprow_title = sprintf(__('Editing Comment # %s'), $comment->comment_ID);
 $form_action = 'editedcomment';

wp-admin/edit-link-categories.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Edit Link Categories Administration Panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 // Handle bulk deletes

wp-admin/edit-link-category-form.php

@@ -1,5 +1,15 @@
 <?php
+/**
+ * Edit link category form for inclusion in administration panels.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
 if ( ! empty($cat_ID) ) {
+	/**
+	 * @var string
+	 */
 	$heading = __('Edit Category');
 	$submit_text = __('Edit Category');
 	$form = '<form name="editcat" id="editcat" method="post" action="link-category.php" class="validate">';

wp-admin/edit-link-form.php

@@ -1,5 +1,15 @@
 <?php
+/**
+ * Edit links form for inclusion in administration panels.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
 if ( ! empty($link_id) ) {
+	/**
+	 * @var string
+	 */
 	$heading = __('Edit Link');
 	$submit_text = __('Save Changes');
 	$form = '<form name="editlink" id="editlink" method="post" action="link.php">';

wp-admin/edit-page-form.php

@@ -1,5 +1,16 @@
 <?php
+/**
+ * Edit page form for inclusion in the administration panels.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 
+/**
+ * Post ID global
+ * @name $post_ID
+ * @var int
+ */
 if ( ! isset( $post_ID ) )
 	$post_ID = 0;
 

wp-admin/edit-pages.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Edit Pages Administration Panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 // Handle bulk deletes

wp-admin/edit-post-rows.php

@@ -1,4 +1,13 @@
-<?php if ( ! defined('ABSPATH') ) die(); ?>
+<?php
+/**
+ * Edit posts rows table for inclusion in administration panels.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+if ( ! defined('ABSPATH') ) die();
+?>
 <table class="widefat">
 	<thead>
 	<tr>

wp-admin/edit-tag-form.php

@@ -1,5 +1,15 @@
 <?php
+/**
+ * Edit tag form for inclusion in administration panels.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
 if ( ! empty($tag_ID) ) {
+	/**
+	 * @var string
+	 */
 	$heading = __('Edit Tag');
 	$submit_text = __('Edit Tag');
 	$form = '<form name="edittag" id="edittag" method="post" action="edit-tags.php" class="validate">';

wp-admin/edit-tags.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Edit Tags Administration Panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $title = __('Tags');

wp-admin/edit.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Edit Posts Administration Panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 // Handle bulk deletes

wp-admin/options-discussion.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Discussion settings administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $title = __('Discussion Settings');

wp-admin/options-general.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * General settings administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('./admin.php');
 
 $title = __('General Settings');

wp-admin/options-misc.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Miscellaneous settings administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $title = __('Miscellaneous Settings');

wp-admin/options-permalink.php

@@ -1,9 +1,23 @@
 <?php
+/**
+ * Permalink settings administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $title = __('Permalink Settings');
 $parent_file = 'options-general.php';
 
+/**
+ * Display JavaScript on the page.
+ *
+ * @package WordPress
+ * @subpackage Permalink_Settings_Panel
+ */
 function add_js() {
 ?>
 <script type="text/javascript">

wp-admin/options-reading.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Reading settings administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $title = __('Reading Settings');

wp-admin/options-writing.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Writing settings administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $title = __('Writing Settings');

wp-admin/options.php

@@ -1,4 +1,18 @@
 <?php
+/**
+ * Options Management Administration Panel.
+ *
+ * Just allows for displaying of options.
+ *
+ * This isn't referenced or linked to, but will show all of the options and
+ * allow editing. The issue is that serialized data is not supported to be
+ * modified. Options can not be removed.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $title = __('Settings');

wp-admin/page-new.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * New page administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 $title = __('New Page');
 $parent_file = 'post-new.php';

wp-admin/page.php

@@ -1,4 +1,14 @@
 <?php
+/**
+ * Edit page administration panel.
+ *
+ * Manage edit page: post, edit, delete, etc.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $parent_file = 'edit.php';
@@ -6,6 +16,11 @@ $submenu_file = 'edit-pages.php';
 
 wp_reset_vars(array('action'));
 
+/**
+ * Redirect to previous page.
+ *
+ * @param int $page_ID Page ID.
+ */
 function redirect_page($page_ID) {
 	$referredby = '';
 	if ( !empty($_POST['referredby']) ) {

wp-admin/plugin-editor.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Edit plugin editor administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $title = __("Edit Plugins");

wp-admin/plugin-install.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Install plugin administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 if ( ! current_user_can('install_plugins') )

wp-admin/plugins.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Plugins administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $action = '';

wp-admin/post.php

@@ -1,4 +1,14 @@
 <?php
+/**
+ * Edit post administration panel.
+ *
+ * Manage Post actions: post, edit, delete, etc.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $parent_file = 'edit.php';
@@ -6,6 +16,11 @@ $submenu_file = 'edit.php';
 
 wp_reset_vars(array('action', 'safe_mode', 'withcomments', 'posts', 'content', 'edited_post_title', 'comment_error', 'profile', 'trackback_url', 'excerpt', 'showcomments', 'commentstart', 'commentend', 'commentorder'));
 
+/**
+ * Redirect to previous page.
+ *
+ * @param int $post_ID Optional. Post ID.
+ */
 function redirect_post($post_ID = '') {
 	global $action;
 

wp-admin/press-this.php

@@ -1,17 +1,56 @@
 <?php
+/**
+ * Press This Display and Handler.
+ *
+ * @package WordPress
+ * @subpackage Press_This
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 if ( ! current_user_can('publish_posts') ) wp_die( __( 'Cheatin&#8217; uh?' ) );
 
+/**
+ * Replace forward slash with backslash and slash.
+ *
+ * @package WordPress
+ * @subpackage Press_This
+ * @since unknown
+ *
+ * @param string $string
+ * @return string
+ */
 function preg_quote2($string) {
 	return str_replace('/', '\/', preg_quote($string));
 }
+
+/**
+ * Convert characters.
+ *
+ * @package WordPress
+ * @subpackage Press_This
+ * @since unknown
+ *
+ * @param string $text
+ * @return string
+ */
 function aposfix($text) {
 	$translation_table[chr(34)] = '&quot;';
 	$translation_table[chr(38)] = '&';
 	$translation_table[chr(39)] = '&apos;';
 	return preg_replace("/&(?![A-Za-z]{0,4}\w{2,3};|#[0-9]{2,3};)/","&amp;" , strtr($text, $translation_table));
 }
+
+/**
+ * Press It form handler.
+ *
+ * @package WordPress
+ * @subpackage Press_This
+ * @since unknown
+ *
+ * @return int Post ID
+ */
 function press_it() {
 	// define some basic variables
 	$quick['post_status'] = isset($_REQUEST['publish']) ? 'publish' : 'draft';

wp-admin/revision.php

@@ -1,5 +1,12 @@
 <?php
+/**
+ * Revisions administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 wp_reset_vars(array('revision', 'left', 'right', 'action'));

wp-admin/theme-editor.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Theme editor administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 $title = __("Edit Themes");

wp-admin/themes.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Themes administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 if ( isset($_GET['action']) ) {

wp-admin/update.php

@@ -1,10 +1,24 @@
 <?php
+/**
+ * Update Plugin / Core administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 if ( ! current_user_can('update_plugins') )
 	wp_die(__('You do not have sufficient permissions to update plugins for this blog.'));
 
+/**
+ * Plugin upgrade display.
+ *
+ * @since 2.5
+ *
+ * @param string $plugin Plugin
+ */
 function do_plugin_upgrade($plugin) {
 	global $wp_filesystem;
 
@@ -44,6 +58,13 @@ function do_plugin_upgrade($plugin) {
 	echo '</div>';
 }
 
+/**
+ * Display upgrade WordPress for downloading latest or upgrading automatically form.
+ *
+ * @since 2.7
+ *
+ * @return null
+ */
 function core_upgrade_preamble() {
 	$update = get_option('update_core');
 
@@ -57,7 +78,7 @@ function core_upgrade_preamble() {
 	}
 
 	if ( 'development' == $update->response ) {
-		$message = __('You are using a developmemt version of WordPress.  You can upgrade to the latest nightly build automatically or download the nightly build and install it manually. Which would you like to do?');
+		$message = __('You are using a development version of WordPress.  You can upgrade to the latest nightly build automatically or download the nightly build and install it manually. Which would you like to do?');
 		$submit = __('Download nightly build');
 	} else {
 		$message = 	sprintf(__('You can upgrade to version %s automatically or download the nightly build and install it manually. Which would you like to do?'), $update->current);
@@ -78,6 +99,13 @@ function core_upgrade_preamble() {
 	echo '</div>';
 }
 
+/**
+ * Upgrade WordPress core display.
+ *
+ * @since 2.7
+ *
+ * @return null
+ */
 function do_core_upgrade() {
 	global $wp_filesystem;
 

wp-admin/upload.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * Media Library administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 if (!current_user_can('upload_files'))

wp-admin/user-edit.php

@@ -1,5 +1,12 @@
 <?php
+/**
+ * Edit user administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
 
 if ( defined('IS_PROFILE_PAGE') && IS_PROFILE_PAGE )
@@ -7,6 +14,12 @@ if ( defined('IS_PROFILE_PAGE') && IS_PROFILE_PAGE )
 else
 	$is_profile_page = false;
 
+/**
+ * Display JavaScript for profile page.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 function profile_js ( ) {
 ?>
 <script type="text/javascript">

wp-admin/users.php

@@ -1,5 +1,15 @@
 <?php
+/**
+ * Users administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+/** WordPress Administration Bootstrap */
 require_once('admin.php');
+
+/** WordPress Registration API */
 require_once( ABSPATH . WPINC . '/registration.php');
 
 if ( !current_user_can('edit_users') )

wp-admin/widgets.php

@@ -1,6 +1,15 @@
 <?php
+/**
+ * Widgets administration panel.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
 
+/** WordPress Administration Bootstrap */
 require_once( 'admin.php' );
+
+/** WordPress Administration Widgets API */
 require_once(ABSPATH . 'wp-admin/includes/widgets.php');
 
 if ( ! current_user_can('switch_themes') )