From 4667b9323fee09366f83ce6a01331fff209aae71 Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
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.