From 3d9945486ed163a8a14c46cf1834bc781d8292a0 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 May 2024 13:19:14 +0000 Subject: [PATCH] Docs: Various docblock improvements. See #60699 Built from https://develop.svn.wordpress.org/trunk@58075 git-svn-id: http://core.svn.wordpress.org/trunk@57540 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/misc.php | 16 ++++++++-------- wp-includes/block-bindings.php | 2 +- wp-includes/class-wp-block-bindings-registry.php | 6 +++--- wp-includes/class-wp-block-bindings-source.php | 3 +-- wp-includes/class-wp-script-modules.php | 11 +++++------ wp-includes/cron.php | 13 +++++++------ wp-includes/fonts/class-wp-font-face.php | 2 +- wp-includes/fonts/class-wp-font-utils.php | 2 +- wp-includes/option.php | 4 ++-- wp-includes/version.php | 2 +- 10 files changed, 30 insertions(+), 31 deletions(-) diff --git a/wp-admin/includes/misc.php b/wp-admin/includes/misc.php index ffe3801ce8..06fc294445 100644 --- a/wp-admin/includes/misc.php +++ b/wp-admin/includes/misc.php @@ -556,7 +556,7 @@ function wp_print_plugin_file_tree( $tree, $label = '', $level = 2, $size = 1, $ } /** - * Flushes rewrite rules if siteurl, home or page_on_front changed. + * Flushes rewrite rules if `siteurl`, `home` or `page_on_front` changed. * * @since 2.1.0 * @@ -576,11 +576,11 @@ function update_home_siteurl( $old_value, $value ) { } /** - * Resets global variables based on $_GET and $_POST. + * Resets global variables based on `$_GET` and `$_POST`. * * This function resets global variables based on the names passed - * in the $vars array to the value of $_POST[$var] or $_GET[$var] or '' - * if neither is defined. + * in the `$vars` array to the value of `$_POST[$var]` or `$_GET[$var]` or an + * empty string if neither is defined. * * @since 2.0.0 * @@ -754,7 +754,7 @@ function set_screen_options() { /** * Filters a screen option value before it is set. * - * The filter can also be used to modify non-standard [items]_per_page + * The filter can also be used to modify non-standard `[items]_per_page` * settings. See the parent function for a full list of standard options. * * Returning false from the filter will skip saving the current option. @@ -1304,7 +1304,7 @@ function wp_refresh_metabox_loader_nonces( $response, $data ) { } /** - * Adds the latest Heartbeat and REST-API nonce to the Heartbeat response. + * Adds the latest Heartbeat and REST API nonce to the Heartbeat response. * * @since 5.0.0 * @@ -1398,11 +1398,11 @@ function wp_admin_canonical_url() { $filtered_url = remove_query_arg( $removable_query_args, $current_url ); /** - * Filters the admin canonical url value. + * Filters the admin canonical URL value. * * @since 6.5.0 * - * @param string $filtered_url The admin canonical url value. + * @param string $filtered_url The admin canonical URL value. */ $filtered_url = apply_filters( 'wp_admin_canonical_url', $filtered_url ); ?> diff --git a/wp-includes/block-bindings.php b/wp-includes/block-bindings.php index d7b2692081..300b4ddde3 100644 --- a/wp-includes/block-bindings.php +++ b/wp-includes/block-bindings.php @@ -87,7 +87,7 @@ * - @param string $attribute_name The name of an attribute . * The callback has a mixed return type; it may return a string to override * the block's original value, null, false to remove an attribute, etc. - * @type array $uses_context (optional) Array of values to add to block `uses_context` needed by the source. + * @type string[] $uses_context (optional) Array of values to add to block `uses_context` needed by the source. * } * @return WP_Block_Bindings_Source|false Source when the registration was successful, or `false` on failure. */ diff --git a/wp-includes/class-wp-block-bindings-registry.php b/wp-includes/class-wp-block-bindings-registry.php index 0d76b1a4c2..278ec47de2 100644 --- a/wp-includes/class-wp-block-bindings-registry.php +++ b/wp-includes/class-wp-block-bindings-registry.php @@ -36,7 +36,7 @@ final class WP_Block_Bindings_Registry { * Supported source properties that can be passed to the registered source. * * @since 6.5.0 - * @var array + * @var string[] */ private $allowed_source_properties = array( 'label', @@ -48,7 +48,7 @@ final class WP_Block_Bindings_Registry { * Supported blocks that can use the block bindings API. * * @since 6.5.0 - * @var array + * @var string[] */ private $supported_blocks = array( 'core/paragraph', @@ -90,7 +90,7 @@ final class WP_Block_Bindings_Registry { * - @param string $attribute_name The name of the target attribute. * The callback has a mixed return type; it may return a string to override * the block's original value, null, false to remove an attribute, etc. - * @type array $uses_context (optional) Array of values to add to block `uses_context` needed by the source. + * @type string[] $uses_context (optional) Array of values to add to block `uses_context` needed by the source. * } * @return WP_Block_Bindings_Source|false Source when the registration was successful, or `false` on failure. */ diff --git a/wp-includes/class-wp-block-bindings-source.php b/wp-includes/class-wp-block-bindings-source.php index 036e17c3dd..c1b479f20e 100644 --- a/wp-includes/class-wp-block-bindings-source.php +++ b/wp-includes/class-wp-block-bindings-source.php @@ -36,7 +36,6 @@ final class WP_Block_Bindings_Source { */ public $label; - /** * The function used to get the value from the source. * @@ -49,7 +48,7 @@ final class WP_Block_Bindings_Source { * The context added to the blocks needed by the source. * * @since 6.5.0 - * @var array|null + * @var string[]|null */ public $uses_context = null; diff --git a/wp-includes/class-wp-script-modules.php b/wp-includes/class-wp-script-modules.php index 89d12a6b3f..d391878d7c 100644 --- a/wp-includes/class-wp-script-modules.php +++ b/wp-includes/class-wp-script-modules.php @@ -18,7 +18,7 @@ class WP_Script_Modules { * Holds the registered script modules, keyed by script module identifier. * * @since 6.5.0 - * @var array + * @var array[] */ private $registered = array(); @@ -274,7 +274,7 @@ class WP_Script_Modules { * * @since 6.5.0 * - * @return array Script modules marked for enqueue, keyed by script module identifier. + * @return array[] Script modules marked for enqueue, keyed by script module identifier. */ private function get_marked_for_enqueue(): array { $enqueued = array(); @@ -296,11 +296,10 @@ class WP_Script_Modules { * * @since 6.5.0 * - * @param string[] $ids The identifiers of the script modules for which to gather dependencies. - * @param array $import_types Optional. Import types of dependencies to retrieve: 'static', 'dynamic', or both. + * @param string[] $import_types Optional. Import types of dependencies to retrieve: 'static', 'dynamic', or both. * Default is both. - * @return array List of dependencies, keyed by script module identifier. + * @return array[] List of dependencies, keyed by script module identifier. */ private function get_dependencies( array $ids, array $import_types = array( 'static', 'dynamic' ) ) { return array_reduce( @@ -353,7 +352,7 @@ class WP_Script_Modules { * * @since 6.5.0 * - * @param string $src Module source url. + * @param string $src Module source URL. * @param string $id Module identifier. */ $src = apply_filters( 'script_module_loader_src', $src, $id ); diff --git a/wp-includes/cron.php b/wp-includes/cron.php index aadc22b7eb..9371515aba 100644 --- a/wp-includes/cron.php +++ b/wp-includes/cron.php @@ -659,8 +659,9 @@ function wp_unschedule_hook( $hook, $wp_error = false ) { * process, causing the function to return the filtered value instead. * * For plugins replacing wp-cron, return the number of events successfully - * unscheduled (zero if no events were registered with the hook) or false - * if unscheduling one or more events fails. + * unscheduled (zero if no events were registered with the hook). If unscheduling + * one or more events fails then return either a WP_Error object or false depending + * on the value of the `$wp_error` parameter. * * @since 5.1.0 * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned. @@ -1047,14 +1048,14 @@ function _wp_cron() { * one is 'interval' and the other is 'display'. * * The 'interval' is a number in seconds of when the cron job should run. - * So for 'hourly' the time is `HOUR_IN_SECONDS` (60 * 60 or 3600). For 'monthly', - * the value would be `MONTH_IN_SECONDS` (30 * 24 * 60 * 60 or 2592000). + * So for 'hourly' the time is `HOUR_IN_SECONDS` (`60 * 60` or `3600`). For 'monthly', + * the value would be `MONTH_IN_SECONDS` (`30 * 24 * 60 * 60` or `2592000`). * * The 'display' is the description. For the 'monthly' key, the 'display' * would be `__( 'Once Monthly' )`. * - * For your plugin, you will be passed an array. You can easily add your - * schedule by doing the following. + * For your plugin, you will be passed an array. You can add your + * schedule by doing the following: * * // Filter parameter variable name is 'array'. * $array['monthly'] = array( diff --git a/wp-includes/fonts/class-wp-font-face.php b/wp-includes/fonts/class-wp-font-face.php index 974e13ed1d..50d0268a70 100644 --- a/wp-includes/fonts/class-wp-font-face.php +++ b/wp-includes/fonts/class-wp-font-face.php @@ -256,7 +256,7 @@ class WP_Font_Face { * * @since 6.4.0 * - * @param array $font_faces The font-faces to generate @font-face CSS styles. + * @param array[] $font_faces The font-faces to generate @font-face CSS styles. * @return string The `@font-face` CSS styles. */ private function get_css( $font_faces ) { diff --git a/wp-includes/fonts/class-wp-font-utils.php b/wp-includes/fonts/class-wp-font-utils.php index 2dc685ed0d..0ec36abc3f 100644 --- a/wp-includes/fonts/class-wp-font-utils.php +++ b/wp-includes/fonts/class-wp-font-utils.php @@ -244,7 +244,7 @@ class WP_Font_Utils { * * @access private * - * @return array A collection of mime types keyed by file extension. + * @return string[] A collection of mime types keyed by file extension. */ public static function get_allowed_font_mime_types() { $php_7_ttf_mime_type = PHP_VERSION_ID >= 70300 ? 'application/font-sfnt' : 'application/x-font-ttf'; diff --git a/wp-includes/option.php b/wp-includes/option.php index 4c0071e23d..0c5247f1a5 100644 --- a/wp-includes/option.php +++ b/wp-includes/option.php @@ -3034,7 +3034,7 @@ function filter_default_option( $default_value, $option, $passed_default ) { * * @since 6.6.0 * - * @return array The values that trigger autoloading. + * @return string[] The values that trigger autoloading. */ function wp_autoload_values_to_autoload() { $autoload_values = array( 'yes', 'on', 'auto-on', 'auto' ); @@ -3046,7 +3046,7 @@ function wp_autoload_values_to_autoload() { * * @since 6.6.0 * - * @param array $autoload_values Autoload values used to autoload option. + * @param string[] $autoload_values Autoload values used to autoload option. * Default list contains 'yes', 'on', 'auto-on', and 'auto'. */ $filtered_values = apply_filters( 'wp_autoload_values_to_autoload', $autoload_values ); diff --git a/wp-includes/version.php b/wp-includes/version.php index c20f659de3..58de8a2436 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.6-alpha-58074'; +$wp_version = '6.6-alpha-58075'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.