From 270a3d009dd0c27241f991452aced9286f77be40 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 7 Feb 2023 21:21:18 +0000 Subject: [PATCH] Docs: Miscellaneous improvements and corrections to docblocks. See #56792 Built from https://develop.svn.wordpress.org/trunk@55293 git-svn-id: http://core.svn.wordpress.org/trunk@54826 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/class-wp-list-table.php | 2 +- wp-admin/includes/class-wp-screen.php | 4 ++-- wp-admin/includes/nav-menu.php | 4 ++-- wp-includes/cron.php | 20 +++++++++++++------ wp-includes/rest-api.php | 17 ++++++++++------ .../class-wp-rest-search-controller.php | 2 +- .../search/class-wp-rest-search-handler.php | 4 ++-- wp-includes/version.php | 2 +- 8 files changed, 34 insertions(+), 21 deletions(-) diff --git a/wp-admin/includes/class-wp-list-table.php b/wp-admin/includes/class-wp-list-table.php index 104bd446ab..9ecbe37487 100644 --- a/wp-admin/includes/class-wp-list-table.php +++ b/wp-admin/includes/class-wp-list-table.php @@ -387,7 +387,7 @@ class WP_List_Table { * @type string $label The link label. * @type bool $current Optional. Whether this is the currently selected view. * } - * @return array An array of link markup. Keys match the `$link_data` input array. + * @return string[] An array of link markup. Keys match the `$link_data` input array. */ protected function get_views_links( $link_data = array() ) { if ( ! is_array( $link_data ) ) { diff --git a/wp-admin/includes/class-wp-screen.php b/wp-admin/includes/class-wp-screen.php index 73f6275fe6..1d3e8d7fe2 100644 --- a/wp-admin/includes/class-wp-screen.php +++ b/wp-admin/includes/class-wp-screen.php @@ -144,7 +144,7 @@ final class WP_Screen { * The accessible hidden headings and text associated with the screen, if any. * * @since 4.4.0 - * @var array + * @var string[] */ private $_screen_reader_content = array(); @@ -721,7 +721,7 @@ final class WP_Screen { * * @see set_screen_reader_content() For more information on the array format. * - * @return array An associative array of screen reader text strings. + * @return string[] An associative array of screen reader text strings. */ public function get_screen_reader_content() { return $this->_screen_reader_content; diff --git a/wp-admin/includes/nav-menu.php b/wp-admin/includes/nav-menu.php index 7d90f956a1..20a2d0be86 100644 --- a/wp-admin/includes/nav-menu.php +++ b/wp-admin/includes/nav-menu.php @@ -1152,13 +1152,13 @@ function _wp_delete_orphaned_draft_menu_items() { } /** - * Saves nav menu items + * Saves nav menu items. * * @since 3.6.0 * * @param int|string $nav_menu_selected_id ID, slug, or name of the currently-selected menu. * @param string $nav_menu_selected_title Title of the currently-selected menu. - * @return array The menu updated message + * @return string[] The menu updated messages. */ function wp_nav_menu_update_menu_items( $nav_menu_selected_id, $nav_menu_selected_title ) { $unsorted_menu_items = wp_get_nav_menu_items( diff --git a/wp-includes/cron.php b/wp-includes/cron.php index 9903846dd9..8f716fe90e 100644 --- a/wp-includes/cron.php +++ b/wp-includes/cron.php @@ -77,14 +77,14 @@ function wp_schedule_single_event( $timestamp, $hook, $args = array(), $wp_error * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned. * * @param null|bool|WP_Error $result The value to return instead. Default null to continue adding the event. - * @param stdClass $event { + * @param object $event { * An object containing an event's data. * * @type string $hook Action hook to execute when the event is run. * @type int $timestamp Unix timestamp (UTC) for when to next run the event. * @type string|false $schedule How often the event should subsequently recur. * @type array $args Array containing each separate argument to pass to the hook's callback function. - * @type int $interval The interval time in seconds for the schedule. Only present for recurring events. + * @type int $interval Optional. The interval time in seconds for the schedule. Only present for recurring events. * } * @param bool $wp_error Whether to return a WP_Error on failure. */ @@ -164,14 +164,14 @@ function wp_schedule_single_event( $timestamp, $hook, $args = array(), $wp_error * * @since 3.1.0 * - * @param stdClass|false $event { + * @param object|false $event { * An object containing an event's data, or boolean false to prevent the event from being scheduled. * * @type string $hook Action hook to execute when the event is run. * @type int $timestamp Unix timestamp (UTC) for when to next run the event. * @type string|false $schedule How often the event should subsequently recur. * @type array $args Array containing each separate argument to pass to the hook's callback function. - * @type int $interval The interval time in seconds for the schedule. Only present for recurring events. + * @type int $interval Optional. The interval time in seconds for the schedule. Only present for recurring events. * } */ $event = apply_filters( 'schedule_event', $event ); @@ -385,7 +385,7 @@ function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array(), $ * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned. * * @param null|bool|WP_Error $pre Value to return instead. Default null to continue adding the event. - * @param stdClass $event { + * @param object $event { * An object containing an event's data. * * @type string $hook Action hook to execute when the event is run. @@ -722,7 +722,15 @@ function wp_unschedule_hook( $hook, $wp_error = false ) { * Default empty array. * @param int|null $timestamp Optional. Unix timestamp (UTC) of the event. If not specified, the next scheduled event * is returned. Default null. - * @return object|false The event object. False if the event does not exist. + * @return object|false { + * The event object. False if the event does not exist. + * + * @type string $hook Action hook to execute when the event is run. + * @type int $timestamp Unix timestamp (UTC) for when to next run the event. + * @type string|false $schedule How often the event should subsequently recur. + * @type array $args Array containing each separate argument to pass to the hook's callback function. + * @type int $interval Optional. The interval time in seconds for the schedule. Only present for recurring events. + * } */ function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) { /** diff --git a/wp-includes/rest-api.php b/wp-includes/rest-api.php index af17733265..33fcdd5b8a 100644 --- a/wp-includes/rest-api.php +++ b/wp-includes/rest-api.php @@ -1292,8 +1292,13 @@ function rest_parse_hex_color( $color ) { * * @param string $date RFC3339 timestamp. * @param bool $is_utc Whether the provided date should be interpreted as UTC. Default false. - * @return array|null Local and UTC datetime strings, in MySQL datetime format (Y-m-d H:i:s), - * null on failure. + * @return array|null { + * Local and UTC datetime strings, in MySQL datetime format (Y-m-d H:i:s), + * null on failure. + * + * @type string $0 Local datetime string. + * @type string $1 UTC datetime string. + * } */ function rest_get_date_with_gmt( $date, $is_utc = false ) { /* @@ -1549,12 +1554,12 @@ function rest_is_object( $maybe_object ) { } /** - * Converts an object-like value to an object. + * Converts an object-like value to an array. * * @since 5.5.0 * * @param mixed $maybe_object The value being evaluated. - * @return array Returns the object extracted from the value. + * @return array Returns the object extracted from the value as an associative array. */ function rest_sanitize_object( $maybe_object ) { if ( '' === $maybe_object ) { @@ -1581,8 +1586,8 @@ function rest_sanitize_object( $maybe_object ) { * * @since 5.5.0 * - * @param mixed $value The value to check. - * @param array $types The list of possible types. + * @param mixed $value The value to check. + * @param string[] $types The list of possible types. * @return string The best matching type, an empty string if no types match. */ function rest_get_best_type_for_value( $value, $types ) { diff --git a/wp-includes/rest-api/endpoints/class-wp-rest-search-controller.php b/wp-includes/rest-api/endpoints/class-wp-rest-search-controller.php index 93502d60f4..bf59c1e998 100644 --- a/wp-includes/rest-api/endpoints/class-wp-rest-search-controller.php +++ b/wp-includes/rest-api/endpoints/class-wp-rest-search-controller.php @@ -360,7 +360,7 @@ class WP_REST_Search_Controller extends WP_REST_Controller { * @param string|array $subtypes One or more subtypes. * @param WP_REST_Request $request Full details about the request. * @param string $parameter Parameter name. - * @return array|WP_Error List of valid subtypes, or WP_Error object on failure. + * @return string[]|WP_Error List of valid subtypes, or WP_Error object on failure. */ public function sanitize_subtypes( $subtypes, $request, $parameter ) { $subtypes = wp_parse_slug_list( $subtypes ); diff --git a/wp-includes/rest-api/search/class-wp-rest-search-handler.php b/wp-includes/rest-api/search/class-wp-rest-search-handler.php index 34ba2f1c08..cc9dcf8215 100644 --- a/wp-includes/rest-api/search/class-wp-rest-search-handler.php +++ b/wp-includes/rest-api/search/class-wp-rest-search-handler.php @@ -37,7 +37,7 @@ abstract class WP_REST_Search_Handler { * Object subtypes managed by this search handler. * * @since 5.0.0 - * @var array + * @var string[] */ protected $subtypes = array(); @@ -57,7 +57,7 @@ abstract class WP_REST_Search_Handler { * * @since 5.0.0 * - * @return array Array of object subtype identifiers. + * @return string[] Array of object subtype identifiers. */ public function get_subtypes() { return $this->subtypes; diff --git a/wp-includes/version.php b/wp-includes/version.php index f3c01dc4c2..3b6a80cb80 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.2-beta1-55292'; +$wp_version = '6.2-beta1-55293'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.