From 8a4fa5662b3dadc55d4ed6d59067b5be32022b80 Mon Sep 17 00:00:00 2001
From: Scott Taylor <wonderboymusic@git.wordpress.org>
Date: Mon, 1 Dec 2014 00:59:43 +0000
Subject: [PATCH] Improve various `@param` docs for `src/wp-admin/*`.

See #30224.


git-svn-id: https://develop.svn.wordpress.org/trunk@30680 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/class-wp-upgrader-skins.php |  9 +++++++++
 src/wp-admin/includes/media.php                   | 10 +++++-----
 src/wp-admin/includes/plugin-install.php          |  2 +-
 src/wp-admin/includes/post.php                    |  6 +++---
 src/wp-admin/includes/screen.php                  |  4 ++--
 src/wp-admin/includes/template.php                | 15 ++++++++-------
 src/wp-admin/includes/theme.php                   |  2 +-
 src/wp-admin/includes/upgrade.php                 |  8 ++++----
 8 files changed, 33 insertions(+), 23 deletions(-)

diff --git a/src/wp-admin/includes/class-wp-upgrader-skins.php b/src/wp-admin/includes/class-wp-upgrader-skins.php
index 9cd665fe4d..7d40373952 100644
--- a/src/wp-admin/includes/class-wp-upgrader-skins.php
+++ b/src/wp-admin/includes/class-wp-upgrader-skins.php
@@ -27,6 +27,9 @@ class WP_Upgrader_Skin {
 		$this->options = wp_parse_args($args, $defaults);
 	}
 
