From 137f90ef4942c3f92467493c61de9559e48b61e0 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Thu, 2 May 2024 17:20:10 +0000 Subject: [PATCH] Docs: Add missing documentation for various upgrade/install class methods. Follow-up to [13602], [13686], [14879], [25806], [28495], [32655], [48661], [53952]. Props yagniksangani, audrasjb, SergeyBiryukov. Fixes #61124. Built from https://develop.svn.wordpress.org/trunk@58082 git-svn-id: http://core.svn.wordpress.org/trunk@57547 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- .../class-bulk-plugin-upgrader-skin.php | 17 ++++++ .../class-bulk-theme-upgrader-skin.php | 17 ++++++ .../includes/class-bulk-upgrader-skin.php | 54 ++++++++++++++++++- .../class-language-pack-upgrader-skin.php | 18 +++++++ .../includes/class-plugin-installer-skin.php | 6 +++ .../includes/class-theme-installer-skin.php | 6 +++ wp-admin/includes/class-wp-upgrader-skin.php | 23 +++++--- wp-includes/version.php | 2 +- 8 files changed, 135 insertions(+), 8 deletions(-) diff --git a/wp-admin/includes/class-bulk-plugin-upgrader-skin.php b/wp-admin/includes/class-bulk-plugin-upgrader-skin.php index 7cbf334ee2..bb62928fa6 100644 --- a/wp-admin/includes/class-bulk-plugin-upgrader-skin.php +++ b/wp-admin/includes/class-bulk-plugin-upgrader-skin.php @@ -23,10 +23,16 @@ class Bulk_Plugin_Upgrader_Skin extends Bulk_Upgrader_Skin { * The Plugin_Upgrader::bulk_upgrade() method will fill this in * with info retrieved from the get_plugin_data() function. * + * @since 3.0.0 * @var array Plugin data. Values will be empty if not supplied by the plugin. */ public $plugin_info = array(); + /** + * Sets up the strings used in the update process. + * + * @since 3.0.0 + */ public function add_strings() { parent::add_strings(); /* translators: 1: Plugin name, 2: Number of the plugin, 3: Total number of plugins being updated. */ @@ -34,6 +40,10 @@ class Bulk_Plugin_Upgrader_Skin extends Bulk_Upgrader_Skin { } /** + * Performs an action before a bulk plugin update. + * + * @since 3.0.0 + * * @param string $title */ public function before( $title = '' ) { @@ -41,6 +51,10 @@ class Bulk_Plugin_Upgrader_Skin extends Bulk_Upgrader_Skin { } /** + * Performs an action following a bulk plugin update. + * + * @since 3.0.0 + * * @param string $title */ public function after( $title = '' ) { @@ -49,6 +63,9 @@ class Bulk_Plugin_Upgrader_Skin extends Bulk_Upgrader_Skin { } /** + * Displays the footer following the bulk update process. + * + * @since 3.0.0 */ public function bulk_footer() { parent::bulk_footer(); diff --git a/wp-admin/includes/class-bulk-theme-upgrader-skin.php b/wp-admin/includes/class-bulk-theme-upgrader-skin.php index 8ec3bbf5f5..f2b9b95025 100644 --- a/wp-admin/includes/class-bulk-theme-upgrader-skin.php +++ b/wp-admin/includes/class-bulk-theme-upgrader-skin.php @@ -24,10 +24,16 @@ class Bulk_Theme_Upgrader_Skin extends Bulk_Upgrader_Skin { * with info retrieved from the Theme_Upgrader::theme_info() method, * which in turn calls the wp_get_theme() function. * + * @since 3.0.0 * @var WP_Theme|false The theme's info object, or false. */ public $theme_info = false; + /** + * Sets up the strings used in the update process. + * + * @since 3.0.0 + */ public function add_strings() { parent::add_strings(); /* translators: 1: Theme name, 2: Number of the theme, 3: Total number of themes being updated. */ @@ -35,6 +41,10 @@ class Bulk_Theme_Upgrader_Skin extends Bulk_Upgrader_Skin { } /** + * Performs an action before a bulk theme update. + * + * @since 3.0.0 + * * @param string $title */ public function before( $title = '' ) { @@ -42,6 +52,10 @@ class Bulk_Theme_Upgrader_Skin extends Bulk_Upgrader_Skin { } /** + * Performs an action following a bulk theme update. + * + * @since 3.0.0 + * * @param string $title */ public function after( $title = '' ) { @@ -50,6 +64,9 @@ class Bulk_Theme_Upgrader_Skin extends Bulk_Upgrader_Skin { } /** + * Displays the footer following the bulk update process. + * + * @since 3.0.0 */ public function bulk_footer() { parent::bulk_footer(); diff --git a/wp-admin/includes/class-bulk-upgrader-skin.php b/wp-admin/includes/class-bulk-upgrader-skin.php index 461311962d..5cdd2a56ce 100644 --- a/wp-admin/includes/class-bulk-upgrader-skin.php +++ b/wp-admin/includes/class-bulk-upgrader-skin.php @@ -16,13 +16,30 @@ * @see WP_Upgrader_Skin */ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { - public $in_loop = false; + /** + * Whether the bulk update process has started. + * + * @since 3.0.0 + * @var bool + */ + public $in_loop = false; + + /** + * Stores an error message about the update. + * + * @since 3.0.0 * @var string|false */ public $error = false; /** + * Constructor. + * + * Sets up the generic skin for the Bulk Upgrader classes. + * + * @since 3.0.0 + * * @param array $args */ public function __construct( $args = array() ) { @@ -36,6 +53,9 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { } /** + * Sets up the strings used in the update process. + * + * @since 3.0.0 */ public function add_strings() { $this->upgrader->strings['skin_upgrade_start'] = __( 'The update process is starting. This process may take a while on some hosts, so please be patient.' ); @@ -49,6 +69,9 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { } /** + * Displays a message about the update. + * + * @since 3.0.0 * @since 5.9.0 Renamed `$string` (a PHP reserved keyword) to `$feedback` for PHP 8 named parameter support. * * @param string $feedback Message data. @@ -77,18 +100,27 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { } /** + * Displays the header before the update process. + * + * @since 3.0.0 */ public function header() { // Nothing. This will be displayed within an iframe. } /** + * Displays the footer following the update process. + * + * @since 3.0.0 */ public function footer() { // Nothing. This will be displayed within an iframe. } /** + * Displays an error message about the update. + * + * @since 3.0.0 * @since 5.9.0 Renamed `$error` to `$errors` for PHP 8 named parameter support. * * @param string|WP_Error $errors Errors. @@ -113,18 +145,28 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { } /** + * Displays the header before the bulk update process. + * + * @since 3.0.0 */ public function bulk_header() { $this->feedback( 'skin_upgrade_start' ); } /** + * Displays the footer following the bulk update process. + * + * @since 3.0.0 */ public function bulk_footer() { $this->feedback( 'skin_upgrade_end' ); } /** + * Performs an action before a bulk update. + * + * @since 3.0.0 + * * @param string $title */ public function before( $title = '' ) { @@ -137,6 +179,10 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { } /** + * Performs an action following a bulk update. + * + * @since 3.0.0 + * * @param string $title */ public function after( $title = '' ) { @@ -172,6 +218,9 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { } /** + * Resets the properties used in the update process. + * + * @since 3.0.0 */ public function reset() { $this->in_loop = false; @@ -179,6 +228,9 @@ class Bulk_Upgrader_Skin extends WP_Upgrader_Skin { } /** + * Flushes all output buffers. + * + * @since 3.0.0 */ public function flush_output() { wp_ob_end_flush_all(); diff --git a/wp-admin/includes/class-language-pack-upgrader-skin.php b/wp-admin/includes/class-language-pack-upgrader-skin.php index 57b0a1c376..b93ed6c8bc 100644 --- a/wp-admin/includes/class-language-pack-upgrader-skin.php +++ b/wp-admin/includes/class-language-pack-upgrader-skin.php @@ -22,6 +22,12 @@ class Language_Pack_Upgrader_Skin extends WP_Upgrader_Skin { public $display_footer_actions = true; /** + * Constructor. + * + * Sets up the language pack upgrader skin. + * + * @since 3.7.0 + * * @param array $args */ public function __construct( $args = array() ) { @@ -41,6 +47,9 @@ class Language_Pack_Upgrader_Skin extends WP_Upgrader_Skin { } /** + * Performs an action before a language pack update. + * + * @since 3.7.0 */ public function before() { $name = $this->upgrader->get_name_for_update( $this->language_update ); @@ -52,6 +61,9 @@ class Language_Pack_Upgrader_Skin extends WP_Upgrader_Skin { } /** + * Displays an error message about the update. + * + * @since 3.7.0 * @since 5.9.0 Renamed `$error` to `$errors` for PHP 8 named parameter support. * * @param string|WP_Error $errors Errors. @@ -63,12 +75,18 @@ class Language_Pack_Upgrader_Skin extends WP_Upgrader_Skin { } /** + * Performs an action following a language pack update. + * + * @since 3.7.0 */ public function after() { echo ''; } /** + * Displays the footer following the bulk update process. + * + * @since 3.7.0 */ public function bulk_footer() { $this->decrement_update_count( 'translation' ); diff --git a/wp-admin/includes/class-plugin-installer-skin.php b/wp-admin/includes/class-plugin-installer-skin.php index 9fa033a95f..d8e7e3e8cb 100644 --- a/wp-admin/includes/class-plugin-installer-skin.php +++ b/wp-admin/includes/class-plugin-installer-skin.php @@ -24,6 +24,12 @@ class Plugin_Installer_Skin extends WP_Upgrader_Skin { private $is_downgrading = false; /** + * Constructor. + * + * Sets up the plugin installer skin. + * + * @since 2.8.0 + * * @param array $args */ public function __construct( $args = array() ) { diff --git a/wp-admin/includes/class-theme-installer-skin.php b/wp-admin/includes/class-theme-installer-skin.php index 93c626c617..85f87977b2 100644 --- a/wp-admin/includes/class-theme-installer-skin.php +++ b/wp-admin/includes/class-theme-installer-skin.php @@ -24,6 +24,12 @@ class Theme_Installer_Skin extends WP_Upgrader_Skin { private $is_downgrading = false; /** + * Constructor. + * + * Sets up the theme installer skin. + * + * @since 2.8.0 + * * @param array $args */ public function __construct( $args = array() ) { diff --git a/wp-admin/includes/class-wp-upgrader-skin.php b/wp-admin/includes/class-wp-upgrader-skin.php index 83b4ba472e..a5c80fad6d 100644 --- a/wp-admin/includes/class-wp-upgrader-skin.php +++ b/wp-admin/includes/class-wp-upgrader-skin.php @@ -20,7 +20,6 @@ class WP_Upgrader_Skin { * Holds the upgrader data. * * @since 2.8.0 - * * @var WP_Upgrader */ public $upgrader; @@ -29,7 +28,6 @@ class WP_Upgrader_Skin { * Whether header is done. * * @since 2.8.0 - * * @var bool */ public $done_header = false; @@ -38,7 +36,6 @@ class WP_Upgrader_Skin { * Whether footer is done. * * @since 2.8.0 - * * @var bool */ public $done_footer = false; @@ -47,7 +44,6 @@ class WP_Upgrader_Skin { * Holds the result of an upgrade. * * @since 2.8.0 - * * @var string|bool|WP_Error */ public $result = false; @@ -56,7 +52,6 @@ class WP_Upgrader_Skin { * Holds the options of an upgrade. * * @since 2.8.0 - * * @var array */ public $options = array(); @@ -82,6 +77,8 @@ class WP_Upgrader_Skin { } /** + * Sets the relationship between the skin being used and the upgrader. + * * @since 2.8.0 * * @param WP_Upgrader $upgrader @@ -94,6 +91,8 @@ class WP_Upgrader_Skin { } /** + * Sets up the strings used in the update process. + * * @since 3.0.0 */ public function add_strings() { @@ -141,6 +140,8 @@ class WP_Upgrader_Skin { } /** + * Displays the header before the update process. + * * @since 2.8.0 */ public function header() { @@ -153,6 +154,8 @@ class WP_Upgrader_Skin { } /** + * Displays the footer following the update process. + * * @since 2.8.0 */ public function footer() { @@ -164,6 +167,8 @@ class WP_Upgrader_Skin { } /** + * Displays an error message about the update. + * * @since 2.8.0 * * @param string|WP_Error $errors Errors. @@ -186,6 +191,8 @@ class WP_Upgrader_Skin { } /** + * Displays a message about the update. + * * @since 2.8.0 * @since 5.9.0 Renamed `$string` (a PHP reserved keyword) to `$feedback` for PHP 8 named parameter support. * @@ -218,7 +225,7 @@ class WP_Upgrader_Skin { public function before() {} /** - * Performs and action following an update. + * Performs an action following an update. * * @since 2.8.0 */ @@ -262,11 +269,15 @@ class WP_Upgrader_Skin { } /** + * Displays the header before the bulk update process. + * * @since 3.0.0 */ public function bulk_header() {} /** + * Displays the footer following the bulk update process. + * * @since 3.0.0 */ public function bulk_footer() {} diff --git a/wp-includes/version.php b/wp-includes/version.php index df24622a9f..7a4e68fc97 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.6-alpha-58081'; +$wp_version = '6.6-alpha-58082'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.