From 53da9208dd6c5d1149354f230329ae949b79504f Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Sun, 3 Jan 2021 21:57:09 +0000
Subject: [PATCH] Docs: Various docblock corrections particularly relating to
 boolean types.

See #51800

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


git-svn-id: http://core.svn.wordpress.org/trunk@49625 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-admin/includes/class-wp-community-events.php | 6 +++---
 wp-admin/includes/dashboard.php                 | 2 +-
 wp-admin/includes/deprecated.php                | 2 +-
 wp-admin/includes/image.php                     | 2 +-
 wp-admin/includes/translation-install.php       | 6 +++---
 wp-includes/category-template.php               | 2 +-
 wp-includes/class-wp-hook.php                   | 3 +++
 wp-includes/class-wp-image-editor-imagick.php   | 2 +-
 wp-includes/class-wp-metadata-lazyloader.php    | 4 ++--
 wp-includes/comment.php                         | 6 +++---
 wp-includes/formatting.php                      | 4 ++--
 wp-includes/functions.php                       | 2 +-
 wp-includes/plugin.php                          | 4 ++--
 wp-includes/post.php                            | 5 ++---
 wp-includes/user.php                            | 2 +-
 wp-includes/version.php                         | 2 +-
 16 files changed, 28 insertions(+), 26 deletions(-)

