From 79db573265351206614d65697711e40b5aca5b74 Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Thu, 4 Aug 2022 14:52:11 +0000
Subject: [PATCH] Docs: Various corrections and improvements to inline
 documentation.

See #55646

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


git-svn-id: http://core.svn.wordpress.org/trunk@53386 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-admin/authorize-application.php     |  4 ++--
 wp-admin/edit-tags.php                 |  2 +-
 wp-includes/category.php               |  2 +-
 wp-includes/class-wp-comment-query.php |  2 --
 wp-includes/class-wp-http.php          |  4 ++--
 wp-includes/class-wp-query.php         |  2 +-
 wp-includes/link-template.php          |  2 +-
 wp-includes/media.php                  |  5 ++---
 wp-includes/meta.php                   |  4 ++--
 wp-includes/option.php                 | 22 ++++++++++++----------
 wp-includes/pluggable.php              |  1 +
 wp-includes/taxonomy.php               |  4 ++--
 wp-includes/version.php                |  2 +-
 wp-login.php                           |  2 ++
 14 files changed, 30 insertions(+), 28 deletions(-)

diff --git a/wp-admin/authorize-application.php b/wp-admin/authorize-application.php
index 1bcf07b77c..1eabb96335 100644
--- a/wp-admin/authorize-application.php
+++ b/wp-admin/authorize-application.php
@@ -250,8 +250,8 @@ require_once ABSPATH . 'wp-admin/admin-header.php';
 				 *     The array of request data. All arguments are optional and may be empty.
 				 *
 				 *     @type string $app_name    The suggested name of the application.
-				 *     @type string $success_url The url the user will be redirected to after approving the application.
-				 *     @type string $reject_url  The url the user will be redirected to after rejecting the application.
+				 *     @type string $success_url The URL the user will be redirected to after approving the application.
+				 *     @type string $reject_url  The URL the user will be redirected to after rejecting the application.
 				 * }
 				 * @param WP_User $user The user authorizing the application.
 				 */
