Changeset 59861

Timestamp:

02/23/2025 11:09:25 AM (8 months ago)

Author:

johnbillion

Message:

Docs: Various improvements to inline documentation.

See #62281

Location:

trunk/src

Files:

• wp-admin/includes/class-wp-upgrader.php (modified) (1 diff)
• wp-admin/includes/update-core.php (modified) (8 diffs)
• wp-admin/includes/update.php (modified) (2 diffs)
• wp-admin/includes/upgrade.php (modified) (1 diff)
• wp-includes/class-wp-recovery-mode.php (modified) (1 diff)
• wp-includes/class-wp-theme.php (modified) (1 diff)
• wp-includes/theme.php (modified) (9 diffs)
• wp-includes/update.php (modified) (3 diffs)

trunk/src/wp-admin/includes/class-wp-upgrader.php

@@ -487 +487 @@
      *
      * @global WP_Filesystem_Base $wp_filesystem        WordPress filesystem subclass.
-     * @global array              $wp_theme_directories
+     * @global string[]           $wp_theme_directories
      *
      * @param array|string $args {

trunk/src/wp-admin/includes/update-core.php

@@ -19 +19 @@
  * @since 2.7.0
  *
- * @global array $_old_files
- * @var array
+ * @global string[] $_old_files
+ * @var string[]
  * @name $_old_files
  */
@@ -841 +841 @@
  * @since 6.2.0
  *
- * @global array $_old_requests_files
- * @var array
+ * @global string[] $_old_requests_files
+ * @var string[]
  * @name $_old_requests_files
  */
@@ -938 +938 @@
  *              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
  */
@@ -978 +978 @@
  * 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.
@@ -1006 +1007 @@
  *
  * @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.
  *
@@ -1604 +1605 @@
  * @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.
@@ -1716 +1717 @@
  * @since 4.2.2
  *
- * @global array              $wp_theme_directories
+ * @global string[]           $wp_theme_directories
  * @global WP_Filesystem_Base $wp_filesystem
  */
@@ -1762 +1763 @@
  *
  * @param string $directory Directory path. Expects trailingslashed.
- * @return array
+ * @return string[]
  */
 function _upgrade_422_find_genericons_files_in_folder( $directory ) {

trunk/src/wp-admin/includes/update.php

@@ -402 +402 @@
  * @since 2.9.0
  *
- * @return array
+ * @return object[]
  */
 function get_plugin_updates() {
@@ -625 +625 @@
  * @since 2.9.0
  *
- * @return array
+ * @return WP_Theme[]
  */
 function get_theme_updates() {

trunk/src/wp-admin/includes/upgrade.php

@@ -2861 +2861 @@
  * @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

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

@@ -339 +339 @@
      * @since 5.2.0
      *
-     * @global array $wp_theme_directories
+     * @global string[] $wp_theme_directories
      *
      * @param array $error Error details from `error_get_last()`.

trunk/src/wp-includes/class-wp-theme.php

@@ -243 +243 @@
      * @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.

trunk/src/wp-includes/theme.php

@@ -15 +15 @@
  * @since 3.4.0
  *
- * @global array $wp_theme_directories
+ * @global string[] $wp_theme_directories
  *
  * @param array $args {
@@ -106 +106 @@
  * @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.
@@ -381 +381 @@
  * @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
@@ -406 +406 @@
  * @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
@@ -442 +442 @@
  * @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.
@@ -592 +592 @@
  * @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.
@@ -637 +637 @@
  * @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.
@@ -688 +688 @@
  * @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.
@@ -751 +751 @@
  * @since 2.5.0
  *
- * @global array                $wp_theme_directories
+ * @global string[]             $wp_theme_directories
  * @global WP_Customize_Manager $wp_customize
  * @global array                $sidebars_widgets

trunk/src/wp-includes/update.php

@@ -489 +489 @@
          *     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.
          *
@@ -975 +975 @@
      *     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.
      * }
@@ -987 +987 @@
  *
  * @since 2.8.0
- *
- * @global string $wp_version The WordPress version string.
  */
 function _maybe_update_core() {