From a6a5bea437fe2767037fc2b67051ec7e3febacc0 Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Tue, 20 Sep 2022 20:32:09 +0000
Subject: [PATCH] Docs: Various improvements and corrections to inline docs.

See #55646

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


git-svn-id: https://core.svn.wordpress.org/trunk@53826 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-admin/includes/template.php   |  2 +-
 wp-includes/cron.php             | 12 ++++++------
 wp-includes/functions.php        |  7 +------
 wp-includes/general-template.php |  1 +
 wp-includes/option.php           |  6 +++---
 wp-includes/post.php             |  2 +-
 wp-includes/script-loader.php    |  6 +++---
 wp-includes/version.php          |  2 +-
 8 files changed, 17 insertions(+), 21 deletions(-)

diff --git a/wp-admin/includes/template.php b/wp-admin/includes/template.php
index 4e100e409a..b0c6cb362f 100644
--- a/wp-admin/includes/template.php
+++ b/wp-admin/includes/template.php
@@ -1649,7 +1649,7 @@ function add_settings_section( $id, $title, $callback, $page, $args = array() )
  * @param string   $section  Optional. The slug-name of the section of the settings page
  *                           in which to show the box. Default 'default'.
  * @param array    $args {
- *     Optional. Extra arguments used when outputting the field.
+ *     Optional. Extra arguments that get passed to the callback function.
  *
  *     @type string $label_for When supplied, the setting title will be wrapped
  *                             in a `<label>` element, its `for` attribute populated
diff --git a/wp-includes/cron.php b/wp-includes/cron.php
index 56e864ed11..4a7899df8c 100644
--- a/wp-includes/cron.php
+++ b/wp-includes/cron.php
@@ -377,7 +377,7 @@ function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array(), $
 	);
 
 	/**
-	 * Filter to preflight or hijack rescheduling of events.
+	 * Filter to preflight or hijack 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.
@@ -392,11 +392,11 @@ function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array(), $
 	 * @param stdClass           $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 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 $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.
 	 * }
 	 * @param bool               $wp_error Whether to return a WP_Error on failure.
 	 */
diff --git a/wp-includes/functions.php b/wp-includes/functions.php
index f78b0cc6ff..35c2b1bd21 100644
--- a/wp-includes/functions.php
+++ b/wp-includes/functions.php
@@ -1496,12 +1496,7 @@ function wp_get_nocache_headers() {
 		 *
 		 * @see wp_get_nocache_headers()
 		 *
-		 * @param array $headers {
-		 *     Header names and field values.
-		 *
-		 *     @type string $Expires       Expires header.
-		 *     @type string $Cache-Control Cache-Control header.
-		 * }
+		 * @param array $headers Header names and field values.
 		 */
 		$headers = (array) apply_filters( 'nocache_headers', $headers );
 	}
diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php
index 5a1e4fdb7f..c687fd0138 100644
--- a/wp-includes/general-template.php
+++ b/wp-includes/general-template.php
@@ -4338,6 +4338,7 @@ function the_search_query() {
  * @since 4.3.0
  *
  * @param string $doctype Optional. The type of HTML document. Accepts 'xhtml' or 'html'. Default 'html'.
+ * @return string A space-separated list of language attributes.
  */
 function get_language_attributes( $doctype = 'html' ) {
 	$attributes = array();
diff --git a/wp-includes/option.php b/wp-includes/option.php
index 3deb035758..3c0b5b4cf9 100644
--- a/wp-includes/option.php
+++ b/wp-includes/option.php
@@ -342,7 +342,7 @@ function wp_load_alloptions( $force_cache = false ) {
  * Loads and caches certain often requested site options if is_multisite() and a persistent cache is not being used.
  *
  * @since 3.0.0
- * @since 6.1.0 Uses update_meta_cache
+ * @since 6.1.0 Now uses update_meta_cache().
  *
  * @param int $network_id Optional site ID for which to query the options. Defaults to the current site.
  */
@@ -1806,8 +1806,8 @@ function get_site_transient( $transient ) {
 	 *
 	 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
 	 *
-	 * Returning a truthy value from the filter will effectively short-circuit retrieval
-	 * and return the passed value instead.
+	 * Returning a value other than boolean false will short-circuit retrieval and
+	 * return that value instead.
 	 *
 	 * @since 2.9.0
 	 * @since 4.4.0 The `$transient` parameter was added.
diff --git a/wp-includes/post.php b/wp-includes/post.php
index aed2ee42f2..17abaf8558 100644
--- a/wp-includes/post.php
+++ b/wp-includes/post.php
@@ -7978,7 +7978,7 @@ function wp_cache_set_posts_last_changed() {
  * @global wpdb $wpdb WordPress database abstraction object.
  *
  * @param string $type
- * @return mixed
+ * @return string[] An array of MIME types.
  */
 function get_available_post_mime_types( $type = 'attachment' ) {
 	global $wpdb;
diff --git a/wp-includes/script-loader.php b/wp-includes/script-loader.php
index f9626dc42e..ed697693d0 100644
--- a/wp-includes/script-loader.php
+++ b/wp-includes/script-loader.php
@@ -169,7 +169,7 @@ function wp_default_packages_vendor( $scripts ) {
  * @since 5.0.0
  *
  * @param WP_Scripts $scripts WP_Scripts object.
- * @param array      $tests   Features to detect.
+ * @param string[]   $tests   Features to detect.
  * @return string Conditional polyfill inline script.
  */
 function wp_get_script_polyfill( $scripts, $tests ) {
@@ -1745,8 +1745,8 @@ function wp_default_styles( $styles ) {
  *
  * @since 2.3.1
  *
- * @param array $js_array JavaScript scripts array
- * @return array Reordered array, if needed.
+ * @param string[] $js_array JavaScript scripts array
+ * @return string[] Reordered array, if needed.
  */
 function wp_prototype_before_jquery( $js_array ) {
 	$prototype = array_search( 'prototype', $js_array, true );
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 1b7b8ed0f1..55fb0f3a63 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.1-alpha-54266';
+$wp_version = '6.1-alpha-54267';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.