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

@@ -486,7 +486,7 @@ class WP_Upgrader {
 	 * @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.

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 @@ $_old_files = array(
  *
  * @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 @@ $_old_requests_files = array(
  *              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 @@ $_new_bundled_files = array(
  *
  * 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 @@ $_new_bundled_files = array(
  * @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 @@ window.location = 'about.php?updated';
  *
  * @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 );

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' );

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;

src/wp-includes/class-wp-recovery-mode.php

@@ -338,7 +338,7 @@ class WP_Recovery_Mode {
 	 *
 	 * @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 {

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.

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

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' );