From b3e0cfd25de82e40362ebd8449728dc3ee11117a Mon Sep 17 00:00:00 2001 From: Scott Taylor Date: Fri, 29 May 2015 21:17:27 +0000 Subject: [PATCH] Add (more) missing doc blocks to `wp-admin/includes/*`. See #32444. Built from https://develop.svn.wordpress.org/trunk@32655 git-svn-id: http://core.svn.wordpress.org/trunk@32625 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/class-wp-upgrader-skins.php | 85 ++++++++++++++++++- wp-admin/includes/class-wp-upgrader.php | 38 ++++++++- wp-admin/includes/dashboard.php | 7 ++ wp-admin/includes/export.php | 6 ++ wp-admin/includes/import.php | 8 +- wp-admin/includes/menu.php | 12 ++- wp-admin/includes/nav-menu.php | 4 + wp-admin/includes/plugin-install.php | 6 ++ wp-admin/includes/screen.php | 10 +-- wp-includes/version.php | 2 +- 10 files changed, 162 insertions(+), 16 deletions(-) diff --git a/wp-admin/includes/class-wp-upgrader-skins.php b/wp-admin/includes/class-wp-upgrader-skins.php index 942542e08f..0c6426c230 100644 --- a/wp-admin/includes/class-wp-upgrader-skins.php +++ b/wp-admin/includes/class-wp-upgrader-skins.php @@ -22,6 +22,10 @@ class WP_Upgrader_Skin { public $result = false; public $options = array(); + /** + * + * @param array $args + */ public function __construct($args = array()) { $defaults = array( 'url' => '', 'nonce' => '', 'title' => '', 'context' => false ); $this->options = wp_parse_args($args, $defaults); @@ -43,6 +47,13 @@ class WP_Upgrader_Skin { $this->result = $result; } + /** + * + * @param bool $error + * @param string $context + * @param bool $allow_relaxed_file_ownership + * @return type + */ public function request_filesystem_credentials( $error = false, $context = false, $allow_relaxed_file_ownership = false ) { $url = $this->options['url']; if ( ! $context ) { @@ -73,6 +84,10 @@ class WP_Upgrader_Skin { echo ''; } + /** + * + * @param string|WP_Error $errors + */ public function error($errors) { if ( ! $this->done_header ) $this->header(); @@ -88,6 +103,10 @@ class WP_Upgrader_Skin { } } + /** + * + * @param string $string + */ public function feedback($string) { if ( isset( $this->upgrader->strings[$string] ) ) $string = $this->upgrader->strings[$string]; @@ -154,7 +173,11 @@ class Plugin_Upgrader_Skin extends WP_Upgrader_Skin { public $plugin_active = false; public $plugin_network_active = false; - public function __construct($args = array()) { + /** + * + * @param array $args + */ + public function __construct( $args = array() ) { $defaults = array( 'url' => '', 'plugin' => '', 'nonce' => '', 'title' => __('Update Plugin') ); $args = wp_parse_args($args, $defaults); @@ -210,6 +233,10 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { */ public $error = false; + /** + * + * @param array $args + */ public function __construct($args = array()) { $defaults = array( 'url' => '', 'nonce' => '' ); $args = wp_parse_args($args, $defaults); @@ -256,6 +283,11 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { public function footer() { // Nothing, This will be displayed within a iframe. } + + /** + * + * @param string|WP_Error $error + */ public function error($error) { if ( is_string($error) && isset( $this->upgrader->strings[$error] ) ) $this->error = $this->upgrader->strings[$error]; @@ -281,6 +313,10 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { $this->feedback('skin_upgrade_end'); } + /** + * + * @param string $title + */ public function before($title = '') { $this->in_loop = true; printf( '

' . $this->upgrader->strings['skin_before_update_header'] . '

', $title, $this->upgrader->update_current, $this->upgrader->update_count); @@ -289,6 +325,10 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { $this->flush_output(); } + /** + * + * @param string $title + */ public function after($title = '') { echo '

