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

See #55646


git-svn-id: https://develop.svn.wordpress.org/trunk@54267 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/template.php   |  2 +-
 src/wp-includes/cron.php             | 12 ++++++------
 src/wp-includes/functions.php        |  7 +------
 src/wp-includes/general-template.php |  1 +
 src/wp-includes/option.php           |  6 +++---
 src/wp-includes/post.php             |  2 +-
 src/wp-includes/script-loader.php    |  6 +++---
 7 files changed, 16 insertions(+), 20 deletions(-)

diff --git a/src/wp-admin/includes/template.php b/src/wp-admin/includes/template.php
index 4e100e409a..b0c6cb362f 100644
--- a/src/wp-admin/includes/template.php
+++ b/src/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/src/wp-includes/cron.php b/src/wp-includes/cron.php
index 56e864ed11..4a7899df8c 100644
--- a/src/wp-includes/cron.php
+++ b/src/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/src/wp-includes/functions.php b/src/wp-includes/functions.php
index f78b0cc6ff..35c2b1bd21 100644
--- a/src/wp-includes/functions.php
+++ b/src/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/src/wp-includes/general-template.php b/src/wp-includes/general-template.php
index 5a1e4fdb7f..c687fd0138 100644
--- a/src/wp-includes/general-template.php
+++ b/src/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/src/wp-includes/option.php b/src/wp-includes/option.php
index 3deb035758..3c0b5b4cf9 100644
--- a/src/wp-includes/option.php
+++ b/src/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/src/wp-includes/post.php b/src/wp-includes/post.php
index aed2ee42f2..17abaf8558 100644
--- a/src/wp-includes/post.php
+++ b/src/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/src/wp-includes/script-loader.php b/src/wp-includes/script-loader.php
index f9626dc42e..ed697693d0 100644
--- a/src/wp-includes/script-loader.php
+++ b/src/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 );