From 4667b9323fee09366f83ce6a01331fff209aae71 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 18 Aug 2023 17:29:20 +0000 Subject: [PATCH] Docs: Miscellaneous docblock corrections and improvements. See #58833 Built from https://develop.svn.wordpress.org/trunk@56414 git-svn-id: http://core.svn.wordpress.org/trunk@55926 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/plugin.php | 4 +-- wp-admin/includes/schema.php | 2 +- wp-includes/block-supports/utils.php | 2 +- wp-includes/block-template-utils.php | 8 +++--- wp-includes/class-wp-block-type.php | 4 +-- wp-includes/class-wp-navigation-fallback.php | 2 +- wp-includes/class-wp-theme-json.php | 2 +- wp-includes/cron.php | 28 ++++++++++---------- wp-includes/functions.php | 2 +- wp-includes/functions.wp-scripts.php | 12 ++++----- wp-includes/l10n.php | 2 +- wp-includes/post.php | 4 +-- wp-includes/theme.php | 2 +- wp-includes/version.php | 2 +- 14 files changed, 38 insertions(+), 38 deletions(-) diff --git a/wp-admin/includes/plugin.php b/wp-admin/includes/plugin.php index 0e48817361..d5e62ed06f 100644 --- a/wp-admin/includes/plugin.php +++ b/wp-admin/includes/plugin.php @@ -854,7 +854,7 @@ function deactivate_plugins( $plugins, $silent = false, $network_wide = null ) { * @param bool $network_wide Whether to enable the plugin for all sites in the network. * Default false. * @param bool $silent Prevent calling activation hooks. Default false. - * @return bool|WP_Error True when finished or WP_Error if there were errors during a plugin activation. + * @return true|WP_Error True when finished or WP_Error if there were errors during a plugin activation. */ function activate_plugins( $plugins, $redirect = '', $network_wide = false, $silent = false ) { if ( ! is_array( $plugins ) ) { @@ -2440,7 +2440,7 @@ function wp_get_plugin_error( $plugin ) { * * @param string $plugin Single plugin to resume. * @param string $redirect Optional. URL to redirect to. Default empty string. - * @return bool|WP_Error True on success, false if `$plugin` was not paused, + * @return true|WP_Error True on success, false if `$plugin` was not paused, * `WP_Error` on failure. */ function resume_plugin( $plugin, $redirect = '' ) { diff --git a/wp-admin/includes/schema.php b/wp-admin/includes/schema.php index db91a62809..89d9fabfc0 100644 --- a/wp-admin/includes/schema.php +++ b/wp-admin/includes/schema.php @@ -979,7 +979,7 @@ endif; * @param string $path Optional. The path to append to the network's domain name. Default '/'. * @param bool $subdomain_install Optional. Whether the network is a subdomain installation or a subdirectory installation. * Default false, meaning the network is a subdirectory installation. - * @return bool|WP_Error True on success, or WP_Error on warning (with the installation otherwise successful, + * @return true|WP_Error True on success, or WP_Error on warning (with the installation otherwise successful, * so the error code must be checked) or failure. */ function populate_network( $network_id = 1, $domain = '', $email = '', $site_name = '', $path = '/', $subdomain_install = false ) { diff --git a/wp-includes/block-supports/utils.php b/wp-includes/block-supports/utils.php index 6e15d5388b..7c5d7db48a 100644 --- a/wp-includes/block-supports/utils.php +++ b/wp-includes/block-supports/utils.php @@ -18,7 +18,7 @@ * @param string $feature_set Name of block support feature set.. * @param string $feature Optional name of individual feature to check. * - * @return boolean Whether to serialize block support styles & classes. + * @return bool Whether to serialize block support styles & classes. */ function wp_should_skip_block_supports_serialization( $block_type, $feature_set, $feature = null ) { if ( ! is_object( $block_type ) || ! $feature_set ) { diff --git a/wp-includes/block-template-utils.php b/wp-includes/block-template-utils.php index 438556a7b9..b8538ee3b4 100644 --- a/wp-includes/block-template-utils.php +++ b/wp-includes/block-template-utils.php @@ -308,10 +308,10 @@ function _get_block_template_file( $template_type, $slug ) { * @param array $query { * Arguments to retrieve templates. Optional, empty by default. * - * @type array $slug__in List of slugs to include. - * @type array $slug__not_in List of slugs to skip. - * @type string $area A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only). - * @type string $post_type Post type to get the templates for. + * @type string[] $slug__in List of slugs to include. + * @type string[] $slug__not_in List of slugs to skip. + * @type string $area A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only). + * @type string $post_type Post type to get the templates for. * } * * @return array Template diff --git a/wp-includes/class-wp-block-type.php b/wp-includes/class-wp-block-type.php index 1fb8894164..e28bacd3b2 100644 --- a/wp-includes/class-wp-block-type.php +++ b/wp-includes/class-wp-block-type.php @@ -333,8 +333,8 @@ class WP_Block_Type { * * @param string $name Deprecated property name. * - * @return boolean Returns true when for the new property the first item in the array exists, - * or false otherwise. + * @return bool Returns true when for the new property the first item in the array exists, + * or false otherwise. */ public function __isset( $name ) { if ( ! in_array( $name, $this->deprecated_properties, true ) ) { diff --git a/wp-includes/class-wp-navigation-fallback.php b/wp-includes/class-wp-navigation-fallback.php index 99bece209f..70ddf11e4e 100644 --- a/wp-includes/class-wp-navigation-fallback.php +++ b/wp-includes/class-wp-navigation-fallback.php @@ -31,7 +31,7 @@ class WP_Navigation_Fallback { * * @since 6.3.0 * - * @param bool Whether to create a fallback navigation menu. Default true. + * @param bool $create Whether to create a fallback navigation menu. Default true. */ $should_create_fallback = apply_filters( 'wp_navigation_should_create_fallback', true ); diff --git a/wp-includes/class-wp-theme-json.php b/wp-includes/class-wp-theme-json.php index dc297fa9b9..d4b50cd953 100644 --- a/wp-includes/class-wp-theme-json.php +++ b/wp-includes/class-wp-theme-json.php @@ -2685,7 +2685,7 @@ class WP_Theme_JSON { * @param array $theme_json The theme.json like structure to inspect. * @param array $path Path to inspect. * @param bool|array $override Data to compute whether to override the preset. - * @return boolean + * @return bool */ protected static function should_override_preset( $theme_json, $path, $override ) { _deprecated_function( __METHOD__, '6.0.0', 'get_metadata_boolean' ); diff --git a/wp-includes/cron.php b/wp-includes/cron.php index c89d7376aa..c3a281a626 100644 --- a/wp-includes/cron.php +++ b/wp-includes/cron.php @@ -57,7 +57,7 @@ function wp_schedule_single_event( $timestamp, $hook, $args = array(), $wp_error ); /** - * Filter to preflight or hijack scheduling an event. + * Filter to override scheduling an event. * * Returning a non-null value will short-circuit adding the event to the * cron array, causing the function to return the filtered value instead. @@ -376,7 +376,7 @@ function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array(), $ ); /** - * Filter to preflight or hijack rescheduling of a recurring event. + * Filter to override rescheduling of a recurring event. * * Returning a non-null value will short-circuit the normal rescheduling * process, causing the function to return the filtered value instead. @@ -473,7 +473,7 @@ function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = fa } /** - * Filter to preflight or hijack unscheduling of events. + * Filter to override unscheduling of events. * * Returning a non-null value will short-circuit the normal unscheduling * process, causing the function to return the filtered value instead. @@ -526,8 +526,8 @@ function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = fa /** * Unschedules all events attached to the hook with the specified arguments. * - * Warning: This function may return Boolean FALSE, but may also return a non-Boolean - * value which evaluates to FALSE. For information about casting to booleans see the + * Warning: This function may return boolean false, but may also return a non-boolean + * value which evaluates to false. For information about casting to booleans see the * {@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use * the `===` operator for testing the return value of this function. * @@ -563,7 +563,7 @@ function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) { } /** - * Filter to preflight or hijack clearing a scheduled hook. + * Filter to override clearing a scheduled hook. * * Returning a non-null value will short-circuit the normal unscheduling * process, causing the function to return the filtered value instead. @@ -637,8 +637,8 @@ function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) { * * Can be useful for plugins when deactivating to clean up the cron queue. * - * Warning: This function may return Boolean FALSE, but may also return a non-Boolean - * value which evaluates to FALSE. For information about casting to booleans see the + * Warning: This function may return boolean false, but may also return a non-boolean + * value which evaluates to false. For information about casting to booleans see the * {@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use * the `===` operator for testing the return value of this function. * @@ -653,7 +653,7 @@ function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) { */ function wp_unschedule_hook( $hook, $wp_error = false ) { /** - * Filter to preflight or hijack clearing all events attached to the hook. + * Filter to override clearing all events attached to the hook. * * Returning a non-null value will short-circuit the normal unscheduling * process, causing the function to return the filtered value instead. @@ -749,7 +749,7 @@ function wp_unschedule_hook( $hook, $wp_error = false ) { */ function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) { /** - * Filter to preflight or hijack retrieving a scheduled event. + * Filter to override retrieving a scheduled event. * * Returning a non-null value will short-circuit the normal process, * returning the filtered value instead. @@ -965,9 +965,9 @@ function spawn_cron( $gmt_time = 0 ) { * @since 5.1.0 Return value added to indicate success or failure. * @since 5.7.0 Functionality moved to _wp_cron() to which this becomes a wrapper. * - * @return bool|int|void On success an integer indicating number of events spawned (0 indicates no - * events needed to be spawned), false if spawning fails for one or more events or - * void if the function registered _wp_cron() to run on the action. + * @return false|int|void On success an integer indicating number of events spawned (0 indicates no + * events needed to be spawned), false if spawning fails for one or more events or + * void if the function registered _wp_cron() to run on the action. */ function wp_cron() { if ( did_action( 'wp_loaded' ) ) { @@ -1160,7 +1160,7 @@ function wp_get_schedule( $hook, $args = array() ) { */ function wp_get_ready_cron_jobs() { /** - * Filter to preflight or hijack retrieving ready cron jobs. + * Filter to override retrieving ready cron jobs. * * Returning an array will short-circuit the normal retrieval of ready * cron jobs, causing the function to return the filtered value instead. diff --git a/wp-includes/functions.php b/wp-includes/functions.php index 731aed9229..16a32dd7bf 100644 --- a/wp-includes/functions.php +++ b/wp-includes/functions.php @@ -8600,7 +8600,7 @@ function is_php_version_compatible( $required ) { * * @param int|float $expected The expected value. * @param int|float $actual The actual number. - * @param int|float $precision The allowed variation. + * @param int|float $precision Optional. The allowed variation. Default 1. * @return bool Whether the numbers match within the specified precision. */ function wp_fuzzy_number_match( $expected, $actual, $precision = 1 ) { diff --git a/wp-includes/functions.wp-scripts.php b/wp-includes/functions.wp-scripts.php index aab583d6e3..269e875e80 100644 --- a/wp-includes/functions.wp-scripts.php +++ b/wp-includes/functions.wp-scripts.php @@ -73,7 +73,7 @@ function _wp_scripts_maybe_doing_it_wrong( $function_name, $handle = '' ) { * * Called by admin-header.php and {@see 'wp_head'} hook. Since it is called by wp_head on every page load, * the function does not instantiate the WP_Scripts object unless script names are explicitly passed. - * Makes use of already-instantiated $wp_scripts global if present. Use provided {@see 'wp_print_scripts'} + * Makes use of already-instantiated `$wp_scripts` global if present. Use provided {@see 'wp_print_scripts'} * hook to register/enqueue new scripts. * * @see WP_Scripts::do_item() @@ -113,8 +113,8 @@ function wp_print_scripts( $handles = false ) { * Adds extra code to a registered script. * * Code will only be added if the script is already in the queue. - * Accepts a string $data containing the Code. If two or more code blocks - * are added to the same script $handle, they will be printed in the order + * Accepts a string `$data` containing the code. If two or more code blocks + * are added to the same script `$handle`, they will be printed in the order * they were added, i.e. the latter added code can redeclare the previous. * * @since 4.5.0 @@ -201,9 +201,9 @@ function wp_register_script( $handle, $src, $deps = array(), $ver = false, $args * * Works only if the script has already been registered. * - * Accepts an associative array $l10n and creates a JavaScript object: + * Accepts an associative array `$l10n` and creates a JavaScript object: * - * "$object_name" = { + * "$object_name": { * key: value, * key: value, * ... @@ -337,7 +337,7 @@ function wp_deregister_script( $handle ) { /** * Enqueues a script. * - * Registers the script if $src provided (does NOT overwrite), and enqueues it. + * Registers the script if `$src` provided (does NOT overwrite), and enqueues it. * * @see WP_Dependencies::add() * @see WP_Dependencies::add_data() diff --git a/wp-includes/l10n.php b/wp-includes/l10n.php index 951c1c316b..a085d4483f 100644 --- a/wp-includes/l10n.php +++ b/wp-includes/l10n.php @@ -1517,7 +1517,7 @@ function wp_get_pomo_file_data( $po_file ) { * * @type string $id ID attribute of the select element. Default 'locale'. * @type string $name Name attribute of the select element. Default 'locale'. - * @type array $languages List of installed languages, contain only the locales. + * @type string[] $languages List of installed languages, contain only the locales. * Default empty array. * @type array $translations List of available translations. Default result of * wp_get_available_translations(). diff --git a/wp-includes/post.php b/wp-includes/post.php index 22a37683ea..59b1975207 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -4974,8 +4974,8 @@ function check_and_publish_future_post( $post ) { * * @since 5.7.0 * - * @param string $post_date The date in mysql format. - * @param string $post_date_gmt The GMT date in mysql format. + * @param string $post_date The date in mysql format (`Y-m-d H:i:s`). + * @param string $post_date_gmt The GMT date in mysql format (`Y-m-d H:i:s`). * @return string|false A valid Gregorian-calendar date string, or false on failure. */ function wp_resolve_post_date( $post_date = '', $post_date_gmt = '' ) { diff --git a/wp-includes/theme.php b/wp-includes/theme.php index 911c4a942b..5ff31953b1 100644 --- a/wp-includes/theme.php +++ b/wp-includes/theme.php @@ -4268,7 +4268,7 @@ function create_initial_theme_features() { * * @since 5.9.0 * - * @return boolean Whether the active theme is a block-based theme or not. + * @return bool Whether the active theme is a block-based theme or not. */ function wp_is_block_theme() { return wp_get_theme()->is_block_theme(); diff --git a/wp-includes/version.php b/wp-includes/version.php index c495818a6e..6f50f6067f 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.4-alpha-56413'; +$wp_version = '6.4-alpha-56414'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.