'; if ( $this->error || ! $this->result ) { @@ -328,10 +368,18 @@ class Bulk_Plugin_Upgrader_Skin extends Bulk_Upgrader_Skin { $this->upgrader->strings['skin_before_update_header'] = __('Updating Plugin %1$s (%2$d/%3$d)'); } + /** + * + * @param string $title + */ public function before($title = '') { parent::before($this->plugin_info['Title']); } + /** + * + * @param string $title + */ public function after($title = '') { parent::after($this->plugin_info['Title']); $this->decrement_update_count( 'plugin' ); @@ -368,10 +416,18 @@ class Bulk_Theme_Upgrader_Skin extends Bulk_Upgrader_Skin { $this->upgrader->strings['skin_before_update_header'] = __('Updating Theme %1$s (%2$d/%3$d)'); } + /** + * + * @param string $title + */ public function before($title = '') { parent::before( $this->theme_info->display('Name') ); } + /** + * + * @param string $title + */ public function after($title = '') { parent::after( $this->theme_info->display('Name') ); $this->decrement_update_count( 'theme' ); @@ -412,6 +468,10 @@ class Plugin_Installer_Skin extends WP_Upgrader_Skin { public $api; public $type; + /** + * + * @param array $args + */ public function __construct($args = array()) { $defaults = array( 'type' => 'web', 'url' => '', 'plugin' => '', 'nonce' => '', 'title' => '' ); $args = wp_parse_args($args, $defaults); @@ -488,6 +548,10 @@ class Theme_Installer_Skin extends WP_Upgrader_Skin { public $api; public $type; + /** + * + * @param array $args + */ public function __construct($args = array()) { $defaults = array( 'type' => 'web', 'url' => '', 'theme' => '', 'nonce' => '', 'title' => '' ); $args = wp_parse_args($args, $defaults); @@ -572,6 +636,10 @@ class Theme_Installer_Skin extends WP_Upgrader_Skin { class Theme_Upgrader_Skin extends WP_Upgrader_Skin { public $theme = ''; + /** + * + * @param array $args + */ public function __construct($args = array()) { $defaults = array( 'url' => '', 'theme' => '', 'nonce' => '', 'title' => __('Update Theme') ); $args = wp_parse_args($args, $defaults); @@ -649,6 +717,10 @@ class Language_Pack_Upgrader_Skin extends WP_Upgrader_Skin { public $done_footer = false; public $display_footer_actions = true; + /** + * + * @param array $args + */ public function __construct( $args = array() ) { $defaults = array( 'url' => '', 'nonce' => '', 'title' => __( 'Update Translations' ), 'skip_header_footer' => false ); $args = wp_parse_args( $args, $defaults ); @@ -668,6 +740,10 @@ class Language_Pack_Upgrader_Skin extends WP_Upgrader_Skin { printf( '

' . __( 'Updating translations for %1$s (%2$s)…' ) . '