+	/**
+	 * @param WP_Upgrader $upgrader
+	 */
 	public function set_upgrader(&$upgrader) {
 		if ( is_object($upgrader) )
 			$this->upgrader =& $upgrader;
@@ -216,6 +219,9 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin {
 		$this->upgrader->strings['skin_upgrade_end'] = __('All updates have been completed.');
 	}
 
+	/**
+	 * @param string $string
+	 */
 	public function feedback($string) {
 		if ( isset( $this->upgrader->strings[$string] ) )
 			$string = $this->upgrader->strings[$string];
@@ -721,6 +727,9 @@ class Automatic_Upgrader_Skin extends WP_Upgrader_Skin {
 		return $this->messages;
 	}
 
+	/**
+	 * @param string|array|WP_Error $data
+	 */
 	public function feedback( $data ) {
 		if ( is_wp_error( $data ) )
 			$string = $data->get_error_message();
diff --git a/src/wp-admin/includes/media.php b/src/wp-admin/includes/media.php
index 2ff1a3d38b..7fa4dd8f05 100644
--- a/src/wp-admin/includes/media.php
+++ b/src/wp-admin/includes/media.php
@@ -432,7 +432,7 @@ function media_handle_sideload($file_array, $post_id, $desc = null, $post_data =
  *
  * @since 2.5.0
  *
- * @param array $content_func
+ * @param string|callable $content_func
  */
 function wp_iframe($content_func /* ... */) {
 	_wp_admin_html_begin();
@@ -916,7 +916,7 @@ function media_upload_library() {
  *
  * @since 2.7.0
  *
- * @param object $post
+ * @param WP_Post $post
  * @param string $checked
  * @return string
  */
@@ -944,7 +944,7 @@ function image_align_input_fields( $post, $checked = '' ) {
  *
  * @since 2.7.0
  *
- * @param object $post
+ * @param WP_Post $post
  * @param bool|string $check
  * @return array
  */
@@ -1016,7 +1016,7 @@ function image_size_input_fields( $post, $check = '' ) {
  *
  * @since 2.7.0
  *
- * @param object $post
+ * @param WP_Post $post
  * @param string $url_type
  * @return string
  */
@@ -2930,7 +2930,7 @@ function wp_add_id3_tag_data( &$metadata, $data ) {
  * @since 3.6.0
  *
  * @param string $file Path to file.
- * @return array|boolean Returns array of metadata, if found.
+ * @return array|bool Returns array of metadata, if found.
  */
 function wp_read_video_metadata( $file ) {
 	if ( ! file_exists( $file ) )
diff --git a/src/wp-admin/includes/plugin-install.php b/src/wp-admin/includes/plugin-install.php
index df44c9bebe..055ff1f0e1 100644
--- a/src/wp-admin/includes/plugin-install.php
+++ b/src/wp-admin/includes/plugin-install.php
@@ -190,7 +190,7 @@ function install_search_form( $type_selector = true ) {
  * Upload from zip
  * @since 2.8.0
  *
- * @param string $page
+ * @param integer $page
  */
 function install_plugins_upload( $page = 1 ) {
 ?>
diff --git a/src/wp-admin/includes/post.php b/src/wp-admin/includes/post.php
index 81ab8329a8..6efb9be32a 100644
--- a/src/wp-admin/includes/post.php
+++ b/src/wp-admin/includes/post.php
@@ -1120,7 +1120,7 @@ function postbox_classes( $id, $page ) {
  *
  * @since 2.5.0
  *
- * @param int|object $id    Post ID or post object.
+ * @param integer $id    Post ID or post object.
  * @param string $title (optional) Title
  * @param string $name (optional) Name
  * @return array With two entries of type string
@@ -1185,7 +1185,7 @@ function get_sample_permalink($id, $title = null, $name = null) {
  *
  * @since 2.5.0
  *
- * @param int|object $id Post ID or post object.
+ * @param integer $id Post ID or post object.
  * @param string $new_title Optional. New title.
  * @param string $new_slug Optional. New slug.
  * @return string The HTML of the sample permalink slug editor.
@@ -1308,7 +1308,7 @@ function _wp_post_thumbnail_html( $thumbnail_id = null, $post = null ) {
  * @since 2.5.0
  *
  * @param int $post_id ID of the post to check for editing
- * @return bool|int False: not locked or locked by current user. Int: user ID of user with lock.
+ * @return integer False: not locked or locked by current user. Int: user ID of user with lock.
  */
 function wp_check_post_lock( $post_id ) {
 	if ( !$post = get_post( $post_id ) )
diff --git a/src/wp-admin/includes/screen.php b/src/wp-admin/includes/screen.php
index 94b1c5a9a2..41c4fb95bc 100644
--- a/src/wp-admin/includes/screen.php
+++ b/src/wp-admin/includes/screen.php
@@ -60,7 +60,7 @@ function get_hidden_columns( $screen ) {
  *
  * @since 2.7.0
  *
- * @param string|WP_Screen $screen
+ * @param WP_Screen $screen
  */
 function meta_box_prefs( $screen ) {
 	global $wp_meta_boxes;
@@ -650,7 +650,7 @@ final class WP_Screen {
 	 * @param string $option Option name.
 	 * @param string $key    Optional. Specific array key for when the option is an array.
 	 *                       Default false.
-	 * @return mixed The option value if set, null otherwise.
+	 * @return string The option value if set, null otherwise.
 	 */
 	public function get_option( $option, $key = false ) {
 		if ( ! isset( $this->_options[ $option ] ) )
diff --git a/src/wp-admin/includes/template.php b/src/wp-admin/includes/template.php
index e6ac370baf..ad960319ce 100644
--- a/src/wp-admin/includes/template.php
+++ b/src/wp-admin/includes/template.php
@@ -403,7 +403,7 @@ function get_inline_data($post) {
  *
  * @since 2.7.0
  *
- * @param string|int $position
+ * @param int $position
  * @param bool $checkbox
  * @param string $mode
  * @param bool $table_row
@@ -707,10 +707,10 @@ function meta_form( $post = null ) {
  *
  * @since 0.71
  *
- * @param int|bool $edit      Accepts 1|true for editing the date, 0|false for adding the date.
- * @param int|bool $for_post  Accepts 1|true for applying the date to a post, 0|false for a comment.
- * @param int|bool $tab_index The tabindex attribute to add. Default 0.
- * @param int|bool $multi     Optional. Whether the additional fields and buttons should be added.
+ * @param int $edit      Accepts 1|true for editing the date, 0|false for adding the date.
+ * @param int $for_post  Accepts 1|true for applying the date to a post, 0|false for a comment.
+ * @param int $tab_index The tabindex attribute to add. Default 0.
+ * @param int $multi     Optional. Whether the additional fields and buttons should be added.
  *                            Default 0|false.
  */
 function touch_time( $edit = 1, $for_post = 1, $tab_index = 0, $multi = 0 ) {
@@ -813,7 +813,7 @@ function page_template_dropdown( $default = '' ) {
  * @param int $parent  Optional. The parent page ID. Default 0.
  * @param int $level   Optional. Page depth level. Default 0.
  *
- * @return void|bool Boolean False if page has no children, otherwise print out html elements
+ * @return null|false Boolean False if page has no children, otherwise print out html elements
  */
 function parent_dropdown( $default = 0, $parent = 0, $level = 0 ) {
 	global $wpdb;
@@ -992,7 +992,8 @@ function add_meta_box( $id, $title, $callback, $screen = null, $context = 'advan
  *
  * @since 2.5.0
  *
- * @param string|object $screen Screen identifier
+ * @staticvar bool $already_sorted
+ * @param string|WP_Screen $screen Screen identifier
  * @param string $context box context
  * @param mixed $object gets passed to the box callback function as first parameter
  * @return int number of meta_boxes
diff --git a/src/wp-admin/includes/theme.php b/src/wp-admin/includes/theme.php
index faed0a8e5b..36bfbe7e0c 100644
--- a/src/wp-admin/includes/theme.php
+++ b/src/wp-admin/includes/theme.php
@@ -138,7 +138,7 @@ function theme_update_available( $theme ) {
  * @since 3.8.0
  *
  * @param WP_Theme $theme WP_Theme object.
- * @return string|bool HTML for the update link, or false if invalid info was passed.
+ * @return false|string HTML for the update link, or false if invalid info was passed.
  */
 function get_theme_update_available( $theme ) {
 	static $themes_update;
diff --git a/src/wp-admin/includes/upgrade.php b/src/wp-admin/includes/upgrade.php
index 195eeae1fd..2a3f5a2ab6 100644
--- a/src/wp-admin/includes/upgrade.php
+++ b/src/wp-admin/includes/upgrade.php
@@ -30,7 +30,7 @@ if ( !function_exists('wp_install') ) :
  * @param string $user_name User's username.
  * @param string $user_email User's email.
  * @param bool $public Whether blog is public.
- * @param null $deprecated Optional. Not used.
+ * @param string $deprecated Optional. Not used.
  * @param string $user_password Optional. User's chosen password. Will default to a random password.
  * @param string $language Optional. Language chosen.
  * @return array Array keys 'url', 'user_id', 'password', 'password_message'.
@@ -1532,7 +1532,7 @@ function maybe_add_column($table_name, $column_name, $create_ddl) {
  *
  * @since 1.2.0
  *
- * @return array List of options.
+ * @return stdClass List of options.
  */
 function get_alloptions_110() {
 	global $wpdb;
@@ -1975,7 +1975,7 @@ function make_site_theme_from_oldschool($theme_name, $template) {
  *
  * @param string $theme_name
  * @param string $template
- * @return bool|null
+ * @return null|false
  */
 function make_site_theme_from_default($theme_name, $template) {
 	$site_dir = WP_CONTENT_DIR . "/themes/$template";
@@ -2039,7 +2039,7 @@ function make_site_theme_from_default($theme_name, $template) {
  *
  * @since 1.5.0
  *
- * @return string|bool
+ * @return false|string
  */
 function make_site_theme() {
 	// Name the theme after the blog.