From dd4d98a368ca1d617adfaaef9b2937c60464ac4a Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Sat, 11 Jan 2020 18:32:05 +0000 Subject: [PATCH] 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 | 2 +- .../includes/class-wp-community-events.php | 6 +-- wp-admin/includes/class-wp-upgrader-skin.php | 2 +- wp-admin/includes/file.php | 12 ++--- wp-admin/includes/plugin.php | 26 +++++----- wp-admin/includes/template.php | 1 + wp-admin/includes/theme.php | 2 +- wp-admin/includes/update-core.php | 4 +- wp-admin/includes/update.php | 8 ++-- wp-admin/includes/upgrade.php | 4 +- wp-admin/install-helper.php | 2 +- wp-includes/author-template.php | 7 +-- wp-includes/bookmark-template.php | 7 +-- wp-includes/cache.php | 18 +++---- wp-includes/canonical.php | 2 +- wp-includes/category-template.php | 47 ++++++++++--------- wp-includes/class-http.php | 4 +- wp-includes/class-wp-customize-setting.php | 2 +- wp-includes/class-wp-customize-widgets.php | 2 +- wp-includes/class-wp-editor.php | 2 +- wp-includes/class-wp-embed.php | 2 +- wp-includes/class-wp-image-editor.php | 2 +- wp-includes/class-wp-meta-query.php | 2 +- wp-includes/class-wp-oembed.php | 19 ++++---- wp-includes/class-wp-rewrite.php | 24 +++++----- wp-includes/comment-template.php | 5 +- wp-includes/comment.php | 4 +- wp-includes/cron.php | 10 ++-- wp-includes/deprecated.php | 8 ++-- wp-includes/embed.php | 2 +- wp-includes/feed.php | 2 +- wp-includes/functions.php | 4 +- wp-includes/general-template.php | 20 ++++---- wp-includes/http.php | 2 +- wp-includes/l10n.php | 4 +- wp-includes/link-template.php | 19 ++++---- wp-includes/media.php | 10 ++-- wp-includes/nav-menu.php | 2 +- wp-includes/pluggable-deprecated.php | 2 +- wp-includes/pluggable.php | 19 ++++---- wp-includes/pomo/po.php | 2 +- wp-includes/post-template.php | 15 +++--- wp-includes/rest-api/class-wp-rest-server.php | 2 +- wp-includes/revision.php | 4 +- wp-includes/user.php | 8 ++-- wp-includes/version.php | 2 +- wp-includes/wp-db.php | 14 +++--- wp-signup.php | 10 ++-- 48 files changed, 201 insertions(+), 178 deletions(-) diff --git a/wp-admin/includes/class-core-upgrader.php b/wp-admin/includes/class-core-upgrader.php index 6ea093c8d0..bda7901af3 100644 --- a/wp-admin/includes/class-core-upgrader.php +++ b/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; diff --git a/wp-admin/includes/class-wp-community-events.php b/wp-admin/includes/class-wp-community-events.php index 2fa955254f..8b1e32e549 100644 --- a/wp-admin/includes/class-wp-community-events.php +++ b/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` - * and `events` items on success. + * @return array|false An array containing `location` and `events` items + * on success, false on failure. */ public function get_cached_events() { $cached_response = get_site_transient( $this->get_events_transient_key( $this->user_location ) ); diff --git a/wp-admin/includes/class-wp-upgrader-skin.php b/wp-admin/includes/class-wp-upgrader-skin.php index 8356358525..e776076d64 100644 --- a/wp-admin/includes/class-wp-upgrader-skin.php +++ b/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']; diff --git a/wp-admin/includes/file.php b/wp-admin/includes/file.php index a28ac46098..a6b38b9291 100644 --- a/wp-admin/includes/file.php +++ b/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, or WP_Error describing an error condition. + * @return bool|WP_Error True on success, false if verification not attempted, + * 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, - * or an error object. Default false. + * @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. * @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 ); diff --git a/wp-admin/includes/plugin.php b/wp-admin/includes/plugin.php index b3b150a0de..ff87539798 100644 --- a/wp-admin/includes/plugin.php +++ b/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 ); diff --git a/wp-admin/includes/template.php b/wp-admin/includes/template.php index e1140325e9..5e6838eab1 100644 --- a/wp-admin/includes/template.php +++ b/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( diff --git a/wp-admin/includes/theme.php b/wp-admin/includes/theme.php index 832fe89095..2e8e0172d4 100644 --- a/wp-admin/includes/theme.php +++ b/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; diff --git a/wp-admin/includes/update-core.php b/wp-admin/includes/update-core.php index f5092eec3a..0f6f072243 100644 --- a/wp-admin/includes/update-core.php +++ b/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; diff --git a/wp-admin/includes/update.php b/wp-admin/includes/update.php index b1b656fbd1..0caa04a963 100644 --- a/wp-admin/includes/update.php +++ b/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 diff --git a/wp-admin/includes/upgrade.php b/wp-admin/includes/upgrade.php index df3b8edcc3..505b0aad17 100644 --- a/wp-admin/includes/upgrade.php +++ b/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. diff --git a/wp-admin/install-helper.php b/wp-admin/install-helper.php index c13f302784..432a4a9fa5 100644 --- a/wp-admin/install-helper.php +++ b/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; diff --git a/wp-includes/author-template.php b/wp-includes/author-template.php index a14b628909..6b18cad722 100644 --- a/wp-includes/author-template.php +++ b/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; } /** diff --git a/wp-includes/bookmark-template.php b/wp-includes/bookmark-template.php index cf82e46e00..e73f50c73d 100644 --- a/wp-includes/bookmark-template.php +++ b/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; } diff --git a/wp-includes/cache.php b/wp-includes/cache.php index 1af29d5f65..a5a548ccd2 100644 --- a/wp-includes/cache.php +++ b/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 ) ) { diff --git a/wp-includes/canonical.php b/wp-includes/canonical.php index ecacb59a60..6be007dc78 100644 --- a/wp-includes/canonical.php +++ b/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; diff --git a/wp-includes/category-template.php b/wp-includes/category-template.php index 69cf4c77e9..6217a55ce4 100644 --- a/wp-includes/category-template.php +++ b/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 '
'. - * @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 `
  • ` 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. - * Otherwise, this function outputs the tag cloud. + * @return void|string|array Void if 'echo' argument is true, or on failure. Otherwise, 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 array $args An array of tag cloud arguments. + * @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. */ $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 $sep Optional. Separate items using this. - * @param string $after Optional. After list. + * @param string $before Optional. Before list. + * @param string $sep Optional. Separate items using this. + * @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 $sep Optional. Separate items using this. - * @param string $after Optional. After list. - * @return false|void False on WordPress error. + * @param string $before Optional. Before list. + * @param string $sep Optional. Separate items using this. + * @param string $after Optional. After list. + * @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 int|object $post Optional. Post to check instead of the current post. (since 2.7.0) + * @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) * @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 ) { diff --git a/wp-includes/class-http.php b/wp-includes/class-http.php index a961808ff3..dc3148222a 100644 --- a/wp-includes/class-http.php +++ b/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 - * API response array if the redirect is successfully followed. + * @return array|false|WP_Error An HTTP 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. diff --git a/wp-includes/class-wp-customize-setting.php b/wp-includes/class-wp-customize-setting.php index 6bd00f7537..c5efd0a7ee 100644 --- a/wp-includes/class-wp-customize-setting.php +++ b/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(); diff --git a/wp-includes/class-wp-customize-widgets.php b/wp-includes/class-wp-customize-widgets.php index 7c5098f8a9..d899c26bf1 100644 --- a/wp-includes/class-wp-customize-widgets.php +++ b/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 ) ) { diff --git a/wp-includes/class-wp-editor.php b/wp-includes/class-wp-editor.php index 7617812f97..26824dfa9b 100644 --- a/wp-includes/class-wp-editor.php +++ b/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' ); diff --git a/wp-includes/class-wp-embed.php b/wp-includes/class-wp-embed.php index 317a29841c..5211bd369f 100644 --- a/wp-includes/class-wp-embed.php +++ b/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 ) { diff --git a/wp-includes/class-wp-image-editor.php b/wp-includes/class-wp-image-editor.php index 8baf341a6d..e6222ece95 100644 --- a/wp-includes/class-wp-image-editor.php +++ b/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() ) { diff --git a/wp-includes/class-wp-meta-query.php b/wp-includes/class-wp-meta-query.php index e442a17149..ebe03772bd 100644 --- a/wp-includes/class-wp-meta-query.php +++ b/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. diff --git a/wp-includes/class-wp-oembed.php b/wp-includes/class-wp-oembed.php index 26ca7173d4..42917c608d 100644 --- a/wp-includes/class-wp-oembed.php +++ b/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 `` 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 - * @return false|object|WP_Error False on failure, otherwise the result in the form of an object. + * @param string $format Format to use. + * @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. - * @return false|string False on error, otherwise the HTML needed to embed. + * @param string $url The URL to the content that is desired to be embedded. + * @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 ) ) { diff --git a/wp-includes/class-wp-rewrite.php b/wp-includes/class-wp-rewrite.php index 16d688ee48..46b118361b 100644 --- a/wp-includes/class-wp-rewrite.php +++ b/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 ) ) { diff --git a/wp-includes/comment-template.php b/wp-includes/comment-template.php index 2e4d1c83f7..a031c9a88c 100644 --- a/wp-includes/comment-template.php +++ b/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; diff --git a/wp-includes/comment.php b/wp-includes/comment.php index 9d998fc266..fca5ab9db4 100644 --- a/wp-includes/comment.php +++ b/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 ) ) { diff --git a/wp-includes/cron.php b/wp-includes/cron.php index e010b86355..b13db42c73 100644 --- a/wp-includes/cron.php +++ b/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' ); diff --git a/wp-includes/deprecated.php b/wp-includes/deprecated.php index 9230525b3c..92ba6b75a5 100644 --- a/wp-includes/deprecated.php +++ b/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()' ); diff --git a/wp-includes/embed.php b/wp-includes/embed.php index 7be60972f0..34b6d29914 100644 --- a/wp-includes/embed.php +++ b/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(); diff --git a/wp-includes/feed.php b/wp-includes/feed.php index c0b75016e3..aa17296c0c 100644 --- a/wp-includes/feed.php +++ b/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 ); diff --git a/wp-includes/functions.php b/wp-includes/functions.php index 12e4d0efe3..888343b6d0 100644 --- a/wp-includes/functions.php +++ b/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' ) ) { diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index 4b895800ee..49df1077ed 100644 --- a/wp-includes/general-template.php +++ b/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; diff --git a/wp-includes/http.php b/wp-includes/http.php index 8fca0c541d..ac60d7d449 100644 --- a/wp-includes/http.php +++ b/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; diff --git a/wp-includes/l10n.php b/wp-includes/l10n.php index 991e2346fe..9f211d4dc6 100644 --- a/wp-includes/l10n.php +++ b/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() ) { diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php index 113f2f8a33..0e7c07fef8 100644 --- a/wp-includes/link-template.php +++ b/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 bool|int $month False for current month. Integer of month. + * @param int|false $year Integer of year. False for current year. + * @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 bool|int $month False for current month. Integer of month. - * @param bool|int $day False for current day. Integer of day. + * @param int|false $year Integer of year. False for current year. + * @param int|false $month Integer of month. False for current month. + * @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 ); diff --git a/wp-includes/media.php b/wp-includes/media.php index 601538d8ea..1d7c79e526 100644 --- a/wp-includes/media.php +++ b/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 diff --git a/wp-includes/nav-menu.php b/wp-includes/nav-menu.php index 48d8000c35..7474e6629b 100644 --- a/wp-includes/nav-menu.php +++ b/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 ); diff --git a/wp-includes/pluggable-deprecated.php b/wp-includes/pluggable-deprecated.php index 03eeae482d..11e393ddfd 100644 --- a/wp-includes/pluggable-deprecated.php +++ b/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()' ); diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php index cd82331e9d..933e127abe 100644 --- a/wp-includes/pluggable.php +++ b/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 - * 0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago. + * @return int|false 1 if the nonce is valid and generated between 0-12 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 - * 0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago. + * @return int|false 1 if the nonce is valid and generated between 0-12 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 - * 0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago. + * @return int|false 1 if the nonce is valid and generated between 0-12 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 `` tag for the user's avatar. False on failure. + * @return string|false `` tag for the user's avatar. False on failure. */ function get_avatar( $id_or_email, $size = 96, $default = '', $alt = '', $args = null ) { $defaults = array( diff --git a/wp-includes/pomo/po.php b/wp-includes/pomo/po.php index 69a486061f..c16abf979a 100644 --- a/wp-includes/pomo/po.php +++ b/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 ) { diff --git a/wp-includes/post-template.php b/wp-includes/post-template.php index 75ffc47ab2..ed1a2b02ac 100644 --- a/wp-includes/post-template.php +++ b/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 { diff --git a/wp-includes/rest-api/class-wp-rest-server.php b/wp-includes/rest-api/class-wp-rest-server.php index 1b1bed5d73..bbd930051f 100644 --- a/wp-includes/rest-api/class-wp-rest-server.php +++ b/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'; diff --git a/wp-includes/revision.php b/wp-includes/revision.php index 802e3478fa..da038a21be 100644 --- a/wp-includes/revision.php +++ b/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 ); diff --git a/wp-includes/user.php b/wp-includes/user.php index d6075ca5a9..964ec9b8d1 100644 --- a/wp-includes/user.php +++ b/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 - * determine_current_user filter. + * @param int|bool $user_id The user ID (or false) as received from + * 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; diff --git a/wp-includes/version.php b/wp-includes/version.php index 594291bfa5..fe5da4edf9 100644 --- a/wp-includes/version.php +++ b/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. diff --git a/wp-includes/wp-db.php b/wp-includes/wp-db.php index 5c2cc4afed..c697287c8f 100644 --- a/wp-includes/wp-db.php +++ b/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 - * @return false|void False if the showing of errors is disabled. + * @param string $str The error to display. + * @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 $error_code Optional. A Computer readable string to identify the error. - * @return false|void + * @param string $message The error message. + * @param string $error_code Optional. A computer-readable string to identify the error. + * @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 ) { diff --git a/wp-signup.php b/wp-signup.php index 917b7d1267..9a4cb47049 100644 --- a/wp-signup.php +++ b/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 ) ) {