WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
Sergey Biryukov 2020-01-11 18:32:05 +00:00
parent 2294d65753
commit dd4d98a368
48 changed files with 201 additions and 178 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
wp-admin/includes/class-core-upgrader.php
View File

@ -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;

6
wp-admin/includes/class-wp-community-events.php
View File

@ -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 ) );

2
wp-admin/includes/class-wp-upgrader-skin.php
View File

@ -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'];

12
wp-admin/includes/file.php
View File

@ -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 );

26
wp-admin/includes/plugin.php
View File

@ -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 );

1
wp-admin/includes/template.php
View File

@ -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(

2
wp-admin/includes/theme.php
View File

@ -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;

4
wp-admin/includes/update-core.php
View File

@ -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;

8
wp-admin/includes/update.php
View File

@ -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

4
wp-admin/includes/upgrade.php
View File

@ -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.

2
wp-admin/install-helper.php
View File

@ -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;

7
wp-includes/author-template.php
View File

@ -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;
}
/**

7
wp-includes/bookmark-template.php
View File

@ -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;
}

18
wp-includes/cache.php
View File

@ -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 ) ) {

2
wp-includes/canonical.php
View File

@ -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;

21
wp-includes/category-template.php
View File

@ -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.
* 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,6 +695,7 @@ function wp_tag_cloud( $args = '' ) {
'echo' => true,
'show_count' => 0,
);
$args = wp_parse_args( $args, $defaults );
$tags = get_terms(
@ -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,7 +734,7 @@ 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.
*/
$return = apply_filters( 'wp_tag_cloud', $return, $args );
@ -1383,7 +1388,7 @@ function get_term_parents_list( $term_id, $taxonomy, $args = array() ) {
* @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.
* @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 );

4
wp-includes/class-http.php
View File

@ -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.

2
wp-includes/class-wp-customize-setting.php
View File

@ -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();

2
wp-includes/class-wp-customize-widgets.php
View File

@ -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 ) ) {

2
wp-includes/class-wp-editor.php
View File

@ -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' );

2
wp-includes/class-wp-embed.php
View File

@ -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 ) {

2
wp-includes/class-wp-image-editor.php
View File

@ -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() ) {

2
wp-includes/class-wp-meta-query.php
View File

@ -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.

17
wp-includes/class-wp-oembed.php
View File

@ -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
* @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 );
@ -654,7 +655,7 @@ class WP_oEmbed {
*
* @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.
* @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 ) ) {

24
wp-includes/class-wp-rewrite.php
View File

@ -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 ) ) {

5
wp-includes/comment-template.php
View File

@ -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;

4
wp-includes/comment.php
View File

@ -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 ) ) {

10
wp-includes/cron.php
View File

@ -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' );

8
wp-includes/deprecated.php
View File

@ -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()' );

2
wp-includes/embed.php
View File

@ -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();

2
wp-includes/feed.php
View File

@ -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 );

4
wp-includes/functions.php
View File

@ -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' ) ) {

20
wp-includes/general-template.php
View File

@ -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;

2
wp-includes/http.php
View File

@ -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;

4
wp-includes/l10n.php
View File

@ -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() ) {

19
wp-includes/link-template.php
View File

@ -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 );

10
wp-includes/media.php
View File

@ -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

2
wp-includes/nav-menu.php
View File

@ -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 );

2
wp-includes/pluggable-deprecated.php
View File

@ -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()' );

19
wp-includes/pluggable.php
View File

@ -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 `<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(

2
wp-includes/pomo/po.php
View File

@ -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 ) {

15
wp-includes/post-template.php
View File

@ -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 {

2
wp-includes/rest-api/class-wp-rest-server.php
View File

@ -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';

4
wp-includes/revision.php
View File

@ -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 );

8
wp-includes/user.php
View File

@ -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;

2
wp-includes/version.php
View File

@ -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.

14
wp-includes/wp-db.php
View File

@ -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 ) {

10
wp-signup.php
View File

@ -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 ) ) {