Docs: In various `@return` tags, list the expected type first, instead of `false`.

Follow-up to [46696].

See #48303.
Built from https://develop.svn.wordpress.org/trunk@47060


git-svn-id: http://core.svn.wordpress.org/trunk@46860 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/includes/class-core-upgrader.php

@@ -57,7 +57,7 @@ class Core_Upgrader extends WP_Upgrader {
 	 *        @type bool $do_rollback      Whether to perform this "upgrade" as a rollback.
 	 *                                     Default false.
 	 * }
-	 * @return null|false|WP_Error False or WP_Error on failure, null on success.
+	 * @return null|false|WP_Error Null on success, false or WP_Error on failure.
 	 */
 	public function upgrade( $current, $args = array() ) {
 		global $wp_filesystem;

wp-admin/includes/class-wp-community-events.php

@@ -229,7 +229,7 @@ class WP_Community_Events {
 	 *
 	 * @since 4.8.0
 	 *
-	 * @return false|string The anonymized address on success; the given address
+	 * @return string|false The anonymized address on success; the given address
 	 *                      or false on failure.
 	 */
 	public static function get_unsafe_client_ip() {
@@ -341,8 +341,8 @@ class WP_Community_Events {
 	 *
 	 * @since 4.8.0
 	 *
-	 * @return false|array false on failure; an array containing `location`
+	 * @return array|false An array containing `location` and `events` items
-	 *                     and `events` items on success.
+	 *                     on success, false on failure.
 	 */
 	public function get_cached_events() {
 		$cached_response = get_site_transient( $this->get_events_transient_key( $this->user_location ) );

wp-admin/includes/class-wp-upgrader-skin.php

@@ -81,7 +81,7 @@ class WP_Upgrader_Skin {
 	 * @param string        $context                      Optional. Full path to the directory that is tested
 	 *                                                    for being writable. Default empty.
 	 * @param bool          $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable. Default false.
-	 * @return bool False on failure, true on success.
+	 * @return bool True on success, false on failure.
 	 */
 	public function request_filesystem_credentials( $error = false, $context = '', $allow_relaxed_file_ownership = false ) {
 		$url = $this->options['url'];

wp-admin/includes/file.php

@@ -1189,8 +1189,8 @@ function verify_file_md5( $filename, $expected_md5 ) {
  * @param string       $filename            The file to validate.
  * @param string|array $signatures          A Signature provided for the file.
  * @param string       $filename_for_errors A friendly filename for errors. Optional.
- *
+ * @return bool|WP_Error True on success, false if verification not attempted,
- * @return bool|WP_Error true on success, false if verification not attempted, or WP_Error describing an error condition.
+ *                       or WP_Error describing an error condition.
  */
 function verify_file_signature( $filename, $signatures, $filename_for_errors = false ) {
 	if ( ! $filename_for_errors ) {
@@ -1964,12 +1964,11 @@ function request_filesystem_credentials( $form_post, $type = '', $error = false,
 	 * @param mixed         $output                       Form output to return instead. Default empty.
 	 * @param string        $form_post                    The URL to post the form to.
 	 * @param string        $type                         Chosen type of filesystem.
-	 * @param bool|WP_Error $error                        Optional. Whether the current request has failed to connect,
+	 * @param bool|WP_Error $error                        Whether the current request has failed to connect,
-	 *                                                    or an error object. Default false.
+	 *                                                    or an error object.
 	 * @param string        $context                      Full path to the directory that is tested for
 	 *                                                    being writable.
 	 * @param bool          $allow_relaxed_file_ownership Whether to allow Group/World writable.
-	 *                                                    Default false.
 	 * @param array         $extra_fields                 Extra POST fields.
 	 */
 	$req_cred = apply_filters( 'request_filesystem_credentials', '', $form_post, $type, $error, $context, $extra_fields, $allow_relaxed_file_ownership );
@@ -2092,7 +2091,8 @@ function request_filesystem_credentials( $form_post, $type = '', $error = false,
 	 * @param string[]      $types       Types of connections.
 	 * @param array         $credentials Credentials to connect with.
 	 * @param string        $type        Chosen filesystem method.
-	 * @param bool|WP_Error $error       Error object or status.
+	 * @param bool|WP_Error $error       Whether the current request has failed to connect,
+	 *                                   or an error object.
 	 * @param string        $context     Full path to the directory that is tested for being writable.
 	 */
 	$types = apply_filters( 'fs_ftp_connection_types', $types, $credentials, $type, $error, $context );

wp-admin/includes/plugin.php

@@ -613,7 +613,7 @@ function is_network_only_plugin( $plugin ) {
  * @param bool   $network_wide Optional. Whether to enable the plugin for all sites in the network
  *                             or just the current site. Multisite only. Default false.
  * @param bool   $silent       Optional. Whether to prevent calling activation hooks. Default false.
- * @return null|WP_Error WP_Error on invalid file or null on success.
+ * @return null|WP_Error Null on success, WP_Error on invalid file.
  */
 function activate_plugin( $plugin, $redirect = '', $network_wide = false, $silent = false ) {
 	$plugin = plugin_basename( trim( $plugin ) );
@@ -1342,7 +1342,7 @@ function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $func
  *                              to be compatible with sanitize_key().
  * @param callable $function    The function to be called to output the content for this page.
  * @param int      $position    The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv,
@@ -1454,7 +1454,7 @@ function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability,
  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
  * @param callable $function   The function to be called to output the content for this page.
  * @param int      $position   The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
@@ -1478,7 +1478,7 @@ function add_management_page( $page_title, $menu_title, $capability, $menu_slug,
  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
  * @param callable $function   The function to be called to output the content for this page.
  * @param int      $position   The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
@@ -1502,7 +1502,7 @@ function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $f
  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
  * @param callable $function   The function to be called to output the content for this page.
  * @param int      $position   The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
@@ -1526,7 +1526,7 @@ function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $fun
  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
  * @param callable $function   The function to be called to output the content for this page.
  * @param int      $position   The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
@@ -1550,7 +1550,7 @@ function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $f
  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
  * @param callable $function   The function to be called to output the content for this page.
  * @param int      $position   The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	if ( current_user_can( 'edit_users' ) ) {
@@ -1579,7 +1579,7 @@ function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $fun
  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
  * @param callable $function   The function to be called to output the content for this page.
  * @param int      $position   The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
@@ -1603,7 +1603,7 @@ function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug,
  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
  * @param callable $function   The function to be called to output the content for this page.
  * @param int      $position   The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
@@ -1627,7 +1627,7 @@ function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $fun
  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
  * @param callable $function   The function to be called to output the content for this page.
  * @param int      $position   The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
@@ -1651,7 +1651,7 @@ function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $fun
  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
  * @param callable $function   The function to be called to output the content for this page.
  * @param int      $position   The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
@@ -1675,7 +1675,7 @@ function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $fun
  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
  * @param callable $function   The function to be called to output the content for this page.
  * @param int      $position   The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
@@ -1699,7 +1699,7 @@ function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $fun
  * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
  * @param callable $function   The function to be called to output the content for this page.
  * @param int      $position   The position in the menu order this item should appear.
- * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
+ * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
  */
 function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
 	return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );

wp-admin/includes/template.php

@@ -76,6 +76,7 @@ function wp_category_checklist( $post_id = 0, $descendants_and_self = 0, $select
  *     @type bool   $echo                 Whether to echo the generated markup. False to return the markup instead
  *                                        of echoing it. Default true.
  * }
+ * @return string HTML list of input elements.
  */
 function wp_terms_checklist( $post_id = 0, $args = array() ) {
 	$defaults = array(

wp-admin/includes/theme.php

@@ -163,7 +163,7 @@ function theme_update_available( $theme ) {
  * @staticvar object $themes_update
  *
  * @param WP_Theme $theme WP_Theme object.
- * @return false|string HTML for the update link, or false if invalid info was passed.
+ * @return string|false HTML for the update link, or false if invalid info was passed.
  */
 function get_theme_update_available( $theme ) {
 	static $themes_update = null;

wp-admin/includes/update-core.php

@@ -880,7 +880,7 @@ $_new_bundled_files = array(
  *
  * @param string $from New release unzipped path.
  * @param string $to   Path to old WordPress installation.
- * @return null|WP_Error WP_Error on failure, null on success.
+ * @return null|WP_Error Null on success, WP_Error on failure.
  */
 function update_core( $from, $to ) {
 	global $wp_filesystem, $_old_files, $_new_bundled_files, $wpdb;
@@ -1314,7 +1314,7 @@ function update_core( $from, $to ) {
  * @param string   $from      Source directory.
  * @param string   $to        Destination directory.
  * @param string[] $skip_list Array of files/folders to skip copying.
- * @return true|WP_Error WP_Error on failure, true on success.
+ * @return true|WP_Error True on success, WP_Error on failure.
  */
 function _copy_dir( $from, $to, $skip_list = array() ) {
 	global $wp_filesystem;

wp-admin/includes/update.php

@@ -276,7 +276,7 @@ function core_update_footer( $msg = '' ) {
  * @since 2.3.0
  *
  * @global string $pagenow
- * @return false|void
+ * @return void|false
  */
 function update_nag() {
 	if ( is_multisite() && ! current_user_can( 'update_core' ) ) {
@@ -409,7 +409,7 @@ function wp_plugin_update_rows() {
  *
  * @param string $file        Plugin basename.
  * @param array  $plugin_data Plugin information.
- * @return false|void
+ * @return void|false
  */
 function wp_plugin_update_row( $file, $plugin_data ) {
 	$current = get_site_transient( 'update_plugins' );
@@ -611,7 +611,7 @@ function wp_theme_update_rows() {
  *
  * @param string   $theme_key Theme stylesheet.
  * @param WP_Theme $theme     Theme object.
- * @return false|void
+ * @return void|false
  */
 function wp_theme_update_row( $theme_key, $theme ) {
 	$current = get_site_transient( 'update_themes' );
@@ -720,7 +720,7 @@ function wp_theme_update_row( $theme_key, $theme ) {
  * @since 2.7.0
  *
  * @global int $upgrading
- * @return false|void
+ * @return void|false
  */
 function maintenance_nag() {
 	include( ABSPATH . WPINC . '/version.php' ); // include an unmodified $wp_version

wp-admin/includes/upgrade.php

@@ -3061,7 +3061,7 @@ function make_site_theme_from_oldschool( $theme_name, $template ) {
  *
  * @param string $theme_name The name of the theme.
  * @param string $template   The directory name of the theme.
- * @return false|void
+ * @return void|false
  */
 function make_site_theme_from_default( $theme_name, $template ) {
 	$site_dir    = WP_CONTENT_DIR . "/themes/$template";
@@ -3136,7 +3136,7 @@ function make_site_theme_from_default( $theme_name, $template ) {
  *
  * @since 1.5.0
  *
- * @return false|string
+ * @return string|false
  */
 function make_site_theme() {
 	// Name the theme after the blog.

wp-admin/install-helper.php

@@ -114,7 +114,7 @@ endif;
  * @param string $table_name Table name
  * @param string $column_name Column name
  * @param string $drop_ddl SQL statement to drop column.
- * @return bool False on failure, true on success or doesn't exist.
+ * @return bool True on success or if the column doesn't exist, false on failure.
  */
 function maybe_drop_column( $table_name, $column_name, $drop_ddl ) {
 	global $wpdb;

wp-includes/author-template.php

@@ -407,7 +407,7 @@ function get_author_posts_url( $author_id, $author_nicename = '' ) {
  *     @type array|string $exclude       Array or comma/space-separated list of author IDs to exclude. Default empty.
  *     @type array|string $include       Array or comma/space-separated list of author IDs to include. Default empty.
  * }
- * @return string|void The output, if echo is set to false.
+ * @return void|string Void if 'echo' argument is true, list of authors if 'echo' is false.
  */
 function wp_list_authors( $args = '' ) {
 	global $wpdb;
@@ -518,10 +518,11 @@ function wp_list_authors( $args = '' ) {
 
 	$return = rtrim( $return, ', ' );
 
-	if ( ! $args['echo'] ) {
+	if ( $args['echo'] ) {
+		echo $return;
+	} else {
 		return $return;
 	}
-	echo $return;
 }
 
 /**

wp-includes/bookmark-template.php

@@ -202,7 +202,7 @@ function _walk_bookmarks( $bookmarks, $args = '' ) {
  *                                      $categorize is true. Accepts 'ASC' (ascending) or 'DESC' (descending).
  *                                      Default 'ASC'.
  * }
- * @return string|void Will only return if echo option is set to not echo. Default is not return anything.
+ * @return void|string Void if 'echo' argument is true, HTML list of bookmarks if 'echo' is false.
  */
 function wp_list_bookmarks( $args = '' ) {
 	$defaults = array(
@@ -316,8 +316,9 @@ function wp_list_bookmarks( $args = '' ) {
 	 */
 	$html = apply_filters( 'wp_list_bookmarks', $output );
 
-	if ( ! $parsed_args['echo'] ) {
+	if ( $parsed_args['echo'] ) {
+		echo $html;
+	} else {
 		return $html;
 	}
-	echo $html;
 }

wp-includes/cache.php

@@ -22,7 +22,7 @@
  *                           to be used across groups. Default empty.
  * @param int        $expire Optional. When the cache data should expire, in seconds.
  *                           Default 0 (no expiration).
- * @return bool False if cache key and group already exist, true on success.
+ * @return bool True on success, false if cache key and group already exist.
  */
 function wp_cache_add( $key, $data, $group = '', $expire = 0 ) {
 	global $wp_object_cache;
@@ -58,7 +58,7 @@ function wp_cache_close() {
  * @param int|string $key    The cache key to decrement.
  * @param int        $offset Optional. The amount by which to decrement the item's value. Default 1.
  * @param string     $group  Optional. The group the key is in. Default empty.
- * @return false|int False on failure, the item's new value on success.
+ * @return int|false The item's new value on success, false on failure.
  */
 function wp_cache_decr( $key, $offset = 1, $group = '' ) {
 	global $wp_object_cache;
@@ -92,7 +92,7 @@ function wp_cache_delete( $key, $group = '' ) {
  * @see WP_Object_Cache::flush()
  * @global WP_Object_Cache $wp_object_cache Object cache global instance.
  *
- * @return bool False on failure, true on success
+ * @return bool True on success, false on failure.
  */
 function wp_cache_flush() {
 	global $wp_object_cache;
@@ -134,7 +134,7 @@ function wp_cache_get( $key, $group = '', $force = false, &$found = null ) {
  * @param int|string $key    The key for the cache contents that should be incremented.
  * @param int        $offset Optional. The amount by which to increment the item's value. Default 1.
  * @param string     $group  Optional. The group the key is in. Default empty.
- * @return false|int False on failure, the item's new value on success.
+ * @return int|false The item's new value on success, false on failure.
  */
 function wp_cache_incr( $key, $offset = 1, $group = '' ) {
 	global $wp_object_cache;
@@ -191,7 +191,7 @@ function wp_cache_replace( $key, $data, $group = '', $expire = 0 ) {
  *                           to be used across groups. Default empty.
  * @param int        $expire Optional. When to expire the cache contents, in seconds.
  *                           Default 0 (no expiration).
- * @return bool False on failure, true on success
+ * @return bool True on success, false on failure.
  */
 function wp_cache_set( $key, $data, $group = '', $expire = 0 ) {
 	global $wp_object_cache;
@@ -396,7 +396,7 @@ class WP_Object_Cache {
 	 * @param mixed      $data   The contents to store in the cache.
 	 * @param string     $group  Optional. Where to group the cache contents. Default 'default'.
 	 * @param int        $expire Optional. When to expire the cache contents. Default 0 (no expiration).
-	 * @return bool False if cache key and group already exist, true on success
+	 * @return bool True on success, false if cache key and group already exist.
 	 */
 	public function add( $key, $data, $group = 'default', $expire = 0 ) {
 		if ( wp_suspend_cache_addition() ) {
@@ -441,7 +441,7 @@ class WP_Object_Cache {
 	 * @param int|string $key    The cache key to decrement.
 	 * @param int        $offset Optional. The amount by which to decrement the item's value. Default 1.
 	 * @param string     $group  Optional. The group the key is in. Default 'default'.
-	 * @return false|int False on failure, the item's new value on success.
+	 * @return int|false The item's new value on success, false on failure.
 	 */
 	public function decr( $key, $offset = 1, $group = 'default' ) {
 		if ( empty( $group ) ) {
@@ -530,7 +530,7 @@ class WP_Object_Cache {
 	 *                           cache. Default false.
 	 * @param bool       $found  Optional. Whether the key was found in the cache (passed by reference).
 	 *                           Disambiguates a return of false, a storable value. Default null.
-	 * @return false|mixed False on failure to retrieve contents or the cache contents on success.
+	 * @return mixed|false The cache contents on success, false on failure to retrieve contents.
 	 */
 	public function get( $key, $group = 'default', $force = false, &$found = null ) {
 		if ( empty( $group ) ) {
@@ -564,7 +564,7 @@ class WP_Object_Cache {
 	 * @param int|string $key    The cache key to increment
 	 * @param int        $offset Optional. The amount by which to increment the item's value. Default 1.
 	 * @param string     $group  Optional. The group the key is in. Default 'default'.
-	 * @return false|int False on failure, the item's new value on success.
+	 * @return int|false The item's new value on success, false on failure.
 	 */
 	public function incr( $key, $offset = 1, $group = 'default' ) {
 		if ( empty( $group ) ) {

wp-includes/canonical.php

@@ -679,7 +679,7 @@ function strip_fragment_from_url( $url ) {
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @return false|string The correct URL if one is found. False on failure.
+ * @return string|false The correct URL if one is found. False on failure.
  */
 function redirect_guess_404_permalink() {
 	global $wpdb;

wp-includes/category-template.php

@@ -478,7 +478,8 @@ function wp_dropdown_categories( $args = '' ) {
  *     @type int|array    $current_category      ID of category, or array of IDs of categories, that should get the
  *                                               'current-cat' class. Default 0.
  *     @type int          $depth                 Category depth. Used for tab indentation. Default 0.
- *     @type bool|int     $echo                  True to echo markup, false to return it. Default 1.
+ *     @type bool|int     $echo                  Whether to echo or return the generated markup. Accepts 0, 1, or their
+ *                                               bool equivalents. Default 1.
  *     @type array|string $exclude               Array or comma/space-separated string of term IDs to exclude.
  *                                               If `$hierarchical` is true, descendants of `$exclude` terms will also
  *                                               be excluded; see `$exclude_tree`. See get_terms().
@@ -493,7 +494,8 @@ function wp_dropdown_categories( $args = '' ) {
  *     @type bool         $hide_title_if_empty   Whether to hide the `$title_li` element if there are no terms in
  *                                               the list. Default false (title will always be shown).
  *     @type string       $separator             Separator between links. Default '<br />'.
- *     @type bool|int     $show_count            Whether to show how many posts are in the category. Default 0.
+ *     @type bool|int     $show_count            Whether to include post counts. Accepts 0, 1, or their bool equivalents.
+ *                                               Default 0.
  *     @type string       $show_option_all       Text to display for showing all categories. Default empty string.
  *     @type string       $show_option_none      Text to display for the 'no categories' option.
  *                                               Default 'No categories'.
@@ -503,9 +505,10 @@ function wp_dropdown_categories( $args = '' ) {
  *     @type string       $title_li              Text to use for the list title `<li>` element. Pass an empty string
  *                                               to disable. Default 'Categories'.
  *     @type bool|int     $use_desc_for_title    Whether to use the category description as the title attribute.
- *                                               Default 1.
+ *                                               Accepts 0, 1, or their bool equivalents. Default 1.
  * }
- * @return false|string HTML list of categories only if 'echo' argument is 0.
+ * @return void|string|false Void if 'echo' argument is true, HTML list of categories if 'echo' is false.
+ *                           False if the taxonomy does not exist.
  */
 function wp_list_categories( $args = '' ) {
 	$defaults = array(
@@ -671,8 +674,8 @@ function wp_list_categories( $args = '' ) {
  *                             associated with the taxonomy.
  *     @type bool   $echo      Whether or not to echo the return value. Default true.
  * }
- * @return void|array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument.
+ * @return void|string|array Void if 'echo' argument is true, or on failure. Otherwise, tag cloud
- *                    Otherwise, this function outputs the tag cloud.
+ *                           as a string or an array, depending on 'format' argument.
  */
 function wp_tag_cloud( $args = '' ) {
 	$defaults = array(
@@ -692,7 +695,8 @@ function wp_tag_cloud( $args = '' ) {
 		'echo'       => true,
 		'show_count' => 0,
 	);
-	$args     = wp_parse_args( $args, $defaults );
+
+	$args = wp_parse_args( $args, $defaults );
 
 	$tags = get_terms(
 		array_merge(
@@ -714,6 +718,7 @@ function wp_tag_cloud( $args = '' ) {
 		} else {
 			$link = get_term_link( intval( $tag->term_id ), $tag->taxonomy );
 		}
+
 		if ( is_wp_error( $link ) ) {
 			return;
 		}
@@ -729,8 +734,8 @@ function wp_tag_cloud( $args = '' ) {
 	 *
 	 * @since 2.3.0
 	 *
-	 * @param string $return HTML output of the tag cloud.
+	 * @param string|array $return Tag cloud as a string or an array, depending on 'format' argument.
-	 * @param array  $args   An array of tag cloud arguments.
+	 * @param array        $args   An array of tag cloud arguments.
 	 */
 	$return = apply_filters( 'wp_tag_cloud', $return, $args );
 
@@ -1265,11 +1270,11 @@ function get_the_terms( $post, $taxonomy ) {
  *
  * @since 2.5.0
  *
- * @param int $id Post ID.
+ * @param int    $id       Post ID.
  * @param string $taxonomy Taxonomy name.
- * @param string $before Optional. Before list.
+ * @param string $before   Optional. Before list.
- * @param string $sep Optional. Separate items using this.
+ * @param string $sep      Optional. Separate items using this.
- * @param string $after Optional. After list.
+ * @param string $after    Optional. After list.
  * @return string|false|WP_Error A list of terms on success, false if there are no terms, WP_Error on failure.
  */
 function get_the_term_list( $id, $taxonomy, $before = '', $sep = '', $after = '' ) {
@@ -1378,12 +1383,12 @@ function get_term_parents_list( $term_id, $taxonomy, $args = array() ) {
  *
  * @since 2.5.0
  *
- * @param int $id Post ID.
+ * @param int    $id       Post ID.
  * @param string $taxonomy Taxonomy name.
- * @param string $before Optional. Before list.
+ * @param string $before   Optional. Before list.
- * @param string $sep Optional. Separate items using this.
+ * @param string $sep      Optional. Separate items using this.
- * @param string $after Optional. After list.
+ * @param string $after    Optional. After list.
- * @return false|void False on WordPress error.
+ * @return void|false False on WordPress error.
  */
 function the_terms( $id, $taxonomy, $before = '', $sep = ', ', $after = '' ) {
 	$term_list = get_the_term_list( $id, $taxonomy, $before, $sep, $after );
@@ -1412,7 +1417,7 @@ function the_terms( $id, $taxonomy, $before = '', $sep = ', ', $after = '' ) {
  * @since 3.1.0
  *
  * @param string|int|array $category Optional. The category name/term_id/slug or array of them to check for.
- * @param int|object $post Optional. Post to check instead of the current post.
+ * @param int|object       $post     Optional. Post to check instead of the current post.
  * @return bool True if the current post has any of the given categories (or any category, if no category specified).
  */
 function has_category( $category = '', $post = null ) {
@@ -1436,8 +1441,8 @@ function has_category( $category = '', $post = null ) {
  *
  * @since 2.6.0
  *
- * @param string|int|array $tag Optional. The tag name/term_id/slug or array of them to check for.
+ * @param string|int|array $tag  Optional. The tag name/term_id/slug or array of them to check for.
- * @param int|object $post Optional. Post to check instead of the current post. (since 2.7.0)
+ * @param int|object       $post Optional. Post to check instead of the current post. (since 2.7.0)
  * @return bool True if the current post has any of the given tags (or any tag, if no tag specified).
  */
 function has_tag( $tag = '', $post = null ) {

wp-includes/class-http.php

@@ -1004,8 +1004,8 @@ class WP_Http {
 	 * @param string $url      The URL which was requested.
 	 * @param array  $args     The arguments which were used to make the request.
 	 * @param array  $response The response of the HTTP request.
-	 * @return false|WP_Error|array False if no redirect is present, a WP_Error object if there's an error, or an HTTP
+	 * @return array|false|WP_Error An HTTP API response array if the redirect is successfully followed,
-	 *                              API response array if the redirect is successfully followed.
+	 *                              false if no redirect is present, or a WP_Error object if there's an error.
 	 */
 	public static function handle_redirects( $url, $args, $response ) {
 		// If no redirects are present, or, redirects were not requested, perform no action.

wp-includes/class-wp-customize-setting.php

@@ -497,7 +497,7 @@ class WP_Customize_Setting {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @return false|void False if cap check fails or value isn't set or is invalid.
+	 * @return void|false False if cap check fails or value isn't set or is invalid.
 	 */
 	final public function save() {
 		$value = $this->post_value();

wp-includes/class-wp-customize-widgets.php

@@ -225,7 +225,7 @@ final class WP_Customize_Widgets {
 	 *
 	 * @param false|array $args       The arguments to the WP_Customize_Setting constructor.
 	 * @param string      $setting_id ID for dynamic setting, usually coming from `$_POST['customized']`.
-	 * @return false|array Setting arguments, false otherwise.
+	 * @return array|false Setting arguments, false otherwise.
 	 */
 	public function filter_customize_dynamic_setting_args( $args, $setting_id ) {
 		if ( $this->get_setting_type( $setting_id ) ) {

wp-includes/class-wp-editor.php

@@ -1738,7 +1738,7 @@ final class _WP_Editors {
 	 * @since 3.1.0
 	 *
 	 * @param array $args Optional. Accepts 'pagenum' and 's' (search) arguments.
-	 * @return false|array Results.
+	 * @return array|false Results.
 	 */
 	public static function wp_link_query( $args = array() ) {
 		$pts      = get_post_types( array( 'public' => true ), 'objects' );

wp-includes/class-wp-embed.php

@@ -435,7 +435,7 @@ class WP_Embed {
 	 * Conditionally makes a hyperlink based on an internal class variable.
 	 *
 	 * @param string $url URL to potentially be linked.
-	 * @return false|string Linked URL or the original URL. False if 'return_false_on_fail' is true.
+	 * @return string|false Linked URL or the original URL. False if 'return_false_on_fail' is true.
 	 */
 	public function maybe_make_link( $url ) {
 		if ( $this->return_false_on_fail ) {

wp-includes/class-wp-image-editor.php

@@ -379,7 +379,7 @@ abstract class WP_Image_Editor {
 	 *
 	 * @since 3.5.0
 	 *
-	 * @return false|string suffix
+	 * @return string|false suffix
 	 */
 	public function get_suffix() {
 		if ( ! $this->get_size() ) {

wp-includes/class-wp-meta-query.php

@@ -311,7 +311,7 @@ class WP_Meta_Query {
 	 * @param string $primary_table     Database table where the object being filtered is stored (eg wp_users).
 	 * @param string $primary_id_column ID column for the filtered object in $primary_table.
 	 * @param object $context           Optional. The main query object.
-	 * @return false|array {
+	 * @return array|false {
 	 *     Array containing JOIN and WHERE SQL clauses to append to the main query.
 	 *
 	 *     @type string $join  SQL fragment to append to the main JOIN clause.

wp-includes/class-wp-oembed.php

@@ -248,7 +248,7 @@ class WP_oEmbed {
 	 *
 	 * @param string        $url  The URL to the content.
 	 * @param string|array  $args Optional provider arguments.
-	 * @return false|string False on failure, otherwise the oEmbed provider URL.
+	 * @return string|false The oEmbed provider URL on success, false on failure.
 	 */
 	public function get_provider( $url, $args = '' ) {
 		$args = wp_parse_args( $args );
@@ -339,7 +339,7 @@ class WP_oEmbed {
 	 *
 	 * @param string       $url  The URL to the content that should be attempted to be embedded.
 	 * @param array|string $args Optional. Arguments, usually passed from a shortcode. Default empty.
-	 * @return false|object False on failure, otherwise the result in the form of an object.
+	 * @return object|false The result in the form of an object on success, false on failure.
 	 */
 	public function get_data( $url, $args = '' ) {
 		$args = wp_parse_args( $args );
@@ -369,7 +369,8 @@ class WP_oEmbed {
 	 *
 	 * @param string       $url  The URL to the content that should be attempted to be embedded.
 	 * @param array|string $args Optional. Arguments, usually passed from a shortcode. Default empty.
-	 * @return false|string False on failure, otherwise the UNSANITIZED (and potentially unsafe) HTML that should be used to embed.
+	 * @return string|false The UNSANITIZED (and potentially unsafe) HTML that should be used to embed on success,
+	 *                      false on failure.
 	 */
 	public function get_html( $url, $args = '' ) {
 		/**
@@ -417,7 +418,7 @@ class WP_oEmbed {
 	 * @since 2.9.0
 	 *
 	 * @param string $url The URL that should be inspected for discovery `<link>` tags.
-	 * @return false|string False on failure, otherwise the oEmbed provider URL.
+	 * @return string|false The oEmbed provider URL on success, false on failure.
 	 */
 	public function discover( $url ) {
 		$providers = array();
@@ -509,7 +510,7 @@ class WP_oEmbed {
 	 * @param string       $provider The URL to the oEmbed provider.
 	 * @param string       $url      The URL to the content that is desired to be embedded.
 	 * @param array|string $args     Optional. Arguments, usually passed from a shortcode. Default empty.
-	 * @return false|object False on failure, otherwise the result in the form of an object.
+	 * @return object|false The result in the form of an object on success, false on failure.
 	 */
 	public function fetch( $provider, $url, $args = '' ) {
 		$args = wp_parse_args( $args, wp_embed_defaults( $url ) );
@@ -547,8 +548,8 @@ class WP_oEmbed {
 	 * @since 3.0.0
 	 *
 	 * @param string $provider_url_with_args URL to the provider with full arguments list (url, maxheight, etc.)
-	 * @param string $format Format to use
+	 * @param string $format                 Format to use.
-	 * @return false|object|WP_Error False on failure, otherwise the result in the form of an object.
+	 * @return object|false|WP_Error The result in the form of an object on success, false on failure.
 	 */
 	private function _fetch_with_format( $provider_url_with_args, $format ) {
 		$provider_url_with_args = add_query_arg( 'format', $format, $provider_url_with_args );
@@ -653,8 +654,8 @@ class WP_oEmbed {
 	 * @since 2.9.0
 	 *
 	 * @param object $data A data object result from an oEmbed provider.
-	 * @param string $url The URL to the content that is desired to be embedded.
+	 * @param string $url  The URL to the content that is desired to be embedded.
-	 * @return false|string False on error, otherwise the HTML needed to embed.
+	 * @return string|false The HTML needed to embed on success, false on failure.
 	 */
 	public function data2html( $data, $url ) {
 		if ( ! is_object( $data ) || empty( $data->type ) ) {

wp-includes/class-wp-rewrite.php

@@ -489,7 +489,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return string|false False on no permalink structure. Date permalink structure.
+	 * @return string|false Date permalink structure on success, false on failure.
 	 */
 	public function get_date_permastruct() {
 		if ( isset( $this->date_structure ) ) {
@@ -546,7 +546,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return false|string False on failure. Year structure on success.
+	 * @return string|false Year permalink structure on success, false on failure.
 	 */
 	public function get_year_permastruct() {
 		$structure = $this->get_date_permastruct();
@@ -570,7 +570,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return false|string False on failure. Year/Month structure on success.
+	 * @return string|false Year/Month permalink structure on success, false on failure.
 	 */
 	public function get_month_permastruct() {
 		$structure = $this->get_date_permastruct();
@@ -592,7 +592,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return string|false False on failure. Year/Month/Day structure on success.
+	 * @return string|false Year/Month/Day permalink structure on success, false on failure.
 	 */
 	public function get_day_permastruct() {
 		return $this->get_date_permastruct();
@@ -608,7 +608,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return string|false False on failure. Category permalink structure.
+	 * @return string|false Category permalink structure on success, false on failure.
 	 */
 	public function get_category_permastruct() {
 		return $this->get_extra_permastruct( 'category' );
@@ -624,7 +624,7 @@ class WP_Rewrite {
 	 *
 	 * @since 2.3.0
 	 *
-	 * @return string|false False on failure. Tag permalink structure.
+	 * @return string|false Tag permalink structure on success, false on failure.
 	 */
 	public function get_tag_permastruct() {
 		return $this->get_extra_permastruct( 'post_tag' );
@@ -636,7 +636,7 @@ class WP_Rewrite {
 	 * @since 2.5.0
 	 *
 	 * @param string $name Permalink structure name.
-	 * @return string|false False if not found. Permalink structure string.
+	 * @return string|false Permalink structure string on success, false on failure.
 	 */
 	public function get_extra_permastruct( $name ) {
 		if ( empty( $this->permalink_structure ) ) {
@@ -659,7 +659,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return string|false False if not found. Permalink structure string.
+	 * @return string|false Author permalink structure on success, false on failure.
 	 */
 	public function get_author_permastruct() {
 		if ( isset( $this->author_structure ) ) {
@@ -685,7 +685,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return string|false False if not found. Permalink structure string.
+	 * @return string|false Search permalink structure on success, false on failure.
 	 */
 	public function get_search_permastruct() {
 		if ( isset( $this->search_structure ) ) {
@@ -711,7 +711,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return string|false False if not found. Permalink structure string.
+	 * @return string|false Page permalink structure on success, false on failure.
 	 */
 	public function get_page_permastruct() {
 		if ( isset( $this->page_structure ) ) {
@@ -737,7 +737,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return string|false False if not found. Permalink structure string.
+	 * @return string|false Feed permalink structure on success, false on failure.
 	 */
 	public function get_feed_permastruct() {
 		if ( isset( $this->feed_structure ) ) {
@@ -763,7 +763,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return string|false False if not found. Permalink structure string.
+	 * @return string|false Comment feed permalink structure on success, false on failure.
 	 */
 	public function get_comment_feed_permastruct() {
 		if ( isset( $this->comment_feed_structure ) ) {

wp-includes/comment-template.php

@@ -427,11 +427,12 @@ function comment_author_url_link( $linktext = '', $before = '', $after = '', $co
  * @param int|WP_Post    $post_id  Post ID or WP_Post object. Default current post.
  * @param bool           $echo     Optional. Whether to echo or return the output.
  *                                 Default true.
- * @return string If `$echo` is false, the class will be returned. Void otherwise.
+ * @return void|string Void if `$echo` argument is true, comment classes if `$echo` is false.
  */
 function comment_class( $class = '', $comment = null, $post_id = null, $echo = true ) {
 	// Separates classes with a single space, collates classes for comment DIV
 	$class = 'class="' . join( ' ', get_comment_class( $class, $comment, $post_id ) ) . '"';
+
 	if ( $echo ) {
 		echo $class;
 	} else {
@@ -1992,6 +1993,8 @@ function comment_form_title( $noreplytext = false, $replytext = false, $linktopa
  *     @type bool   $echo              Whether to echo the output or return it. Default true.
  * }
  * @param WP_Comment[] $comments Optional. Array of WP_Comment objects.
+ * @return void|string Void if 'echo' argument is true, or no comments to list.
+ *                     Otherwise, HTML list of comments.
  */
 function wp_list_comments( $args = array(), $comments = null ) {
 	global $wp_query, $comment_alt, $comment_depth, $comment_thread_alt, $overridden_cpage, $in_comment_loop;

wp-includes/comment.php

@@ -1645,7 +1645,7 @@ function wp_unspam_comment( $comment_id ) {
  * @since 1.0.0
  *
  * @param int|WP_Comment $comment_id Comment ID or WP_Comment object
- * @return false|string Status might be 'trash', 'approved', 'unapproved', 'spam'. False on failure.
+ * @return string|false Status might be 'trash', 'approved', 'unapproved', 'spam'. False on failure.
  */
 function wp_get_comment_status( $comment_id ) {
 	$comment = get_comment( $comment_id );
@@ -2569,7 +2569,7 @@ function wp_update_comment_count_now( $post_id ) {
  *
  * @param string $url URL to ping.
  * @param int $deprecated Not Used.
- * @return false|string False on failure, string containing URI on success.
+ * @return string|false String containing URI on success, false on failure.
  */
 function discover_pingback_server_uri( $url, $deprecated = '' ) {
 	if ( ! empty( $deprecated ) ) {

wp-includes/cron.php

@@ -393,7 +393,7 @@ function wp_unschedule_event( $timestamp, $hook, $args = array() ) {
  *
  * @param string $hook Action hook, the execution of which will be unscheduled.
  * @param array  $args Optional. Arguments that were to be passed to the hook's callback function.
- * @return false|int On success an integer indicating number of events unscheduled (0 indicates no
+ * @return int|false On success an integer indicating number of events unscheduled (0 indicates no
  *                   events were registered with the hook and arguments combination), false if
  *                   unscheduling one or more events fail.
  */
@@ -461,7 +461,7 @@ function wp_clear_scheduled_hook( $hook, $args = array() ) {
  * @since 5.1.0 Return value added to indicate success or failure.
  *
  * @param string $hook Action hook, the execution of which will be unscheduled.
- * @return false|int On success an integer indicating number of events unscheduled (0 indicates no
+ * @return int|false On success an integer indicating number of events unscheduled (0 indicates no
  *                   events were registered on the hook), false if unscheduling fails.
  */
 function wp_unschedule_hook( $hook ) {
@@ -528,7 +528,7 @@ function wp_unschedule_hook( $hook ) {
  *                            Although not passed to a callback, these arguments are used to uniquely identify the
  *                            event, so they should be the same as those used when originally scheduling the event.
  * @param int|null $timestamp Optional. Unix timestamp (UTC) of the event. If not specified, the next scheduled event is returned.
- * @return false|object The event object. False if the event does not exist.
+ * @return object|false The event object. False if the event does not exist.
  */
 function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) {
 	/**
@@ -606,7 +606,7 @@ function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) {
  * @param array  $args Optional. Array containing each separate argument to pass to the hook's callback function.
  *                     Although not passed to a callback, these arguments are used to uniquely identify the
  *                     event, so they should be the same as those used when originally scheduling the event.
- * @return false|int The Unix timestamp of the next time the event will occur. False if the event doesn't exist.
+ * @return int|false The Unix timestamp of the next time the event will occur. False if the event doesn't exist.
  */
 function wp_next_scheduled( $hook, $args = array() ) {
 	$next_event = wp_get_scheduled_event( $hook, $args );
@@ -926,7 +926,7 @@ function wp_get_ready_cron_jobs() {
  * @since 2.1.0
  * @access private
  *
- * @return false|array CRON info array.
+ * @return array|false CRON info array.
  */
 function _get_cron_array() {
 	$cron = get_option( 'cron' );

wp-includes/deprecated.php

@@ -610,7 +610,7 @@ function get_autotoggle($id = 0) {
  * @param string $feed_image
  * @param string $exclude
  * @param bool $hierarchical
- * @return false|null
+ * @return null|false
  */
 function list_cats($optionall = 1, $all = 'All', $sort_column = 'ID', $sort_order = 'asc', $file = '', $list = true, $optiondates = 0,
 				$optioncount = 0, $hide_empty = 1, $use_desc_for_title = 1, $children=false, $child_of=0, $categories=0,
@@ -630,7 +630,7 @@ function list_cats($optionall = 1, $all = 'All', $sort_column = 'ID', $sort_orde
  * @see wp_list_categories()
  *
  * @param string|array $args
- * @return false|null|string
+ * @return null|string|false
  */
 function wp_list_cats($args = '') {
 	_deprecated_function( __FUNCTION__, '2.1.0', 'wp_list_categories()' );
@@ -1908,7 +1908,7 @@ function get_attachment_icon_src( $id = 0, $fullsize = false ) {
  * @param int $id Optional. Post ID.
  * @param bool $fullsize Optional, default to false. Whether to have full size image.
  * @param array $max_dims Optional. Dimensions of image.
- * @return false|string HTML content.
+ * @return string|false HTML content.
  */
 function get_attachment_icon( $id = 0, $fullsize = false, $max_dims = false ) {
 	_deprecated_function( __FUNCTION__, '2.5.0', 'wp_get_attachment_image()' );
@@ -1964,7 +1964,7 @@ function get_attachment_icon( $id = 0, $fullsize = false, $max_dims = false ) {
  * @param int $id Optional. Post ID.
  * @param bool $fullsize Optional, default to false. Whether to have full size image.
  * @param array $max_dims Optional. Dimensions of image.
- * @return false|string
+ * @return string|false
  */
 function get_attachment_innerHTML($id = 0, $fullsize = false, $max_dims = false) {
 	_deprecated_function( __FUNCTION__, '2.5.0', 'wp_get_attachment_image()' );

wp-includes/embed.php

@@ -102,7 +102,7 @@ function wp_embed_defaults( $url = '' ) {
  * @param string $url  The URL that should be embedded.
  * @param array  $args Optional. Additional arguments and parameters for retrieving embed HTML.
  *                     Default empty.
- * @return false|string False on failure or the embed HTML on success.
+ * @return string|false The embed HTML on success, false on failure.
  */
 function wp_oembed_get( $url, $args = '' ) {
 	$oembed = _wp_oembed_get_object();

wp-includes/feed.php

@@ -280,7 +280,7 @@ function comment_guid( $comment_id = null ) {
  * @since 2.5.0
  *
  * @param int|WP_Comment $comment_id Optional comment object or id. Defaults to global comment object.
- * @return false|string false on failure or guid for comment on success.
+ * @return string|false GUID for comment on success, false on failure.
  */
 function get_comment_guid( $comment_id = null ) {
 	$comment = get_comment( $comment_id );

wp-includes/functions.php

@@ -1219,7 +1219,7 @@ function add_magic_quotes( $array ) {
  * @see wp_safe_remote_get()
  *
  * @param string $uri URI/URL of web page to retrieve.
- * @return false|string HTTP content. False on failure.
+ * @return string|false HTTP content. False on failure.
  */
 function wp_remote_fopen( $uri ) {
 	$parsed_url = @parse_url( $uri );
@@ -1858,7 +1858,7 @@ function wp_original_referer_field( $echo = true, $jump_back_to = 'current' ) {
  *
  * @since 2.0.4
  *
- * @return false|string False on failure. Referer URL on success.
+ * @return string|false Referer URL on success, false on failure.
  */
 function wp_get_referer() {
 	if ( ! function_exists( 'wp_validate_redirect' ) ) {

wp-includes/general-template.php

@@ -196,7 +196,7 @@ function get_template_part( $slug, $name = null ) {
  *                              multiple search forms on the same page and improve
  *                              accessibility. Default empty.
  * }
- * @return string|void String when the $echo param is false.
+ * @return void|string Void if 'echo' argument is true, search form HTML if 'echo' is false.
  */
 function get_search_form( $args = array() ) {
 	/**
@@ -300,7 +300,7 @@ function get_search_form( $args = array() ) {
 		$result = $form;
 	}
 
-	if ( isset( $args['echo'] ) && $args['echo'] ) {
+	if ( $args['echo'] ) {
 		echo $result;
 	} else {
 		return $result;
@@ -426,7 +426,7 @@ function wp_registration_url() {
 /**
  * Provides a simple login form for use anywhere within WordPress.
  *
- * The login format HTML is echoed by default. Pass a false value for `$echo` to return it instead.
+ * The login form HTML is echoed by default. Pass a false value for `$echo` to return it instead.
  *
  * @since 3.0.0
  *
@@ -452,7 +452,7 @@ function wp_registration_url() {
  *                                  Default false (unchecked).
  *
  * }
- * @return string|void String when retrieving.
+ * @return void|string Void if 'echo' argument is true, login form HTML if 'echo' is false.
  */
 function wp_login_form( $args = array() ) {
 	$defaults = array(
@@ -1806,7 +1806,7 @@ function get_archives_link( $url, $text, $format = 'html', $before = '', $after
  *     @type string     $day             Day. Default current day.
  *     @type string     $w               Week. Default current week.
  * }
- * @return string|void String when retrieving.
+ * @return void|string Void if 'echo' argument is true, archive links if 'echo' is false.
  */
 function wp_get_archives( $args = '' ) {
 	global $wpdb, $wp_locale;
@@ -2019,6 +2019,7 @@ function wp_get_archives( $args = '' ) {
 			}
 		}
 	}
+
 	if ( $parsed_args['echo'] ) {
 		echo $output;
 	} else {
@@ -2389,7 +2390,7 @@ function the_date( $d = '', $before = '', $after = '', $echo = true ) {
  *
  * @param  string      $d    Optional. PHP date format defaults to the date_format option if not specified.
  * @param  int|WP_Post $post Optional. Post ID or WP_Post object. Default current post.
- * @return false|string Date the current post was written. False on failure.
+ * @return string|false Date the current post was written. False on failure.
  */
 function get_the_date( $d = '', $post = null ) {
 	$post = get_post( $post );
@@ -2460,7 +2461,7 @@ function the_modified_date( $d = '', $before = '', $after = '', $echo = true ) {
  *
  * @param string      $d    Optional. PHP date format defaults to the date_format option if not specified.
  * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default current post.
- * @return false|string Date the current post was modified. False on failure.
+ * @return string|false Date the current post was modified. False on failure.
  */
 function get_the_modified_date( $d = '', $post = null ) {
 	$post = get_post( $post );
@@ -2705,7 +2706,7 @@ function the_modified_time( $d = '' ) {
  *                           was modified. Either 'G', 'U', or php date format defaults
  *                           to the value specified in the time_format option. Default empty.
  * @param int|WP_Post $post  Optional. Post ID or WP_Post object. Default current post.
- * @return false|string Formatted date string or Unix timestamp. False on failure.
+ * @return string|false Formatted date string or Unix timestamp. False on failure.
  */
 function get_the_modified_time( $d = '', $post = null ) {
 	$post = get_post( $post );
@@ -4070,7 +4071,8 @@ function language_attributes( $doctype = 'html' ) {
  *     @type string $before_page_number A string to appear before the page number. Default empty.
  *     @type string $after_page_number  A string to append after the page number. Default empty.
  * }
- * @return string|array|void String of page links or array of page links.
+ * @return string|array|void String of page links or array of page links, depending on 'type' argument.
+ *                           Void if total number of pages is less than 2.
  */
 function paginate_links( $args = '' ) {
 	global $wp_query, $wp_rewrite;

wp-includes/http.php

@@ -513,7 +513,7 @@ function send_origin_headers() {
  * @since 3.5.2
  *
  * @param string $url Request URL.
- * @return false|string URL or false on failure.
+ * @return string|false URL or false on failure.
  */
 function wp_http_validate_url( $url ) {
 	$original_url = $url;

wp-includes/l10n.php

@@ -927,7 +927,7 @@ function load_child_theme_textdomain( $domain, $path = false ) {
  * @param string $domain Optional. Text domain. Default 'default'.
  * @param string $path   Optional. The full file path to the directory containing translation files.
  *
- * @return false|string False if the script textdomain could not be loaded, the translated strings
+ * @return string|false False if the script textdomain could not be loaded, the translated strings
  *                      in JSON encoding otherwise.
  */
 function load_script_textdomain( $handle, $domain = 'default', $path = null ) {
@@ -1432,7 +1432,7 @@ function wp_get_pomo_file_data( $po_file ) {
  *     @type bool     $show_option_site_default     Whether to show an option to fall back to the site's locale. Default false.
  *     @type bool     $show_option_en_us            Whether to show an option for English (United States). Default true.
  * }
- * @return string HTML content
+ * @return string HTML dropdown list of languages.
  */
 function wp_dropdown_languages( $args = array() ) {
 

wp-includes/link-template.php

@@ -467,7 +467,7 @@ function get_attachment_link( $post = null, $leavename = false ) {
  *
  * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
  *
- * @param int|bool $year False for current year or year for permalink.
+ * @param int|false $year Integer of year. False for current year.
  * @return string The permalink for the specified year archive.
  */
 function get_year_link( $year ) {
@@ -501,8 +501,8 @@ function get_year_link( $year ) {
  *
  * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
  *
- * @param bool|int $year  False for current year. Integer of year.
+ * @param int|false $year  Integer of year. False for current year.
- * @param bool|int $month False for current month. Integer of month.
+ * @param int|false $month Integer of month. False for current month.
  * @return string The permalink for the specified month and year archive.
  */
 function get_month_link( $year, $month ) {
@@ -541,9 +541,9 @@ function get_month_link( $year, $month ) {
  *
  * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
  *
- * @param bool|int $year  False for current year. Integer of year.
+ * @param int|false $year  Integer of year. False for current year.
- * @param bool|int $month False for current month. Integer of month.
+ * @param int|false $month Integer of month. False for current month.
- * @param bool|int $day   False for current day. Integer of day.
+ * @param int|false $day   Integer of day. False for current day.
  * @return string The permalink for the specified day, month, and year archive.
  */
 function get_day_link( $year, $month, $day ) {
@@ -2968,7 +2968,10 @@ function previous_comments_link( $label = '' ) {
  * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
  *
  * @param string|array $args Optional args. See paginate_links(). Default empty array.
- * @return string|array|void Markup for comment page links or array of comment page links.
+ * @return void|string|array Void if 'echo' argument is true and 'type' is not an array,
+ *                           or if the query is not for an existing single post of any post type.
+ *                           Otherwise, markup for comment page links or array of comment page links,
+ *                           depending on 'type' argument.
  */
 function paginate_comments_links( $args = array() ) {
 	global $wp_rewrite;
@@ -4011,7 +4014,7 @@ function the_shortlink( $text = '', $title = '', $before = '', $after = '' ) {
  *     @type array  $processed_args When the function returns, the value will be the processed/sanitized $args
  *                                  plus a "found_avatar" guess. Pass as a reference. Default null.
  * }
- * @return false|string The URL of the avatar we found, or false if we couldn't find an avatar.
+ * @return string|false The URL of the avatar on success, false on failure.
  */
 function get_avatar_url( $id_or_email, $args = null ) {
 	$args = get_avatar_data( $id_or_email, $args );

wp-includes/media.php

@@ -185,7 +185,7 @@ function image_hwstring( $width, $height ) {
  * @param array|string $size Optional. Image size to scale to. Accepts any valid image size,
  *                           or an array of width and height values in pixels (in that order).
  *                           Default 'medium'.
- * @return false|array Array containing the image URL, width, height, and boolean for whether
+ * @return array|false Array containing the image URL, width, height, and boolean for whether
  *                     the image is an intermediate size. False on failure.
  */
 function image_downsize( $id, $size = 'medium' ) {
@@ -521,7 +521,7 @@ function wp_constrain_dimensions( $current_width, $current_height, $max_width =
  * @param int        $dest_h New height in pixels.
  * @param bool|array $crop   Optional. Whether to crop image to specified width and height or resize.
  *                           An array can specify positioning of the crop area. Default false.
- * @return false|array False on failure. Returned array matches parameters for `imagecopyresampled()`.
+ * @return array|false Returned array matches parameters for `imagecopyresampled()`. False on failure.
  */
 function image_resize_dimensions( $orig_w, $orig_h, $dest_w, $dest_h, $crop = false ) {
 
@@ -665,7 +665,7 @@ function image_resize_dimensions( $orig_w, $orig_h, $dest_w, $dest_h, $crop = fa
  * @param int    $height Image height.
  * @param bool   $crop   Optional. Whether to crop image to specified width and height or resize.
  *                       Default false.
- * @return false|array False, if no image was created. Metadata array on success.
+ * @return array|false Metadata array on success. False if no image was created.
  */
 function image_make_intermediate_size( $file, $width, $height, $crop = false ) {
 	if ( $width || $height ) {
@@ -740,7 +740,7 @@ function wp_image_matches_ratio( $source_width, $source_height, $target_width, $
  * @param array|string $size    Optional. Image size. Accepts any valid image size, or an array
  *                              of width and height values in pixels (in that order).
  *                              Default 'thumbnail'.
- * @return false|array $data {
+ * @return array|false $data {
  *     Array of file relative path, width, and height on success. Additionally includes absolute
  *     path and URL if registered size is passed to $size parameter. False on failure.
  *
@@ -941,7 +941,7 @@ function wp_get_registered_image_subsizes() {
  * @param string|array $size          Optional. Image size. Accepts any valid image size, or an array of width
  *                                    and height values in pixels (in that order). Default 'thumbnail'.
  * @param bool         $icon          Optional. Whether the image should be treated as an icon. Default false.
- * @return false|array Returns an array (url, width, height, is_intermediate), or false, if no image is available.
+ * @return array|false Returns an array (url, width, height, is_intermediate), or false if no image is available.
  */
 function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon = false ) {
 	// get a thumbnail or intermediate image if there is one

wp-includes/nav-menu.php

@@ -667,7 +667,7 @@ function _is_valid_nav_menu_item( $item ) {
  *                               processed in this function. Default 'menu_order'.
  *     @type bool   $nopaging    Whether to retrieve all menu items (true) or paginate (false). Default true.
  * }
- * @return false|array $items Array of menu items, otherwise false.
+ * @return array|false $items Array of menu items, otherwise false.
  */
 function wp_get_nav_menu_items( $menu, $args = array() ) {
 	$menu = wp_get_nav_menu_object( $menu );

wp-includes/pluggable-deprecated.php

@@ -166,7 +166,7 @@ if ( !function_exists('wp_login') ) :
  * @param string $username   User's username
  * @param string $password   User's password
  * @param string $deprecated Not used
- * @return bool False on login failure, true on successful check
+ * @return bool True on successful check, false on login failure.
  */
 function wp_login($username, $password, $deprecated = '') {
 	_deprecated_function( __FUNCTION__, '2.5.0', 'wp_signon()' );

wp-includes/pluggable.php

@@ -600,7 +600,7 @@ if ( ! function_exists( 'wp_validate_auth_cookie' ) ) :
 	 *
 	 * @param string $cookie Optional. If used, will validate contents instead of cookie's.
 	 * @param string $scheme Optional. The cookie scheme to use: 'auth', 'secure_auth', or 'logged_in'.
-	 * @return false|int False if invalid cookie, user ID if valid.
+	 * @return int|false User ID if valid cookie, false if invalid.
 	 */
 	function wp_validate_auth_cookie( $cookie = '', $scheme = '' ) {
 		$cookie_elements = wp_parse_auth_cookie( $cookie, $scheme );
@@ -1111,8 +1111,9 @@ if ( ! function_exists( 'check_admin_referer' ) ) :
 	 *
 	 * @param int|string $action    The nonce action.
 	 * @param string     $query_arg Optional. Key to check for nonce in `$_REQUEST`. Default '_wpnonce'.
-	 * @return false|int False if the nonce is invalid, 1 if the nonce is valid and generated between
+	 * @return int|false 1 if the nonce is valid and generated between 0-12 hours ago,
-	 *                   0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   False if the nonce is invalid.
 	 */
 	function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
 		if ( -1 === $action ) {
@@ -1155,8 +1156,9 @@ if ( ! function_exists( 'check_ajax_referer' ) ) :
 	 *                                (in that order). Default false.
 	 * @param bool         $die       Optional. Whether to die early when the nonce cannot be verified.
 	 *                                Default true.
-	 * @return false|int False if the nonce is invalid, 1 if the nonce is valid and generated between
+	 * @return int|false 1 if the nonce is valid and generated between 0-12 hours ago,
-	 *                   0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   False if the nonce is invalid.
 	 */
 	function check_ajax_referer( $action = -1, $query_arg = false, $die = true ) {
 		if ( -1 == $action ) {
@@ -2092,8 +2094,9 @@ if ( ! function_exists( 'wp_verify_nonce' ) ) :
 	 *
 	 * @param string     $nonce  Nonce value that was used for verification, usually via a form field.
 	 * @param string|int $action Should give context to what is taking place and be the same when nonce was created.
-	 * @return false|int False if the nonce is invalid, 1 if the nonce is valid and generated between
+	 * @return int|false 1 if the nonce is valid and generated between 0-12 hours ago,
-	 *                   0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   False if the nonce is invalid.
 	 */
 	function wp_verify_nonce( $nonce, $action = -1 ) {
 		$nonce = (string) $nonce;
@@ -2580,7 +2583,7 @@ if ( ! function_exists( 'get_avatar' ) ) :
 	 *                                       Default false.
 	 *     @type string       $extra_attr    HTML attributes to insert in the IMG element. Is not sanitized. Default empty.
 	 * }
-	 * @return false|string `<img>` tag for the user's avatar. False on failure.
+	 * @return string|false `<img>` tag for the user's avatar. False on failure.
 	 */
 	function get_avatar( $id_or_email, $size = 96, $default = '', $alt = '', $args = null ) {
 		$defaults = array(

wp-includes/pomo/po.php

@@ -209,7 +209,7 @@ if ( ! class_exists( 'PO', false ) ) :
 		 * Builds a string from the entry for inclusion in PO file
 		 *
 		 * @param Translation_Entry $entry the entry to convert to po string (passed by reference).
-		 * @return false|string PO-style formatted string for the entry or
+		 * @return string|false PO-style formatted string for the entry or
 		 *  false if the entry is empty
 		 */
 		public static function export_entry( &$entry ) {

wp-includes/post-template.php

@@ -37,7 +37,7 @@ function get_the_ID() { // phpcs:ignore WordPress.NamingConventions.ValidFunctio
  * @param string $before Optional. Markup to prepend to the title. Default empty.
  * @param string $after  Optional. Markup to append to the title. Default empty.
  * @param bool   $echo   Optional. Whether to echo or return the title. Default true for echo.
- * @return string|void Current post title if $echo is false.
+ * @return void|string Void if `$echo` argument is true, current post title if `$echo` is false.
  */
 function the_title( $before = '', $after = '', $echo = true ) {
 	$title = get_the_title();
@@ -75,7 +75,7 @@ function the_title( $before = '', $after = '', $echo = true ) {
  *     @type bool    $echo   Whether to echo or return the title. Default true for echo.
  *     @type WP_Post $post   Current post object to retrieve the title for.
  * }
- * @return string|void String when echo is false.
+ * @return void|string Void if 'echo' argument is true, the title attribute if 'echo' is false.
  */
 function the_title_attribute( $args = '' ) {
 	$defaults    = array(
@@ -1062,7 +1062,8 @@ function _wp_link_page( $i ) {
  * @since 1.5.0
  *
  * @param string $key Meta data key name.
- * @return false|string|array Array of values or single value, if only one element exists. False will be returned if key does not exist.
+ * @return array|string|false Array of values, or single value if only one element exists.
+ *                            False if the key does not exist.
  */
 function post_custom( $key = '' ) {
 	$custom = get_post_custom();
@@ -1153,7 +1154,7 @@ function the_meta() {
  *     @type string       $value_field           Post field used to populate the 'value' attribute of the option
  *                                               elements. Accepts any valid post field. Default 'ID'.
  * }
- * @return string HTML content, if not displaying.
+ * @return string HTML dropdown list of pages.
  */
 function wp_dropdown_pages( $args = '' ) {
 	$defaults = array(
@@ -1211,6 +1212,7 @@ function wp_dropdown_pages( $args = '' ) {
 	if ( $parsed_args['echo'] ) {
 		echo $html;
 	}
+
 	return $html;
 }
 
@@ -1252,7 +1254,7 @@ function wp_dropdown_pages( $args = '' ) {
  *                                      Default 'preserve'.
  *     @type Walker       $walker       Walker instance to use for listing pages. Default empty (Walker_Page).
  * }
- * @return string|void HTML list of pages.
+ * @return void|string Void if 'echo' argument is true, HTML list of pages if 'echo' is false.
  */
 function wp_list_pages( $args = '' ) {
 	$defaults = array(
@@ -1373,7 +1375,7 @@ function wp_list_pages( $args = '' ) {
  *                                         or 'discard'. Default 'discard'.
  *     @type Walker          $walker       Walker instance to use for listing pages. Default empty (Walker_Page).
  * }
- * @return string|void HTML menu
+ * @return void|string Void if 'echo' argument is true, HTML menu if 'echo' is false.
  */
 function wp_page_menu( $args = array() ) {
 	$defaults = array(
@@ -1488,6 +1490,7 @@ function wp_page_menu( $args = array() ) {
 	 * @param array  $args An array of arguments.
 	 */
 	$menu = apply_filters( 'wp_page_menu', $menu, $args );
+
 	if ( $args['echo'] ) {
 		echo $menu;
 	} else {

wp-includes/rest-api/class-wp-rest-server.php

@@ -217,7 +217,7 @@ class WP_REST_Server {
 	 *
 	 * @param string $path Optional. The request route. If not set, `$_SERVER['PATH_INFO']` will be used.
 	 *                     Default null.
-	 * @return false|null Null if not served and a HEAD request, false otherwise.
+	 * @return null|false Null if not served and a HEAD request, false otherwise.
 	 */
 	public function serve_request( $path = null ) {
 		$content_type = isset( $_GET['_jsonp'] ) ? 'application/javascript' : 'application/json';

wp-includes/revision.php

@@ -253,7 +253,7 @@ function wp_get_post_autosave( $post_id, $user_id = 0 ) {
  * @since 2.6.0
  *
  * @param int|WP_Post $post Post ID or post object.
- * @return false|int False if not a revision, ID of revision's parent otherwise.
+ * @return int|false ID of revision's parent on success, false if not a revision.
  */
 function wp_is_post_revision( $post ) {
 	$post = wp_get_post_revision( $post );
@@ -270,7 +270,7 @@ function wp_is_post_revision( $post ) {
  * @since 2.6.0
  *
  * @param int|WP_Post $post Post ID or post object.
- * @return false|int False if not a revision, ID of autosave's parent otherwise
+ * @return int|false ID of autosave's parent on success, false if not a revision.
  */
 function wp_is_post_autosave( $post ) {
 	$post = wp_get_post_revision( $post );

wp-includes/user.php

@@ -334,8 +334,8 @@ function wp_authenticate_spam_check( $user ) {
  *
  * @since 3.9.0
  *
- * @param int|bool $user_id The user ID (or false) as received from the
+ * @param int|bool $user_id The user ID (or false) as received from
- *                       determine_current_user filter.
+ *                          the `determine_current_user` filter.
  * @return int|false User ID if validated, false otherwise. If a user ID from
  *                   an earlier filter callback is received, that value is returned.
  */
@@ -1093,7 +1093,7 @@ function setup_userdata( $for_user_id = 0 ) {
  *     @type array        $role__not_in            An array of role names to exclude. Users matching one or more of
  *                                                 these roles will not be included in results. Default empty array.
  * }
- * @return string String of HTML content.
+ * @return string HTML dropdown list of users.
  */
 function wp_dropdown_users( $args = '' ) {
 	$defaults = array(
@@ -3637,7 +3637,7 @@ function wp_generate_user_request_key( $request_id ) {
  *
  * @param string $request_id ID of the request being confirmed.
  * @param string $key        Provided key to validate.
- * @return bool|WP_Error WP_Error on failure, true on success.
+ * @return bool|WP_Error True on success, WP_Error on failure.
  */
 function wp_validate_user_request_key( $request_id, $key ) {
 	global $wp_hasher;

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.4-alpha-47059';
+$wp_version = '5.4-alpha-47060';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

wp-includes/wp-db.php

@@ -1435,10 +1435,10 @@ class wpdb {
 	 * Print SQL/DB error.
 	 *
 	 * @since 0.71
-	 * @global array $EZSQL_ERROR Stores error information of query and error string
+	 * @global array $EZSQL_ERROR Stores error information of query and error string.
 	 *
-	 * @param string $str The error to display
+	 * @param string $str The error to display.
-	 * @return false|void False if the showing of errors is disabled.
+	 * @return void|false Void if the showing of errors is enabled, false if disabled.
 	 */
 	public function print_error( $str = '' ) {
 		global $EZSQL_ERROR;
@@ -3411,7 +3411,7 @@ class wpdb {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return float Total time spent on the query, in seconds
+	 * @return float Total time spent on the query, in seconds.
 	 */
 	public function timer_stop() {
 		return ( microtime( true ) - $this->time_start );
@@ -3424,9 +3424,9 @@ class wpdb {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @param string $message    The Error message
+	 * @param string $message    The error message.
-	 * @param string $error_code Optional. A Computer readable string to identify the error.
+	 * @param string $error_code Optional. A computer-readable string to identify the error.
-	 * @return false|void
+	 * @return void|false Void if the showing of errors is enabled, false if disabled.
 	 */
 	public function bail( $message, $error_code = '500' ) {
 		if ( $this->show_errors ) {

wp-signup.php

@@ -95,7 +95,7 @@ do_action( 'before_signup_form' );
  *
  * @param string          $blogname   The new site name.
  * @param string          $blog_title The new site title.
- * @param string|WP_Error $errors     A WP_Error object containing existing errors. Defaults to empty string.
+ * @param WP_Error|string $errors     A WP_Error object containing existing errors. Defaults to empty string.
  */
 function show_blog_form( $blogname = '', $blog_title = '', $errors = '' ) {
 	if ( ! is_wp_error( $errors ) ) {
@@ -246,7 +246,7 @@ function validate_blog_form() {
  *
  * @param string          $user_name  The entered username.
  * @param string          $user_email The entered email address.
- * @param string|WP_Error $errors     A WP_Error object containing existing errors. Defaults to empty string.
+ * @param WP_Error|string $errors     A WP_Error object containing existing errors. Defaults to empty string.
  */
 function show_user_form( $user_name = '', $user_email = '', $errors = '' ) {
 	if ( ! is_wp_error( $errors ) ) {
@@ -304,7 +304,7 @@ function validate_user_form() {
  *
  * @param string          $blogname   The new site name
  * @param string          $blog_title The new site title.
- * @param string|WP_Error $errors     A WP_Error object containing existing errors. Defaults to empty string.
+ * @param WP_Error|string $errors     A WP_Error object containing existing errors. Defaults to empty string.
  */
 function signup_another_blog( $blogname = '', $blog_title = '', $errors = '' ) {
 	$current_user = wp_get_current_user();
@@ -553,7 +553,7 @@ function confirm_another_blog_signup( $domain, $path, $blog_title, $user_name, $
  *
  * @param string          $user_name  The username.
  * @param string          $user_email The user's email.
- * @param string|WP_Error $errors     A WP_Error object containing existing errors. Defaults to empty string.
+ * @param WP_Error|string $errors     A WP_Error object containing existing errors. Defaults to empty string.
  */
 function signup_user( $user_name = '', $user_email = '', $errors = '' ) {
 	global $active_signup;
@@ -691,7 +691,7 @@ function confirm_user_signup( $user_name, $user_email ) {
  * @param string          $user_email The user's email address.
  * @param string          $blogname   The site name.
  * @param string          $blog_title The site title.
- * @param string|WP_Error $errors     A WP_Error object containing existing errors. Defaults to empty string.
+ * @param WP_Error|string $errors     A WP_Error object containing existing errors. Defaults to empty string.
  */
 function signup_blog( $user_name = '', $user_email = '', $blogname = '', $blog_title = '', $errors = '' ) {
 	if ( ! is_wp_error( $errors ) ) {