From fc96319aa770050d22cfdc1bbab437154017bcf7 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Sun, 23 Feb 2025 11:09:25 +0000 Subject: [PATCH] Docs: Various improvements to inline documentation. See #62281 git-svn-id: https://develop.svn.wordpress.org/trunk@59861 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-admin/includes/class-wp-upgrader.php | 2 +- src/wp-admin/includes/update-core.php | 31 +++++++++++---------- src/wp-admin/includes/update.php | 4 +-- src/wp-admin/includes/upgrade.php | 2 +- src/wp-includes/class-wp-recovery-mode.php | 2 +- src/wp-includes/class-wp-theme.php | 2 +- src/wp-includes/theme.php | 18 ++++++------ src/wp-includes/update.php | 30 ++++++++++---------- 8 files changed, 45 insertions(+), 46 deletions(-) diff --git a/src/wp-admin/includes/class-wp-upgrader.php b/src/wp-admin/includes/class-wp-upgrader.php index c47773569fc17..6c6cb5d828728 100644 --- a/src/wp-admin/includes/class-wp-upgrader.php +++ b/src/wp-admin/includes/class-wp-upgrader.php @@ -486,7 +486,7 @@ public function clear_destination( $remote_destination ) { * @since 6.2.0 Use move_dir() instead of copy_dir() when possible. * * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass. - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * * @param array|string $args { * Optional. Array or string of arguments for installing a package. Default empty array. diff --git a/src/wp-admin/includes/update-core.php b/src/wp-admin/includes/update-core.php index 941e5e1b25b0d..2c05d1618802d 100644 --- a/src/wp-admin/includes/update-core.php +++ b/src/wp-admin/includes/update-core.php @@ -18,8 +18,8 @@ * * @since 2.7.0 * - * @global array $_old_files - * @var array + * @global string[] $_old_files + * @var string[] * @name $_old_files */ global $_old_files; @@ -840,8 +840,8 @@ * * @since 6.2.0 * - * @global array $_old_requests_files - * @var array + * @global string[] $_old_requests_files + * @var string[] * @name $_old_requests_files */ global $_old_requests_files; @@ -937,8 +937,8 @@ * upgrade. New themes are now installed again. To disable new * themes from being installed on upgrade, explicitly define * CORE_UPGRADE_SKIP_NEW_BUNDLED as true. - * @global array $_new_bundled_files - * @var array + * @global string[] $_new_bundled_files + * @var string[] * @name $_new_bundled_files */ global $_new_bundled_files; @@ -977,13 +977,14 @@ * * The steps for the upgrader for after the new release is downloaded and * unzipped is: + * * 1. Test unzipped location for select files to ensure that unzipped worked. * 2. Create the .maintenance file in current WordPress base. * 3. Copy new WordPress directory over old WordPress files. * 4. Upgrade WordPress to new version. - * 4.1. Copy all files/folders other than wp-content - * 4.2. Copy any language files to WP_LANG_DIR (which may differ from WP_CONTENT_DIR - * 4.3. Copy any new bundled themes/plugins to their respective locations + * 1. Copy all files/folders other than wp-content + * 2. Copy any language files to `WP_LANG_DIR` (which may differ from `WP_CONTENT_DIR` + * 3. Copy any new bundled themes/plugins to their respective locations * 5. Delete new WordPress directory path. * 6. Delete .maintenance file. * 7. Remove old files. @@ -1005,9 +1006,9 @@ * @since 2.7.0 * * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass. - * @global array $_old_files - * @global array $_old_requests_files - * @global array $_new_bundled_files + * @global string[] $_old_files + * @global string[] $_old_requests_files + * @global string[] $_new_bundled_files * @global wpdb $wpdb WordPress database abstraction object. * * @param string $from New release unzipped path. @@ -1603,7 +1604,7 @@ function update_core( $from, $to ) { * * @since 6.2.0 * - * @global array $_old_requests_files Requests files to be preloaded. + * @global string[] $_old_requests_files Requests files to be preloaded. * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass. * @global string $wp_version The WordPress version string. * @@ -1715,7 +1716,7 @@ function _redirect_to_about_wordpress( $new_version ) { * * @since 4.2.2 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * @global WP_Filesystem_Base $wp_filesystem */ function _upgrade_422_remove_genericons() { @@ -1761,7 +1762,7 @@ function _upgrade_422_remove_genericons() { * @since 4.2.2 * * @param string $directory Directory path. Expects trailingslashed. - * @return array + * @return string[] */ function _upgrade_422_find_genericons_files_in_folder( $directory ) { $directory = trailingslashit( $directory ); diff --git a/src/wp-admin/includes/update.php b/src/wp-admin/includes/update.php index 629c1be1cc639..33325236e3414 100644 --- a/src/wp-admin/includes/update.php +++ b/src/wp-admin/includes/update.php @@ -401,7 +401,7 @@ function update_right_now_message() { * * @since 2.9.0 * - * @return array + * @return object[] */ function get_plugin_updates() { $all_plugins = get_plugins(); @@ -624,7 +624,7 @@ function wp_plugin_update_row( $file, $plugin_data ) { * * @since 2.9.0 * - * @return array + * @return WP_Theme[] */ function get_theme_updates() { $current = get_site_transient( 'update_themes' ); diff --git a/src/wp-admin/includes/upgrade.php b/src/wp-admin/includes/upgrade.php index d05bf15a4836e..138d5d9bbb263 100644 --- a/src/wp-admin/includes/upgrade.php +++ b/src/wp-admin/includes/upgrade.php @@ -2860,7 +2860,7 @@ function deslash( $content ) { * semicolons. Default empty string. * @param bool $execute Optional. Whether or not to execute the query right away. * Default true. - * @return array Strings containing the results of the various update queries. + * @return string[] Strings containing the results of the various update queries. */ function dbDelta( $queries = '', $execute = true ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid global $wpdb; diff --git a/src/wp-includes/class-wp-recovery-mode.php b/src/wp-includes/class-wp-recovery-mode.php index afed07b3a70c1..7d1af1164185e 100644 --- a/src/wp-includes/class-wp-recovery-mode.php +++ b/src/wp-includes/class-wp-recovery-mode.php @@ -338,7 +338,7 @@ protected function get_link_ttl() { * * @since 5.2.0 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * * @param array $error Error details from `error_get_last()`. * @return array|false { diff --git a/src/wp-includes/class-wp-theme.php b/src/wp-includes/class-wp-theme.php index cac1f6a410ef5..dd9dfde5dad80 100644 --- a/src/wp-includes/class-wp-theme.php +++ b/src/wp-includes/class-wp-theme.php @@ -242,7 +242,7 @@ final class WP_Theme implements ArrayAccess { * * @since 3.4.0 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * * @param string $theme_dir Directory of the theme within the theme_root. * @param string $theme_root Theme root. diff --git a/src/wp-includes/theme.php b/src/wp-includes/theme.php index 66867cfa4490b..0a3f7c5d65649 100644 --- a/src/wp-includes/theme.php +++ b/src/wp-includes/theme.php @@ -14,7 +14,7 @@ * * @since 3.4.0 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * * @param array $args { * Optional. The search arguments. @@ -105,7 +105,7 @@ function wp_get_themes( $args = array() ) { * * @since 3.4.0 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * * @param string $stylesheet Optional. Directory name for the theme. Defaults to active theme. * @param string $theme_root Optional. Absolute path of the theme root to look in. @@ -380,7 +380,7 @@ function get_template_directory_uri() { * * @since 2.9.0 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * * @return array|string An array of theme roots keyed by template/stylesheet * or a single theme root if all themes have the same root. @@ -405,7 +405,7 @@ function get_theme_roots() { * * @since 2.9.0 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * * @param string $directory Either the full filesystem path to a theme folder * or a folder within WP_CONTENT_DIR. @@ -441,7 +441,7 @@ function register_theme_directory( $directory ) { * * @since 2.9.0 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * * @param bool $force Optional. Whether to force a new directory scan. Default false. * @return array|false Valid themes found on success, false on failure. @@ -591,7 +591,7 @@ function search_theme_directories( $force = false ) { * * @since 1.5.0 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * * @param string $stylesheet_or_template Optional. The stylesheet or template name of the theme. * Default is to leverage the main theme root. @@ -636,7 +636,7 @@ function get_theme_root( $stylesheet_or_template = '' ) { * * @since 1.5.0 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * * @param string $stylesheet_or_template Optional. The stylesheet or template name of the theme. * Default is to leverage the main theme root. @@ -687,7 +687,7 @@ function get_theme_root_uri( $stylesheet_or_template = '', $theme_root = '' ) { * * @since 3.1.0 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * * @param string $stylesheet_or_template The stylesheet or template name of the theme. * @param bool $skip_cache Optional. Whether to skip the cache. @@ -750,7 +750,7 @@ function locale_stylesheet() { * * @since 2.5.0 * - * @global array $wp_theme_directories + * @global string[] $wp_theme_directories * @global WP_Customize_Manager $wp_customize * @global array $sidebars_widgets * @global array $wp_registered_sidebars diff --git a/src/wp-includes/update.php b/src/wp-includes/update.php index 8dba379ad31de..441305007152b 100644 --- a/src/wp-includes/update.php +++ b/src/wp-includes/update.php @@ -488,19 +488,19 @@ function wp_update_plugins( $extra_stats = array() ) { * @param array|false $update { * The plugin update data with the latest details. Default false. * - * @type string $id Optional. ID of the plugin for update purposes, should be a URI - * specified in the `Update URI` header field. - * @type string $slug Slug of the plugin. - * @type string $version The version of the plugin. - * @type string $url The URL for details of the plugin. - * @type string $package Optional. The update ZIP for the plugin. - * @type string $tested Optional. The version of WordPress the plugin is tested against. - * @type string $requires_php Optional. The version of PHP which the plugin requires. - * @type bool $autoupdate Optional. Whether the plugin should automatically update. - * @type array $icons Optional. Array of plugin icons. - * @type array $banners Optional. Array of plugin banners. - * @type array $banners_rtl Optional. Array of plugin RTL banners. - * @type array $translations { + * @type string $id Optional. ID of the plugin for update purposes, should be a URI + * specified in the `Update URI` header field. + * @type string $slug Slug of the plugin. + * @type string $version The version of the plugin. + * @type string $url The URL for details of the plugin. + * @type string $package Optional. The update ZIP for the plugin. + * @type string $tested Optional. The version of WordPress the plugin is tested against. + * @type string $requires_php Optional. The version of PHP which the plugin requires. + * @type bool $autoupdate Optional. Whether the plugin should automatically update. + * @type string[] $icons Optional. Array of plugin icons. + * @type string[] $banners Optional. Array of plugin banners. + * @type string[] $banners_rtl Optional. Array of plugin RTL banners. + * @type array $translations { * Optional. List of translation updates for the plugin. * * @type string $language The language the translation update is for. @@ -974,7 +974,7 @@ function wp_get_update_data() { * @param array $update_data { * Fetched update data. * - * @type array $counts An array of counts for available plugin, theme, and WordPress updates. + * @type int[] $counts An array of counts for available plugin, theme, and WordPress updates. * @type string $update_title Titles of available updates. * } * @param array $titles An array of update counts and UI strings for available updates. @@ -986,8 +986,6 @@ function wp_get_update_data() { * Determines whether core should be updated. * * @since 2.8.0 - * - * @global string $wp_version The WordPress version string. */ function _maybe_update_core() { $current = get_site_transient( 'update_core' );