', $name, $this->language_update->language ); } + /** + * + * @param string|WP_Error $error + */ public function error( $error ) { echo '
'; parent::error( $error ); @@ -710,6 +786,13 @@ class Language_Pack_Upgrader_Skin extends WP_Upgrader_Skin { class Automatic_Upgrader_Skin extends WP_Upgrader_Skin { protected $messages = array(); + /** + * + * @param bool $error + * @param string $context + * @param bool $allow_relaxed_file_ownership + * @return bool + */ public function request_filesystem_credentials( $error = false, $context = '', $allow_relaxed_file_ownership = false ) { if ( $context ) { $this->options['context'] = $context; diff --git a/wp-admin/includes/class-wp-upgrader.php b/wp-admin/includes/class-wp-upgrader.php index 1f2b1f740f..0956223808 100644 --- a/wp-admin/includes/class-wp-upgrader.php +++ b/wp-admin/includes/class-wp-upgrader.php @@ -1063,6 +1063,12 @@ class Plugin_Upgrader extends WP_Upgrader { * @since 2.8.0 * * @global WP_Filesystem_Base $wp_filesystem Subclass + * + * @param bool|WP_Error $removed + * @param string $local_destination + * @param string $remote_destination + * @param array $plugin + * @return WP_Error|bool */ public function delete_old_plugin($removed, $local_destination, $remote_destination, $plugin) { global $wp_filesystem; @@ -1166,6 +1172,11 @@ class Theme_Upgrader extends WP_Upgrader { * Hooked to the {@see 'upgrader_post_install'} filter by {@see Theme_Upgrader::install()}. * * @since 3.4.0 + * + * @param bool $install_result + * @param array $hook_extra + * @param array $child_result + * @return type */ public function check_parent_theme_filter( $install_result, $hook_extra, $child_result ) { // Check to see if we need to install a parent theme @@ -1236,6 +1247,7 @@ class Theme_Upgrader extends WP_Upgrader { * @since 3.4.0 * * @param array $actions Preview actions. + * @return array */ public function hide_activate_preview_actions( $actions ) { unset($actions['activate'], $actions['preview']); @@ -1524,9 +1536,12 @@ class Theme_Upgrader extends WP_Upgrader { * {@see Theme_Upgrader::bulk_upgrade()}. * * @since 2.8.0 + * + * @param bool|WP_Error $return + * @param array $theme + * @return bool|WP_Error */ public function current_before($return, $theme) { - if ( is_wp_error($return) ) return $return; @@ -1548,6 +1563,10 @@ class Theme_Upgrader extends WP_Upgrader { * and {@see Theme_Upgrader::bulk_upgrade()}. * * @since 2.8.0 + * + * @param bool|WP_Error $return + * @param array $theme + * @return bool|WP_Error */ public function current_after($return, $theme) { if ( is_wp_error($return) ) @@ -1580,6 +1599,12 @@ class Theme_Upgrader extends WP_Upgrader { * @since 2.8.0 * * @global WP_Filesystem_Base $wp_filesystem Subclass + * + * @param bool $removed + * @param string $local_destination + * @param string $remote_destination + * @param array $theme + * @return bool */ public function delete_old_theme( $removed, $local_destination, $remote_destination, $theme ) { global $wp_filesystem; @@ -1658,6 +1683,8 @@ class Language_Pack_Upgrader extends WP_Upgrader { * @since 3.7.0 * * @static + * + * @param false|WP_Upgrader $upgrader */ public static function async_upgrade( $upgrader = false ) { // Avoid recursion. @@ -1880,6 +1907,9 @@ class Language_Pack_Upgrader extends WP_Upgrader { * @since 3.7.0 * * @global WP_Filesystem_Base $wp_filesystem Subclass + * + * @param string|WP_Error $source + * @param string $remote_source */ public function check_package( $source, $remote_source ) { global $wp_filesystem; @@ -1911,7 +1941,7 @@ class Language_Pack_Upgrader extends WP_Upgrader { * * @since 3.7.0 * - * @param object The data for an update. + * @param object $update The data for an update. * @return string The name of the item being updated. */ public function get_name_for_update( $update ) { @@ -2620,6 +2650,8 @@ class WP_Automatic_Updater { * * @param string $type The type of update being checked: 'core', 'theme', 'plugin', 'translation'. * @param object $item The update offer. + * + * @return null|WP_Error */ public function update( $type, $item ) { $skin = new Automatic_Upgrader_Skin; @@ -2858,7 +2890,7 @@ class WP_Automatic_Updater { * * @global string $wp_version * - * @param object $update_result The result of the core update. Includes the update offer and result. + * @param object|WP_Error $update_result The result of the core update. Includes the update offer and result. */ protected function after_core_update( $update_result ) { global $wp_version; diff --git a/wp-admin/includes/dashboard.php b/wp-admin/includes/dashboard.php index 80255bb6a8..18702b32aa 100644 --- a/wp-admin/includes/dashboard.php +++ b/wp-admin/includes/dashboard.php @@ -168,6 +168,11 @@ function wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_ add_meta_box( $widget_id, $widget_name, $callback, $screen, $location, $priority, $callback_args ); } +/** + * + * @param type $dashboard + * @param type $meta_box + */ function _wp_dashboard_control_callback( $dashboard, $meta_box ) { echo '
'; wp_dashboard_trigger_widget_control( $meta_box['id'] ); @@ -495,6 +500,8 @@ function wp_dashboard_quick_press( $error_msg = false ) { * Show recent drafts of the user on the dashboard. * * @since 2.7.0 + * + * @param array $drafts */ function wp_dashboard_recent_drafts( $drafts = false ) { if ( ! $drafts ) { diff --git a/wp-admin/includes/export.php b/wp-admin/includes/export.php index a826c7d394..4ddc210609 100644 --- a/wp-admin/includes/export.php +++ b/wp-admin/includes/export.php @@ -315,6 +315,12 @@ function export_wp( $args = array() ) { } } + /** + * + * @param bool $return_me + * @param string $meta_key + * @return boolean + */ function wxr_filter_postmeta( $return_me, $meta_key ) { if ( '_edit_lock' == $meta_key ) $return_me = true; diff --git a/wp-admin/includes/import.php b/wp-admin/includes/import.php index f1e2035a8a..8b6737437a 100644 --- a/wp-admin/includes/import.php +++ b/wp-admin/includes/import.php @@ -45,10 +45,10 @@ function _usort_by_first_member( $a, $b ) { * * @global array $wp_importers * - * @param string $id Importer tag. Used to uniquely identify importer. - * @param string $name Importer name and title. - * @param string $description Importer description. - * @param callback $callback Callback to run. + * @param string $id Importer tag. Used to uniquely identify importer. + * @param string $name Importer name and title. + * @param string $description Importer description. + * @param callback $callback Callback to run. * @return WP_Error Returns WP_Error when $callback is WP_Error. */ function register_importer( $id, $name, $description, $callback ) { diff --git a/wp-admin/includes/menu.php b/wp-admin/includes/menu.php index 16b03b2434..f0e6d8662b 100644 --- a/wp-admin/includes/menu.php +++ b/wp-admin/includes/menu.php @@ -194,13 +194,23 @@ foreach ( $menu as $id => $data ) { } unset($id, $data); +/** + * + * @param string $add + * @param string $class + * @return string + */ function add_cssclass($add, $class) { $class = empty($class) ? $add : $class .= ' ' . $add; return $class; } +/** + * + * @param array $menu + * @return array + */ function add_menu_classes($menu) { - $first = $lastorder = false; $i = 0; $mc = count($menu); diff --git a/wp-admin/includes/nav-menu.php b/wp-admin/includes/nav-menu.php index 78ef95f3a6..7fbf799ee6 100644 --- a/wp-admin/includes/nav-menu.php +++ b/wp-admin/includes/nav-menu.php @@ -237,6 +237,10 @@ class Walker_Nav_Menu_Edit extends Walker_Nav_Menu { * @uses Walker_Nav_Menu */ class Walker_Nav_Menu_Checklist extends Walker_Nav_Menu { + /** + * + * @param array $fields + */ public function __construct( $fields = false ) { if ( $fields ) { $this->db_fields = $fields; diff --git a/wp-admin/includes/plugin-install.php b/wp-admin/includes/plugin-install.php index f27acf2c23..21f7176f96 100644 --- a/wp-admin/includes/plugin-install.php +++ b/wp-admin/includes/plugin-install.php @@ -163,6 +163,8 @@ function install_dashboard() { * Display search form for searching plugins. * * @since 2.7.0 + * + * @param bool $type_selector */ function install_search_form( $type_selector = true ) { $type = isset($_REQUEST['type']) ? wp_unslash( $_REQUEST['type'] ) : 'term'; @@ -261,6 +263,10 @@ function display_plugins_table() { * Determine the status we can perform on a plugin. * * @since 3.0.0 + * + * @param array|object $api + * @param bool $loop + * @return type */ function install_plugin_install_status($api, $loop = false) { // This function is called recursively, $loop prevents further loops. diff --git a/wp-admin/includes/screen.php b/wp-admin/includes/screen.php index 2d836e9358..582c659ed1 100644 --- a/wp-admin/includes/screen.php +++ b/wp-admin/includes/screen.php @@ -185,7 +185,7 @@ function get_current_screen() { * @since 3.0.0 * * @param mixed $hook_name Optional. The hook name (also known as the hook suffix) used to determine the screen, - * or an existing screen object. + * or an existing screen object. */ function set_current_screen( $hook_name = '' ) { WP_Screen::get( $hook_name )->set_current_screen(); @@ -387,11 +387,10 @@ final class WP_Screen { * @global string $hook_suffix * * @param string|WP_Screen $hook_name Optional. The hook name (also known as the hook suffix) used to determine the screen. - * Defaults to the current $hook_suffix global. + * Defaults to the current $hook_suffix global. * @return WP_Screen Screen object. */ public static function get( $hook_name = '' ) { - if ( $hook_name instanceof WP_Screen ) { return $hook_name; } @@ -582,9 +581,8 @@ final class WP_Screen { * @since 3.5.0 * * @param string $admin The admin to check against (network | user | site). - * If empty any of the three admins will result in true. - * @return boolean True if the screen is in the indicated admin, false otherwise. - * + * If empty any of the three admins will result in true. + * @return bool True if the screen is in the indicated admin, false otherwise. */ public function in_admin( $admin = null ) { if ( empty( $admin ) ) diff --git a/wp-includes/version.php b/wp-includes/version.php index 58d1fe2a34..0db0f358cf 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -4,7 +4,7 @@ * * @global string $wp_version */ -$wp_version = '4.3-alpha-32654'; +$wp_version = '4.3-alpha-32655'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.