diff --git a/wp-admin/includes/class-wp-community-events.php b/wp-admin/includes/class-wp-community-events.php
index 40807712cf..6a12d520f6 100644
--- a/wp-admin/includes/class-wp-community-events.php
+++ b/wp-admin/includes/class-wp-community-events.php
@@ -39,9 +39,9 @@ class WP_Community_Events {
 	 * @since 4.8.0
 	 *
 	 * @param int        $user_id       WP user ID.
-	 * @param bool|array $user_location Stored location data for the user.
-	 *                                  false to pass no location;
-	 *                                  array to pass a location {
+	 * @param false|array $user_location {
+	 *     Stored location data for the user. false to pass no location.
+	 *
 	 *     @type string $description The name of the location
 	 *     @type string $latitude    The latitude in decimal degrees notation, without the degree
 	 *                               symbol. e.g.: 47.615200.
diff --git a/wp-admin/includes/dashboard.php b/wp-admin/includes/dashboard.php
index 6855aa6c96..573affff1a 100644
--- a/wp-admin/includes/dashboard.php
+++ b/wp-admin/includes/dashboard.php
@@ -1538,7 +1538,7 @@ function wp_dashboard_primary_output( $widget_id, $feeds ) {
  *
  * @since 3.0.0
  *
- * @return bool|null True if not multisite, user can't upload files, or the space check option is disabled.
+ * @return true|void True if not multisite, user can't upload files, or the space check option is disabled.
  */
 function wp_dashboard_quota() {
 	if ( ! is_multisite() || ! current_user_can( 'upload_files' ) || get_site_option( 'upload_space_check_disabled' ) ) {
diff --git a/wp-admin/includes/deprecated.php b/wp-admin/includes/deprecated.php
index 7caec42e54..dc39eca8e3 100644
--- a/wp-admin/includes/deprecated.php
+++ b/wp-admin/includes/deprecated.php
@@ -128,7 +128,7 @@ function get_real_file_to_edit( $file ) {
  * @param int $parent        Optional. Parent ID to retrieve categories for. Default 0.
  * @param int $level         Optional. Number of levels deep to display. Default 0.
  * @param array $categories  Optional. Categories to include in the control. Default 0.
- * @return bool|null False if no categories were found.
+ * @return false|void False if no categories were found.
  */
 function wp_dropdown_cats( $currentcat = 0, $currentparent = 0, $parent = 0, $level = 0, $categories = 0 ) {
 	_deprecated_function( __FUNCTION__, '3.0.0', 'wp_dropdown_categories()' );
diff --git a/wp-admin/includes/image.php b/wp-admin/includes/image.php
index 522e310c51..2417717188 100644
--- a/wp-admin/includes/image.php
+++ b/wp-admin/includes/image.php
@@ -1014,7 +1014,7 @@ function _load_image_to_edit_path( $attachment_id, $size = 'full' ) {
 		 *
 		 * @since 3.1.0
 		 *
-		 * @param string       $image_url     Current image URL.
+		 * @param string|false $image_url     Current image URL.
 		 * @param int          $attachment_id Attachment ID.
 		 * @param string|int[] $size          Requested image size. Can be any registered image size name, or
 		 *                                    an array of width and height values in pixels (in that order).
diff --git a/wp-admin/includes/translation-install.php b/wp-admin/includes/translation-install.php
index c03f69921d..a2733e169b 100644
--- a/wp-admin/includes/translation-install.php
+++ b/wp-admin/includes/translation-install.php
@@ -29,9 +29,9 @@ function translations_api( $type, $args = null ) {
 	 *
 	 * @since 4.0.0
 	 *
-	 * @param bool|array  $result The result object. Default false.
-	 * @param string      $type   The type of translations being requested.
-	 * @param object      $args   Translation API arguments.
+	 * @param false|object $result The result object. Default false.
+	 * @param string       $type   The type of translations being requested.
+	 * @param object       $args   Translation API arguments.
 	 */
 	$res = apply_filters( 'translations_api', false, $type, $args );
 
diff --git a/wp-includes/category-template.php b/wp-includes/category-template.php
index 727093468c..2da86c4b68 100644
--- a/wp-includes/category-template.php
+++ b/wp-includes/category-template.php
@@ -815,7 +815,7 @@ function default_topic_count_scale( $count ) {
  *     @type string   $order                      How to order the tags. Accepts 'ASC' (ascending),
  *                                                'DESC' (descending), or 'RAND' (random). Default 'ASC'.
  *     @type int|bool $filter                     Whether to enable filtering of the final output
- *                                                via {@see 'wp_generate_tag_cloud'}. Default 1|true.
+ *                                                via {@see 'wp_generate_tag_cloud'}. Default 1.
  *     @type string   $topic_count_text           Nooped plural text from _n_noop() to supply to
  *                                                tag counts. Default null.
  *     @type callable $topic_count_text_callback  Callback used to generate nooped plural text for
diff --git a/wp-includes/class-wp-hook.php b/wp-includes/class-wp-hook.php
index 5f9fa2fb83..21decb003c 100644
--- a/wp-includes/class-wp-hook.php
+++ b/wp-includes/class-wp-hook.php
@@ -187,6 +187,9 @@ final class WP_Hook implements Iterator, ArrayAccess {
 	/**
 	 * Checks if a specific action has been registered for this hook.
 	 *
+	 * When using the $function_to_check argument, this function may return a non-boolean value
+	 * that evaluates to false (e.g. 0), so use the === operator for testing the return value.
+	 *
 	 * @since 4.7.0
 	 *
 	 * @param string        $tag               Optional. The name of the filter hook. Default empty.
diff --git a/wp-includes/class-wp-image-editor-imagick.php b/wp-includes/class-wp-image-editor-imagick.php
index b5e775ab8b..e1e16bcea3 100644
--- a/wp-includes/class-wp-image-editor-imagick.php
+++ b/wp-includes/class-wp-image-editor-imagick.php
@@ -291,7 +291,7 @@ class WP_Image_Editor_Imagick extends WP_Image_Editor {
 	 * @param int    $dst_h       The destination height.
 	 * @param string $filter_name Optional. The Imagick filter to use when resizing. Default 'FILTER_TRIANGLE'.
 	 * @param bool   $strip_meta  Optional. Strip all profiles, excluding color profiles, from the image. Default true.
-	 * @return bool|WP_Error
+	 * @return void|WP_Error
 	 */
 	protected function thumbnail_image( $dst_w, $dst_h, $filter_name = 'FILTER_TRIANGLE', $strip_meta = true ) {
 		$allowed_filters = array(
diff --git a/wp-includes/class-wp-metadata-lazyloader.php b/wp-includes/class-wp-metadata-lazyloader.php
index 0a1a5123ed..67eacc99ae 100644
--- a/wp-includes/class-wp-metadata-lazyloader.php
+++ b/wp-includes/class-wp-metadata-lazyloader.php
@@ -70,7 +70,7 @@ class WP_Metadata_Lazyloader {
 	 *
 	 * @param string $object_type Type of object whose meta is to be lazy-loaded. Accepts 'term' or 'comment'.
 	 * @param array  $object_ids  Array of object IDs.
-	 * @return bool|WP_Error True on success, WP_Error on failure.
+	 * @return void|WP_Error WP_Error on failure.
 	 */
 	public function queue_objects( $object_type, $object_ids ) {
 		if ( ! isset( $this->settings[ $object_type ] ) ) {
@@ -110,7 +110,7 @@ class WP_Metadata_Lazyloader {
 	 * @since 4.5.0
 	 *
 	 * @param string $object_type Object type. Accepts 'comment' or 'term'.
-	 * @return bool|WP_Error True on success, WP_Error on failure.
+	 * @return void|WP_Error WP_Error on failure.
 	 */
 	public function reset_queue( $object_type ) {
 		if ( ! isset( $this->settings[ $object_type ] ) ) {
diff --git a/wp-includes/comment.php b/wp-includes/comment.php
index ac37540be0..581271fdd0 100644
--- a/wp-includes/comment.php
+++ b/wp-includes/comment.php
@@ -2406,9 +2406,9 @@ function wp_set_comment_status( $comment_id, $comment_status, $wp_error = false
 	 *
 	 * @since 1.5.0
 	 *
-	 * @param int         $comment_id     Comment ID.
-	 * @param string|bool $comment_status Current comment status. Possible values include
-	 *                                    'hold', 'approve', 'spam', 'trash', or false.
+	 * @param int    $comment_id     Comment ID.
+	 * @param string $comment_status Current comment status. Possible values include
+	 *                               'hold', '0', 'approve', '1, 'spam', and 'trash'.
 	 */
 	do_action( 'wp_set_comment_status', $comment->comment_ID, $comment_status );
 
diff --git a/wp-includes/formatting.php b/wp-includes/formatting.php
index 6bc3c2b89a..55177d45a1 100644
--- a/wp-includes/formatting.php
+++ b/wp-includes/formatting.php
@@ -5545,8 +5545,8 @@ function wp_slash( $value ) {
  *
  * @since 3.6.0
  *
- * @param string|string[] $value String or array of strings to unslash.
- * @return string|string[] Unslashed $value
+ * @param string|array $value String or array of strings to unslash.
+ * @return string|array Unslashed $value
  */
 function wp_unslash( $value ) {
 	return stripslashes_deep( $value );
diff --git a/wp-includes/functions.php b/wp-includes/functions.php
index 0ea8c9a6a7..7cd072e660 100644
--- a/wp-includes/functions.php
+++ b/wp-includes/functions.php
@@ -837,7 +837,7 @@ function wp_extract_urls( $content ) {
  *
  * @param string|null $content Post content. If `null`, the `post_content` field from `$post` is used.
  * @param int|WP_Post $post    Post ID or post object.
- * @return null|bool Returns false if post is not found.
+ * @return void|false Returns false if post is not found.
  */
 function do_enclose( $content, $post ) {
 	global $wpdb;
diff --git a/wp-includes/plugin.php b/wp-includes/plugin.php
index f6bedc7d5a..97053d6815 100644
--- a/wp-includes/plugin.php
+++ b/wp-includes/plugin.php
@@ -133,7 +133,7 @@ function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1
  *                   anything registered. When checking a specific function, the priority of that
  *                   hook is returned, or false if the function is not attached. When using the
  *                   $function_to_check argument, this function may return a non-boolean value
- *                   that evaluates to false (e.g.) 0, so use the === operator for testing the
+ *                   that evaluates to false (e.g. 0), so use the === operator for testing the
  *                   return value.
  */
 function has_filter( $tag, $function_to_check = false ) {
@@ -566,7 +566,7 @@ function do_action_ref_array( $tag, $args ) {
  *                  anything registered. When checking a specific function, the priority of that
  *                  hook is returned, or false if the function is not attached. When using the
  *                  $function_to_check argument, this function may return a non-boolean value
- *                  that evaluates to false (e.g.) 0, so use the === operator for testing the
+ *                  that evaluates to false (e.g. 0), so use the === operator for testing the
  *                  return value.
  */
 function has_action( $tag, $function_to_check = false ) {
diff --git a/wp-includes/post.php b/wp-includes/post.php
index 23bfc6d68a..d4237f0f96 100644
--- a/wp-includes/post.php
+++ b/wp-includes/post.php
@@ -6103,9 +6103,8 @@ function wp_get_attachment_metadata( $attachment_id = 0, $unfiltered = false ) {
 	 *
 	 * @since 2.1.0
 	 *
-	 * @param array|bool $data          Array of meta data for the given attachment, or false
-	 *                                  if the object does not exist.
-	 * @param int        $attachment_id Attachment post ID.
+	 * @param array $data          Array of meta data for the given attachment.
+	 * @param int   $attachment_id Attachment post ID.
 	 */
 	return apply_filters( 'wp_get_attachment_metadata', $data, $attachment_id );
 }
diff --git a/wp-includes/user.php b/wp-includes/user.php
index 134258d4fe..aa5d6f5ffc 100644
--- a/wp-includes/user.php
+++ b/wp-includes/user.php
@@ -1537,7 +1537,7 @@ function sanitize_user_field( $field, $value, $user_id, $context ) {
  * @since 3.0.0
  *
  * @param object|WP_User $user User object or database row to be cached
- * @return bool|null Returns false on failure.
+ * @return false|void Returns false on failure.
  */
 function update_user_caches( $user ) {
 	if ( $user instanceof WP_User ) {
diff --git a/wp-includes/version.php b/wp-includes/version.php
index d03d382a84..9bf0fc75e1 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.7-alpha-49925';
+$wp_version = '5.7-alpha-49926';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.