Skip to content

Commit 4c2ee4e

Browse files
SergeyBiryukovSergeyBiryukov
committed
Docs: In various @return tags, list the expected type first, instead of false.
Follow-up to [46696]. See #48303. git-svn-id: https://develop.svn.wordpress.org/trunk@47060 602fd350-edb4-49c9-b593-d223f7449a82
1 parent f9e52f8 commit 4c2ee4e

47 files changed

Lines changed: 200 additions & 177 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ public function upgrade_strings() {
5757
* @type bool $do_rollback Whether to perform this "upgrade" as a rollback.
5858
* Default false.
5959
* }
60-
* @return null|false|WP_Error False or WP_Error on failure, null on success.
60+
* @return null|false|WP_Error Null on success, false or WP_Error on failure.
6161
*/
6262
public function upgrade( $current, $args = array() ) {
6363
global $wp_filesystem;

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -229,7 +229,7 @@ protected function get_request_args( $search = '', $timezone = '' ) {
229229
*
230230
* @since 4.8.0
231231
*
232-
* @return false|string The anonymized address on success; the given address
232+
* @return string|false The anonymized address on success; the given address
233233
* or false on failure.
234234
*/
235235
public static function get_unsafe_client_ip() {
@@ -341,8 +341,8 @@ protected function cache_events( $events, $expiration = false ) {
341341
*
342342
* @since 4.8.0
343343
*
344-
* @return false|array false on failure; an array containing `location`
345-
* and `events` items on success.
344+
* @return array|false An array containing `location` and `events` items
345+
* on success, false on failure.
346346
*/
347347
public function get_cached_events() {
348348
$cached_response = get_site_transient( $this->get_events_transient_key( $this->user_location ) );

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ public function set_result( $result ) {
8181
* @param string $context Optional. Full path to the directory that is tested
8282
* for being writable. Default empty.
8383
* @param bool $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable. Default false.
84-
* @return bool False on failure, true on success.
84+
* @return bool True on success, false on failure.
8585
*/
8686
public function request_filesystem_credentials( $error = false, $context = '', $allow_relaxed_file_ownership = false ) {
8787
$url = $this->options['url'];

‎src/wp-admin/includes/file.php‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1189,8 +1189,8 @@ function verify_file_md5( $filename, $expected_md5 ) {
11891189
* @param string $filename The file to validate.
11901190
* @param string|array $signatures A Signature provided for the file.
11911191
* @param string $filename_for_errors A friendly filename for errors. Optional.
1192-
*
1193-
* @return bool|WP_Error true on success, false if verification not attempted, or WP_Error describing an error condition.
1192+
* @return bool|WP_Error True on success, false if verification not attempted,
1193+
* or WP_Error describing an error condition.
11941194
*/
11951195
function verify_file_signature( $filename, $signatures, $filename_for_errors = false ) {
11961196
if ( ! $filename_for_errors ) {
@@ -1964,12 +1964,11 @@ function request_filesystem_credentials( $form_post, $type = '', $error = false,
19641964
* @param mixed $output Form output to return instead. Default empty.
19651965
* @param string $form_post The URL to post the form to.
19661966
* @param string $type Chosen type of filesystem.
1967-
* @param bool|WP_Error $error Optional. Whether the current request has failed to connect,
1968-
* or an error object. Default false.
1967+
* @param bool|WP_Error $error Whether the current request has failed to connect,
1968+
* or an error object.
19691969
* @param string $context Full path to the directory that is tested for
19701970
* being writable.
19711971
* @param bool $allow_relaxed_file_ownership Whether to allow Group/World writable.
1972-
* Default false.
19731972
* @param array $extra_fields Extra POST fields.
19741973
*/
19751974
$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,
20922091
* @param string[] $types Types of connections.
20932092
* @param array $credentials Credentials to connect with.
20942093
* @param string $type Chosen filesystem method.
2095-
* @param bool|WP_Error $error Error object or status.
2094+
* @param bool|WP_Error $error Whether the current request has failed to connect,
2095+
* or an error object.
20962096
* @param string $context Full path to the directory that is tested for being writable.
20972097
*/
20982098
$types = apply_filters( 'fs_ftp_connection_types', $types, $credentials, $type, $error, $context );

‎src/wp-admin/includes/plugin.php‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -613,7 +613,7 @@ function is_network_only_plugin( $plugin ) {
613613
* @param bool $network_wide Optional. Whether to enable the plugin for all sites in the network
614614
* or just the current site. Multisite only. Default false.
615615
* @param bool $silent Optional. Whether to prevent calling activation hooks. Default false.
616-
* @return null|WP_Error WP_Error on invalid file or null on success.
616+
* @return null|WP_Error Null on success, WP_Error on invalid file.
617617
*/
618618
function activate_plugin( $plugin, $redirect = '', $network_wide = false, $silent = false ) {
619619
$plugin = plugin_basename( trim( $plugin ) );
@@ -1342,7 +1342,7 @@ function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $func
13421342
* to be compatible with sanitize_key().
13431343
* @param callable $function The function to be called to output the content for this page.
13441344
* @param int $position The position in the menu order this item should appear.
1345-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1345+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
13461346
*/
13471347
function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
13481348
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,
14541454
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
14551455
* @param callable $function The function to be called to output the content for this page.
14561456
* @param int $position The position in the menu order this item should appear.
1457-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1457+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
14581458
*/
14591459
function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
14601460
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,
14781478
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
14791479
* @param callable $function The function to be called to output the content for this page.
14801480
* @param int $position The position in the menu order this item should appear.
1481-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1481+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
14821482
*/
14831483
function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
14841484
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
15021502
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
15031503
* @param callable $function The function to be called to output the content for this page.
15041504
* @param int $position The position in the menu order this item should appear.
1505-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1505+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
15061506
*/
15071507
function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
15081508
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
15261526
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
15271527
* @param callable $function The function to be called to output the content for this page.
15281528
* @param int $position The position in the menu order this item should appear.
1529-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1529+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
15301530
*/
15311531
function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
15321532
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
15501550
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
15511551
* @param callable $function The function to be called to output the content for this page.
15521552
* @param int $position The position in the menu order this item should appear.
1553-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1553+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
15541554
*/
15551555
function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
15561556
if ( current_user_can( 'edit_users' ) ) {
@@ -1579,7 +1579,7 @@ function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $fun
15791579
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
15801580
* @param callable $function The function to be called to output the content for this page.
15811581
* @param int $position The position in the menu order this item should appear.
1582-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1582+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
15831583
*/
15841584
function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
15851585
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,
16031603
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
16041604
* @param callable $function The function to be called to output the content for this page.
16051605
* @param int $position The position in the menu order this item should appear.
1606-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1606+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
16071607
*/
16081608
function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
16091609
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
16271627
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
16281628
* @param callable $function The function to be called to output the content for this page.
16291629
* @param int $position The position in the menu order this item should appear.
1630-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1630+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
16311631
*/
16321632
function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
16331633
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
16511651
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
16521652
* @param callable $function The function to be called to output the content for this page.
16531653
* @param int $position The position in the menu order this item should appear.
1654-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1654+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
16551655
*/
16561656
function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
16571657
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
16751675
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
16761676
* @param callable $function The function to be called to output the content for this page.
16771677
* @param int $position The position in the menu order this item should appear.
1678-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1678+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
16791679
*/
16801680
function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
16811681
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
16991699
* @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
17001700
* @param callable $function The function to be called to output the content for this page.
17011701
* @param int $position The position in the menu order this item should appear.
1702-
* @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required.
1702+
* @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
17031703
*/
17041704
function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
17051705
return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );

‎src/wp-admin/includes/template.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ function wp_category_checklist( $post_id = 0, $descendants_and_self = 0, $select
7676
* @type bool $echo Whether to echo the generated markup. False to return the markup instead
7777
* of echoing it. Default true.
7878
* }
79+
* @return string HTML list of input elements.
7980
*/
8081
function wp_terms_checklist( $post_id = 0, $args = array() ) {
8182
$defaults = array(

‎src/wp-admin/includes/theme.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,7 @@ function theme_update_available( $theme ) {
163163
* @staticvar object $themes_update
164164
*
165165
* @param WP_Theme $theme WP_Theme object.
166-
* @return false|string HTML for the update link, or false if invalid info was passed.
166+
* @return string|false HTML for the update link, or false if invalid info was passed.
167167
*/
168168
function get_theme_update_available( $theme ) {
169169
static $themes_update = null;

‎src/wp-admin/includes/update-core.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -880,7 +880,7 @@
880880
*
881881
* @param string $from New release unzipped path.
882882
* @param string $to Path to old WordPress installation.
883-
* @return null|WP_Error WP_Error on failure, null on success.
883+
* @return null|WP_Error Null on success, WP_Error on failure.
884884
*/
885885
function update_core( $from, $to ) {
886886
global $wp_filesystem, $_old_files, $_new_bundled_files, $wpdb;
@@ -1314,7 +1314,7 @@ function update_core( $from, $to ) {
13141314
* @param string $from Source directory.
13151315
* @param string $to Destination directory.
13161316
* @param string[] $skip_list Array of files/folders to skip copying.
1317-
* @return true|WP_Error WP_Error on failure, true on success.
1317+
* @return true|WP_Error True on success, WP_Error on failure.
13181318
*/
13191319
function _copy_dir( $from, $to, $skip_list = array() ) {
13201320
global $wp_filesystem;

‎src/wp-admin/includes/update.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -276,7 +276,7 @@ function core_update_footer( $msg = '' ) {
276276
* @since 2.3.0
277277
*
278278
* @global string $pagenow
279-
* @return false|void
279+
* @return void|false
280280
*/
281281
function update_nag() {
282282
if ( is_multisite() && ! current_user_can( 'update_core' ) ) {
@@ -409,7 +409,7 @@ function wp_plugin_update_rows() {
409409
*
410410
* @param string $file Plugin basename.
411411
* @param array $plugin_data Plugin information.
412-
* @return false|void
412+
* @return void|false
413413
*/
414414
function wp_plugin_update_row( $file, $plugin_data ) {
415415
$current = get_site_transient( 'update_plugins' );
@@ -611,7 +611,7 @@ function wp_theme_update_rows() {
611611
*
612612
* @param string $theme_key Theme stylesheet.
613613
* @param WP_Theme $theme Theme object.
614-
* @return false|void
614+
* @return void|false
615615
*/
616616
function wp_theme_update_row( $theme_key, $theme ) {
617617
$current = get_site_transient( 'update_themes' );
@@ -720,7 +720,7 @@ function wp_theme_update_row( $theme_key, $theme ) {
720720
* @since 2.7.0
721721
*
722722
* @global int $upgrading
723-
* @return false|void
723+
* @return void|false
724724
*/
725725
function maintenance_nag() {
726726
include( ABSPATH . WPINC . '/version.php' ); // include an unmodified $wp_version

‎src/wp-admin/includes/upgrade.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3061,7 +3061,7 @@ function make_site_theme_from_oldschool( $theme_name, $template ) {
30613061
*
30623062
* @param string $theme_name The name of the theme.
30633063
* @param string $template The directory name of the theme.
3064-
* @return false|void
3064+
* @return void|false
30653065
*/
30663066
function make_site_theme_from_default( $theme_name, $template ) {
30673067
$site_dir = WP_CONTENT_DIR . "/themes/$template";
@@ -3136,7 +3136,7 @@ function make_site_theme_from_default( $theme_name, $template ) {
31363136
*
31373137
* @since 1.5.0
31383138
*
3139-
* @return false|string
3139+
* @return string|false
31403140
*/
31413141
function make_site_theme() {
31423142
// Name the theme after the blog.

0 commit comments

Comments
 (0)