diff --git a/wp-admin/edit-tags.php b/wp-admin/edit-tags.php
index 3111c51069..cab8ff48de 100644
--- a/wp-admin/edit-tags.php
+++ b/wp-admin/edit-tags.php
@@ -486,7 +486,7 @@ if ( $can_edit_terms ) {
 		 * @param array  $dropdown_args {
 		 *     An array of taxonomy parent drop-down arguments.
 		 *
-		 *     @type int|bool $hide_empty       Whether to hide terms not attached to any posts. Default 0|false.
+		 *     @type int|bool $hide_empty       Whether to hide terms not attached to any posts. Default 0.
 		 *     @type bool     $hide_if_empty    Whether to hide the drop-down if no terms exist. Default false.
 		 *     @type string   $taxonomy         The taxonomy slug.
 		 *     @type string   $name             Value of the name attribute to use for the drop-down select element.
diff --git a/wp-includes/category.php b/wp-includes/category.php
index 0acc2dca52..0c06c4c6ea 100644
--- a/wp-includes/category.php
+++ b/wp-includes/category.php
@@ -269,7 +269,7 @@ function sanitize_category( $category, $context = 'display' ) {
  * @param mixed  $value   Category value to sanitize.
  * @param int    $cat_id  Category ID.
  * @param string $context What filter to use, 'raw', 'display', etc.
- * @return mixed Same type as $value after $value has been sanitized.
+ * @return mixed Value after $value has been sanitized.
  */
 function sanitize_category_field( $field, $value, $cat_id, $context ) {
 	return sanitize_term_field( $field, $value, $cat_id, 'category', $context );
diff --git a/wp-includes/class-wp-comment-query.php b/wp-includes/class-wp-comment-query.php
index 6b72bc88d9..5b0ce51dab 100644
--- a/wp-includes/class-wp-comment-query.php
+++ b/wp-includes/class-wp-comment-query.php
@@ -159,7 +159,6 @@ class WP_Comment_Query {
 	 *                                                      Default null.
 	 *     @type string          $fields                    Comment fields to return. Accepts 'ids' for comment IDs
 	 *                                                      only or empty for all fields. Default empty.
-	 *     @type int             $ID                        Currently unused.
 	 *     @type array           $include_unapproved        Array of IDs or email addresses of users whose unapproved
 	 *                                                      comments will be returned by the query regardless of
 	 *                                                      `$status`. Default empty.
@@ -223,7 +222,6 @@ class WP_Comment_Query {
 	 *                                                      Default empty.
 	 *     @type int[]           $post_author__not_in       Array of author IDs *not* to retrieve comments for.
 	 *                                                      Default empty.
-	 *     @type int             $post_ID                   Currently unused.
 	 *     @type int             $post_id                   Limit results to those affiliated with a given post ID.
 	 *                                                      Default 0.
 	 *     @type int[]           $post__in                  Array of post IDs to include affiliated comments for.
diff --git a/wp-includes/class-wp-http.php b/wp-includes/class-wp-http.php
index 3dca28536e..73be956f4d 100644
--- a/wp-includes/class-wp-http.php
+++ b/wp-includes/class-wp-http.php
@@ -687,8 +687,8 @@ class WP_Http {
 	 *     then a numbered array is returned as the value of that header-key.
 	 *
 	 *     @type array            $response {
-	 *          @type int    $code    The response status code. Default 0.
-	 *          @type string $message The response message. Default empty.
+	 *         @type int    $code    The response status code. Default 0.
+	 *         @type string $message The response message. Default empty.
 	 *     }
 	 *     @type array            $newheaders The processed header data as a multidimensional array.
 	 *     @type WP_Http_Cookie[] $cookies    If the original headers contain the 'Set-Cookie' key,
diff --git a/wp-includes/class-wp-query.php b/wp-includes/class-wp-query.php
index fb1fea61fb..cc1bff5320 100644
--- a/wp-includes/class-wp-query.php
+++ b/wp-includes/class-wp-query.php
@@ -665,7 +665,7 @@ class WP_Query {
 	 *                                                    excludes stickies from 'post__in'. Accepts 1|true, 0|false.
 	 *                                                    Default false.
 	 *     @type int             $m                       Combination YearMonth. Accepts any four-digit year and month
-	 *                                                    numbers 1-12. Default empty.
+	 *                                                    numbers 01-12. Default empty.
 	 *     @type string|string[] $meta_key                Meta key or keys to filter by.
 	 *     @type string|string[] $meta_value              Meta value or values to filter by.
 	 *     @type string          $meta_compare            MySQL operator used for comparing the meta value.
diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php
index 2933069025..da4c2d8ff0 100644
--- a/wp-includes/link-template.php
+++ b/wp-includes/link-template.php
@@ -4016,7 +4016,7 @@ function wp_get_shortlink( $id = 0, $context = 'post', $allow_slugs = true ) {
 	/**
 	 * Filters whether to preempt generating a shortlink for the given post.
 	 *
-	 * Returning a truthy value from the filter will effectively short-circuit
+	 * Returning a value other than false from the filter will short-circuit
 	 * the shortlink generation process, returning that value instead.
 	 *
 	 * @since 3.0.0
diff --git a/wp-includes/media.php b/wp-includes/media.php
index 51c49f83d2..456cd7c988 100644
--- a/wp-includes/media.php
+++ b/wp-includes/media.php
@@ -4535,9 +4535,8 @@ function wp_enqueue_media( $args = array() ) {
 	 *
 	 * @link https://core.trac.wordpress.org/ticket/31071
 	 *
-	 * @param array|null $months An array of objects with `month` and `year`
-	 *                           properties, or `null` (or any other non-array value)
-	 *                           for default behavior.
+	 * @param stdClass[]|null $months An array of objects with `month` and `year`
+	 *                                properties, or `null` for default behavior.
 	 */
 	$months = apply_filters( 'media_library_months_with_files', null );
 	if ( ! is_array( $months ) ) {
diff --git a/wp-includes/meta.php b/wp-includes/meta.php
index adbf4ba9c6..420e0f1f9b 100644
--- a/wp-includes/meta.php
+++ b/wp-includes/meta.php
@@ -1635,7 +1635,7 @@ function unregister_meta_key( $object_type, $meta_key, $object_subtype = '' ) {
 }
 
 /**
- * Retrieves a list of registered meta keys for an object type.
+ * Retrieves a list of registered metadata args for an object type, keyed by their meta keys.
  *
  * @since 4.6.0
  * @since 4.9.8 The `$object_subtype` parameter was added.
@@ -1643,7 +1643,7 @@ function unregister_meta_key( $object_type, $meta_key, $object_subtype = '' ) {
  * @param string $object_type    Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
  *                               or any other object type with an associated meta table.
  * @param string $object_subtype Optional. The subtype of the object type.
- * @return string[] List of registered meta keys.
+ * @return array[] List of registered metadata args, keyed by their meta keys.
  */
 function get_registered_meta_keys( $object_type, $object_subtype = '' ) {
 	global $wp_meta_keys;
diff --git a/wp-includes/option.php b/wp-includes/option.php
index 40cae639e9..96ed00cb95 100644
--- a/wp-includes/option.php
+++ b/wp-includes/option.php
@@ -114,8 +114,8 @@ function get_option( $option, $default = false ) {
 	 *
 	 * The dynamic portion of the hook name, `$option`, refers to the option name.
 	 *
-	 * Returning a truthy value from the filter will effectively short-circuit retrieval
-	 * and return the passed value instead.
+	 * Returning a value other than false from the filter will short-circuit retrieval
+	 * and return that value instead.
 	 *
 	 * @since 1.5.0
 	 * @since 4.4.0 The `$option` parameter was added.
@@ -832,8 +832,8 @@ function get_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 false from the filter will short-circuit retrieval
+	 * and return that value instead.
 	 *
 	 * @since 2.8.0
 	 * @since 4.4.0 The `$transient` parameter was added
@@ -1004,6 +1004,8 @@ function set_transient( $transient, $value, $expiration = 0 ) {
 /**
  * Deletes all expired transients.
  *
+ * Note that this function won't do anything if an external object cache is in use.
+ *
  * The multi-table delete syntax is used to delete the transient record
  * from table a, and the corresponding transient_timeout record from table b.
  *
@@ -1132,9 +1134,9 @@ function get_user_setting( $name, $default = false ) {
 /**
  * Adds or updates user interface setting.
  *
- * Both $name and $value can contain only ASCII letters, numbers, hyphens, and underscores.
+ * Both `$name` and `$value` can contain only ASCII letters, numbers, hyphens, and underscores.
  *
- * This function has to be used before any output has started as it calls setcookie().
+ * This function has to be used before any output has started as it calls `setcookie()`.
  *
  * @since 2.8.0
  *
@@ -1159,7 +1161,7 @@ function set_user_setting( $name, $value ) {
  *
  * Deleting settings would reset them to the defaults.
  *
- * This function has to be used before any output has started as it calls setcookie().
+ * This function has to be used before any output has started as it calls `setcookie()`.
  *
  * @since 2.7.0
  *
@@ -1389,8 +1391,8 @@ function get_network_option( $network_id, $option, $default = false ) {
 	 *
 	 * The dynamic portion of the hook name, `$option`, refers to the option name.
 	 *
-	 * Returning a truthy value from the filter will effectively short-circuit retrieval
-	 * and return the passed value instead.
+	 * Returning a value other than false from the filter will short-circuit retrieval
+	 * and return that value instead.
 	 *
 	 * @since 2.9.0 As 'pre_site_option_' . $key
 	 * @since 3.0.0
@@ -1420,7 +1422,7 @@ function get_network_option( $network_id, $option, $default = false ) {
 	if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) {
 
 		/**
-		 * Filters a specific default network option.
+		 * Filters the value of a specific default network option.
 		 *
 		 * The dynamic portion of the hook name, `$option`, refers to the option name.
 		 *
diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php
index 2931fd892c..2ec21126e0 100644
--- a/wp-includes/pluggable.php
+++ b/wp-includes/pluggable.php
@@ -895,6 +895,7 @@ if ( ! function_exists( 'wp_parse_auth_cookie' ) ) :
 	 * Parses a cookie into its components.
 	 *
 	 * @since 2.7.0
+	 * @since 4.0.0 The `$token` element was added to the return value.
 	 *
 	 * @param string $cookie Authentication cookie.
 	 * @param string $scheme Optional. The cookie scheme to use: 'auth', 'secure_auth', or 'logged_in'.
diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php
index 698a0699cc..76a9ada576 100644
--- a/wp-includes/taxonomy.php
+++ b/wp-includes/taxonomy.php
@@ -3105,8 +3105,8 @@ function wp_unique_term_slug( $slug, $term ) {
  *
  * @param int          $term_id  The ID of the term.
  * @param string       $taxonomy The taxonomy of the term.
- * @param array|string $args {
- *     Optional. Array or string of arguments for updating a term.
+ * @param array        $args {
+ *     Optional. Array of arguments for updating a term.
  *
  *     @type string $alias_of    Slug of the term to make this term an alias of.
  *                               Default empty string. Accepts a term slug.
diff --git a/wp-includes/version.php b/wp-includes/version.php
index def934daaa..34a5c09784 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.1-alpha-53826';
+$wp_version = '6.1-alpha-53827';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
diff --git a/wp-login.php b/wp-login.php
index 43386688ce..b0dd2b2f6d 100644
--- a/wp-login.php
+++ b/wp-login.php
@@ -348,6 +348,8 @@ function login_footer( $input_id = '' ) {
 					/**
 					 * Filters default arguments for the Languages select input on the login screen.
 					 *
+					 * The arguments get passed to the wp_dropdown_languages() function.
+					 *
 					 * @since 5.9.0
 					 *
 					 * @param array $args Arguments for the Languages select input on the login screen.