From e6cc65d39ecff03901f1d28365367da347d6589e Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Tue, 31 Jan 2023 17:50:12 +0000
Subject: [PATCH] Cron API: Improve the docs for some cron event and cron
 schedule related functions.

See #56792

Built from https://develop.svn.wordpress.org/trunk@55170


git-svn-id: http://core.svn.wordpress.org/trunk@54703 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/cron.php    | 48 ++++++++++++++++++++++++++++-------------
 wp-includes/version.php |  2 +-
 2 files changed, 34 insertions(+), 16 deletions(-)

diff --git a/wp-includes/cron.php b/wp-includes/cron.php
index 4726a8d474..9903846dd9 100644
--- a/wp-includes/cron.php
+++ b/wp-includes/cron.php
@@ -437,9 +437,9 @@ function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array(), $
 }
 
 /**
- * Unschedule a previously scheduled event.
+ * Unschedules a previously scheduled event.
  *
- * The $timestamp and $hook parameters are required so that the event can be
+ * The `$timestamp` and `$hook` parameters are required so that the event can be
  * identified.
  *
  * @since 2.1.0
@@ -708,9 +708,9 @@ function wp_unschedule_hook( $hook, $wp_error = false ) {
 }
 
 /**
- * Retrieve a scheduled event.
+ * Retrieves a scheduled event.
  *
- * Retrieve the full event object for a given event, if no timestamp is specified the next
+ * Retrieves the full event object for a given event, if no timestamp is specified the next
  * scheduled event is returned.
  *
  * @since 5.1.0
@@ -792,7 +792,7 @@ function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) {
 }
 
 /**
- * Retrieve the next timestamp for an event.
+ * Retrieves the next timestamp for an event.
  *
  * @since 2.1.0
  *
@@ -924,7 +924,7 @@ function spawn_cron( $gmt_time = 0 ) {
 }
 
 /**
- * Register _wp_cron() to run on the {@see 'wp_loaded'} action.
+ * Registers _wp_cron() to run on the {@see 'wp_loaded'} action.
  *
  * If the {@see 'wp_loaded'} action has already fired, this function calls
  * _wp_cron() directly.
@@ -951,7 +951,7 @@ function wp_cron() {
 }
 
 /**
- * Run scheduled callbacks or spawn cron for all scheduled events.
+ * Runs scheduled callbacks or spawns cron for all scheduled events.
  *
  * 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
@@ -1003,7 +1003,7 @@ function _wp_cron() {
 }
 
 /**
- * Retrieve supported event recurrence schedules.
+ * Retrieves supported event recurrence schedules.
  *
  * The default supported recurrences are 'hourly', 'twicedaily', 'daily', and 'weekly'.
  * A plugin may add more by hooking into the {@see 'cron_schedules'} filter.
@@ -1030,7 +1030,16 @@ function _wp_cron() {
  * @since 2.1.0
  * @since 5.4.0 The 'weekly' schedule was added.
  *
- * @return array[]
+ * @return array {
+ *     The array of cron schedules keyed by the schedule name.
+ *
+ *     @type array ...$0 {
+ *         Cron schedule information.
+ *
+ *         @type int    $interval The schedule interval in seconds.
+ *         @type string $display  The schedule display name.
+ *     }
+ * }
  */
 function wp_get_schedules() {
 	$schedules = array(
@@ -1057,13 +1066,22 @@ function wp_get_schedules() {
 	 *
 	 * @since 2.1.0
 	 *
-	 * @param array[] $new_schedules An array of non-default cron schedule arrays. Default empty.
+	 * @param array $new_schedules {
+	 *     An array of non-default cron schedules keyed by the schedule name. Default empty array.
+	 *
+	 *     @type array ...$0 {
+	 *         Cron schedule information.
+	 *
+	 *         @type int    $interval The schedule interval in seconds.
+	 *         @type string $display  The schedule display name.
+	 *     }
+	 * }
 	 */
 	return array_merge( apply_filters( 'cron_schedules', array() ), $schedules );
 }
 
 /**
- * Retrieve the recurrence schedule for an event.
+ * Retrieves the name of the recurrence schedule for an event.
  *
  * @see wp_get_schedules() for available schedules.
  *
@@ -1084,7 +1102,7 @@ function wp_get_schedule( $hook, $args = array() ) {
 	}
 
 	/**
-	 * Filters the schedule for a hook.
+	 * Filters the schedule name for a hook.
 	 *
 	 * @since 5.1.0
 	 *
@@ -1096,7 +1114,7 @@ function wp_get_schedule( $hook, $args = array() ) {
 }
 
 /**
- * Retrieve cron jobs ready to be run.
+ * Retrieves cron jobs ready to be run.
  *
  * Returns the results of _get_cron_array() limited to events ready to be run,
  * ie, with a timestamp in the past.
@@ -1143,7 +1161,7 @@ function wp_get_ready_cron_jobs() {
 //
 
 /**
- * Retrieve cron info array option.
+ * Retrieves cron info array option.
  *
  * @since 2.1.0
  * @since 6.1.0 Return type modified to consistently return an array.
@@ -1198,7 +1216,7 @@ function _set_cron_array( $cron, $wp_error = false ) {
 }
 
 /**
- * Upgrade a cron info array.
+ * Upgrades a cron info array.
  *
  * This function upgrades the cron info array to version 2.
  *
diff --git a/wp-includes/version.php b/wp-includes/version.php
index cf27a225f0..f3f04181e0 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.2-alpha-55169';
+$wp_version = '6.2-alpha-55170';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.