diff --git a/src/wp-content/themes/twentytwenty/inc/template-tags.php b/src/wp-content/themes/twentytwenty/inc/template-tags.php index 28eaad2b4e42d..7987e4c57af3f 100644 --- a/src/wp-content/themes/twentytwenty/inc/template-tags.php +++ b/src/wp-content/themes/twentytwenty/inc/template-tags.php @@ -107,8 +107,8 @@ function twentytwenty_site_logo( $args = array(), $display = true ) { * @since Twenty Twenty 1.0 * * @param bool $display Display or return the HTML. - * @return string|void The HTML when `$display` is false, null when the site has no - * description. Nothing otherwise. + * @return string|null|void The HTML when `$display` is false, null when the site has no + * description. Nothing otherwise. * @phpstan-return ( $display is true ? void : string|null ) */ function twentytwenty_site_description( $display = true ) { diff --git a/src/wp-includes/author-template.php b/src/wp-includes/author-template.php index 77b1adaf96ac0..b27bbf62379d4 100644 --- a/src/wp-includes/author-template.php +++ b/src/wp-includes/author-template.php @@ -453,7 +453,7 @@ function get_author_posts_url( $author_id, $author_nicename = '' ) { * @phpstan-return ( * $args is array{ echo: false|0|''|'0', ... } * ? string - * : ( $args is ''|array ? void : string|null ) + * : ( $args is ''|'0'|array ? void : string|null ) * ) */ function wp_list_authors( $args = '' ) { diff --git a/src/wp-includes/bookmark-template.php b/src/wp-includes/bookmark-template.php index b3f94decef2d2..37d55bf4561f6 100644 --- a/src/wp-includes/bookmark-template.php +++ b/src/wp-includes/bookmark-template.php @@ -210,7 +210,7 @@ function _walk_bookmarks( $bookmarks, $args = '' ) { * @phpstan-return ( * $args is array{ echo: false|0|''|'0', ... } * ? string - * : ( $args is ''|array ? void : string|null ) + * : ( $args is ''|'0'|array ? void : string|null ) * ) */ function wp_list_bookmarks( $args = '' ) { diff --git a/src/wp-includes/category-template.php b/src/wp-includes/category-template.php index 633c8faf81c51..f268f93cbc461 100644 --- a/src/wp-includes/category-template.php +++ b/src/wp-includes/category-template.php @@ -710,15 +710,15 @@ function wp_list_categories( $args = '' ) { * associated with the taxonomy. * @type bool $echo Whether or not to echo the return value. Default true. * } - * @return string|string[]|void Tag cloud as a string, or as an array when the 'format' argument - * is 'array'. Null on failure. Nothing when 'echo' is true and - * 'format' is not 'array'. + * @return string|string[]|null|void Tag cloud as a string, or as an array when the 'format' + * argument is 'array'. Null on failure. Nothing when 'echo' is + * true and 'format' is not 'array'. * @phpstan-return ( * $args is array{ format: 'array', ... } * ? string[]|null * : ( $args is array{ echo: false|0|''|'0', ... } * ? string|null - * : ( $args is ''|array ? void : string|string[]|null ) ) + * : ( $args is ''|'0'|array ? void : string|string[]|null ) ) * ) */ function wp_tag_cloud( $args = '' ) { diff --git a/src/wp-includes/class-wpdb.php b/src/wp-includes/class-wpdb.php index a676d395ee95c..5cf9508f8fbdf 100644 --- a/src/wp-includes/class-wpdb.php +++ b/src/wp-includes/class-wpdb.php @@ -1794,7 +1794,7 @@ public function esc_like( $text ) { * @global array $EZSQL_ERROR Stores error information of query and error string. * * @param string $str The error to display. - * @return null|false Null if the showing of errors is enabled, false if disabled. + * @return void|false Void if the showing of errors is enabled, false if disabled. */ public function print_error( $str = '' ) { global $EZSQL_ERROR; @@ -1855,8 +1855,6 @@ public function print_error( $str = '' ) { $query ); } - - return null; } /** @@ -4068,7 +4066,7 @@ public function close() { * @since 2.5.0 * * @global string $required_mysql_version The minimum required MySQL version string. - * @return WP_Error|null + * @return void|WP_Error Void if the server meets the minimum version, WP_Error if not. */ public function check_database_version() { global $required_mysql_version; @@ -4079,8 +4077,6 @@ public function check_database_version() { /* translators: 1: WordPress version number, 2: Minimum required MySQL version number. */ return new WP_Error( 'database_version', sprintf( __( 'Error: WordPress %1$s requires MySQL %2$s or higher' ), $wp_version, $required_mysql_version ) ); } - - return null; } /** diff --git a/src/wp-includes/comment-template.php b/src/wp-includes/comment-template.php index 68091c5f4c65e..f96cf18f78f13 100644 --- a/src/wp-includes/comment-template.php +++ b/src/wp-includes/comment-template.php @@ -1244,10 +1244,12 @@ function get_trackback_url() { * * @see get_trackback_url() * - * @param bool $deprecated_echo Deprecated. Use {@see get_trackback_url()}. Echo the URL or + * @param true $deprecated_echo Deprecated. Use {@see get_trackback_url()}. Echo the URL or * return it. Default true. * @return string|void The trackback URL when `$deprecated_echo` is false, nothing otherwise. * @phpstan-return ( $deprecated_echo is true ? void : string ) + * + * @phpstan-ignore conditionalType.alwaysTrue (Typed `true` to flag the deprecated argument.) */ function trackback_url( $deprecated_echo = true ) { if ( true !== $deprecated_echo ) { @@ -2233,12 +2235,12 @@ function _get_comment_reply_id( $post = null ) { * @type bool $echo Whether to echo the output or return it. Default true. * } * @param WP_Comment[] $comments Optional. Array of WP_Comment objects. Default null. - * @return string|void HTML list of comments when 'echo' is false, null when there are no - * comments to list. Nothing otherwise. + * @return string|null|void HTML list of comments when 'echo' is false, null when there are + * no comments to list. Nothing otherwise. * @phpstan-return ( * $args is array{ echo: false|0|''|'0', ... } * ? string|null - * : ( $args is ''|array ? void : string|null ) + * : ( $args is ''|'0'|array ? void : string|null ) * ) */ function wp_list_comments( $args = array(), $comments = null ) { diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php index 5b59d393213ac..bf0001c28e51c 100644 --- a/src/wp-includes/functions.php +++ b/src/wp-includes/functions.php @@ -8737,8 +8737,8 @@ function wp_get_default_update_php_url() { * @param string $before Markup to output before the annotation. Default `

`. * @param string $after Markup to output after the annotation. Default `

`. * @param bool $display Whether to echo or return the markup. Default `true` for echo. - * @return string|void Update PHP page annotation when `$display` is false, null when no - * annotation is available. Nothing otherwise. + * @return string|null|void Update PHP page annotation when `$display` is false, null when + * no annotation is available. Nothing otherwise. * @phpstan-return ( $display is true ? void : string|null ) */ function wp_update_php_annotation( $before = '

', $after = '

', $display = true ) { diff --git a/src/wp-includes/general-template.php b/src/wp-includes/general-template.php index e5c65279e52b5..7ba1d623f4631 100644 --- a/src/wp-includes/general-template.php +++ b/src/wp-includes/general-template.php @@ -1705,8 +1705,8 @@ function wp_title( $sep = '»', $display = true, $seplocation = '' ) { * * @param string $prefix Optional. What to display before the title. * @param bool $display Optional. Whether to display or retrieve title. Default true. - * @return string|void Title when retrieving, null on failure. - * Nothing when displaying. + * @return string|null|void Title when retrieving, null on failure. + * Nothing when displaying. * @phpstan-return ( $display is true ? void : string|null ) */ function single_post_title( $prefix = '', $display = true ) { @@ -1743,8 +1743,8 @@ function single_post_title( $prefix = '', $display = true ) { * * @param string $prefix Optional. What to display before the title. * @param bool $display Optional. Whether to display or retrieve title. Default true. - * @return string|void Title when retrieving, null on failure. - * Nothing when displaying. + * @return string|null|void Title when retrieving, null on failure. + * Nothing when displaying. * @phpstan-return ( $display is true ? void : string|null ) */ function post_type_archive_title( $prefix = '', $display = true ) { @@ -1787,8 +1787,8 @@ function post_type_archive_title( $prefix = '', $display = true ) { * * @param string $prefix Optional. What to display before the title. * @param bool $display Optional. Whether to display or retrieve title. Default true. - * @return string|void Title when retrieving, null on failure. - * Nothing when displaying. + * @return string|null|void Title when retrieving, null on failure. + * Nothing when displaying. * @phpstan-return ( $display is true ? void : string|null ) */ function single_cat_title( $prefix = '', $display = true ) { @@ -1810,8 +1810,8 @@ function single_cat_title( $prefix = '', $display = true ) { * * @param string $prefix Optional. What to display before the title. * @param bool $display Optional. Whether to display or retrieve title. Default true. - * @return string|void Title when retrieving, null on failure. - * Nothing when displaying. + * @return string|null|void Title when retrieving, null on failure. + * Nothing when displaying. * @phpstan-return ( $display is true ? void : string|null ) */ function single_tag_title( $prefix = '', $display = true ) { @@ -1833,8 +1833,8 @@ function single_tag_title( $prefix = '', $display = true ) { * * @param string $prefix Optional. What to display before the title. * @param bool $display Optional. Whether to display or retrieve title. Default true. - * @return string|void Title when retrieving, null on failure. - * Nothing when displaying. + * @return string|null|void Title when retrieving, null on failure. + * Nothing when displaying. * @phpstan-return ( $display is true ? void : string|null ) */ function single_term_title( $prefix = '', $display = true ) { @@ -2235,12 +2235,12 @@ 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 Archive links when 'echo' is false, null when the post type is - * not viewable. Nothing otherwise. + * @return string|null|void Archive links when 'echo' is false, null when the post type is + * not viewable. Nothing otherwise. * @phpstan-return ( * $args is array{ echo: false|0|''|'0', ... } * ? string|null - * : ( $args is ''|array ? void : string|null ) + * : ( $args is ''|'0'|array ? void : string|null ) * ) */ function wp_get_archives( $args = '' ) { @@ -2511,8 +2511,8 @@ function calendar_week_mod( $num ) { * @type bool $display Whether to display the calendar output. Default true. * @type string $post_type Optional. Post type. Default 'post'. * } - * @return string|void Calendar HTML when `$display` is false, null when the site has - * no posts. Nothing otherwise. + * @return string|null|void Calendar HTML when `$display` is false, null when the site has + * no posts. Nothing otherwise. * @phpstan-return ( $args is array{ display: false|0|''|'0', ... } ? string|null : void ) */ function get_calendar( $args = array() ) { @@ -2927,7 +2927,8 @@ function the_date_xml() { * @param string $before Optional. Output before the date. Default empty. * @param string $after Optional. Output after the date. Default empty. * @param bool $display Optional. Whether to echo the date or return it. Default true. - * @return string|void String if retrieving. + * @return string|void The date when `$display` is false, or an empty string when the post's + * date matches the previously output one. Nothing otherwise. * @phpstan-return ( $display is true ? void : string ) */ function the_date( $format = '', $before = '', $after = '', $display = true ) { @@ -3003,7 +3004,7 @@ function get_the_date( $format = '', $post = null ) { * @param string $before Optional. Output before the date. Default empty. * @param string $after Optional. Output after the date. Default empty. * @param bool $display Optional. Whether to echo the date or return it. Default true. - * @return string|void String if retrieving. + * @return string|void The modified date when `$display` is false, nothing otherwise. * @phpstan-return ( $display is true ? void : string ) */ function the_modified_date( $format = '', $before = '', $after = '', $display = true ) { diff --git a/src/wp-includes/l10n.php b/src/wp-includes/l10n.php index a0be55146f7e6..1190a79b35c39 100644 --- a/src/wp-includes/l10n.php +++ b/src/wp-includes/l10n.php @@ -1736,8 +1736,13 @@ function wp_get_l10n_php_file_data( $php_file ) { * instead of an empty value. Default false. * } * @return string|void HTML dropdown list of languages. Always returned, whether or not - * 'echo' is true; nothing is returned when the required `id` or `name` - * argument is missing. + * 'echo' is true; nothing is returned when the 'id' or 'name' + * argument is empty. + * @phpstan-return ( + * $args is array{ id: ''|'0', ... } + * ? void + * : ( $args is array{ name: ''|'0', ... } ? void : string ) + * ) */ function wp_dropdown_languages( $args = array() ) { diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php index cabb7cedfab21..f4accadb0bf3a 100644 --- a/src/wp-includes/link-template.php +++ b/src/wp-includes/link-template.php @@ -1131,8 +1131,8 @@ function get_edit_term_link( $term, $taxonomy = '', $object_type = '' ) { * @param string $after Optional. Display after edit link. Default empty. * @param int|WP_Term|null $term Optional. Term ID or object. If null, the queried object will be inspected. Default null. * @param bool $display Optional. Whether or not to echo the return. Default true. - * @return string|void HTML content when retrieving, null on failure or without the - * capability to edit the term. Nothing when displaying. + * @return string|null|void HTML content when retrieving, null on failure or without the + * capability to edit the term. Nothing when displaying. * @phpstan-return ( $display is true ? void : string|null ) */ function edit_term_link( $link = '', $before = '', $after = '', $term = null, $display = true ) { @@ -3268,16 +3268,16 @@ 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|string[]|void Markup for comment page links, or an array of them when the 'type' - * argument is 'array'. Null if the query is not for an existing single - * post of any post type. Nothing when 'echo' is true and 'type' is not - * 'array'. + * @return string|string[]|null|void Markup for comment page links, or an array of them when + * the 'type' argument is 'array'. Null if the query is not for + * an existing single post of any post type. Nothing when 'echo' + * is true and 'type' is not 'array'. * @phpstan-return ( * $args is array{ type: 'array', ... } * ? string[]|null * : ( $args is array{ echo: false|0|''|'0', ... } * ? string|null - * : ( $args is ''|array ? void : string|string[]|null ) ) + * : ( $args is ''|'0'|array ? void : string|string[]|null ) ) * ) */ function paginate_comments_links( $args = array() ) { diff --git a/src/wp-includes/post-template.php b/src/wp-includes/post-template.php index 0c21f6815a28b..beb53c92b0c46 100644 --- a/src/wp-includes/post-template.php +++ b/src/wp-includes/post-template.php @@ -37,8 +37,8 @@ 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 $display Optional. Whether to echo or return the title. Default true for echo. - * @return string|void Current post title when `$display` is false, null when the title - * is empty. Nothing otherwise. + * @return string|null|void Current post title when `$display` is false, null when the + * title is empty. Nothing otherwise. * @phpstan-return ( $display is true ? void : string|null ) */ function the_title( $before = '', $after = '', $display = true ) { @@ -77,12 +77,12 @@ function the_title( $before = '', $after = '', $display = 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 The title attribute when 'echo' is false, null when the title is - * empty. Nothing otherwise. + * @return string|null|void The title attribute when 'echo' is false, null when the title + * is empty. Nothing otherwise. * @phpstan-return ( * $args is array{ echo: false|0|''|'0', ... } * ? string|null - * : ( $args is ''|array ? void : string|null ) + * : ( $args is ''|'0'|array ? void : string|null ) * ) */ function the_title_attribute( $args = '' ) { @@ -1309,7 +1309,7 @@ function wp_dropdown_pages( $args = '' ) { * @phpstan-return ( * $args is array{ echo: false|0|''|'0', ... } * ? string - * : ( $args is ''|array ? void : string|null ) + * : ( $args is ''|'0'|array ? void : string|null ) * ) */ function wp_list_pages( $args = '' ) { @@ -1437,7 +1437,7 @@ function wp_list_pages( $args = '' ) { * @phpstan-return ( * $args is array{ echo: false|0|''|'0', ... } * ? string - * : ( $args is ''|array ? void : string|null ) + * : ( $args is ''|'0'|array ? void : string|null ) * ) */ function wp_page_menu( $args = array() ) { diff --git a/src/wp-includes/user.php b/src/wp-includes/user.php index 0a0aed8348073..3e8d76b1e4a3b 100644 --- a/src/wp-includes/user.php +++ b/src/wp-includes/user.php @@ -911,7 +911,7 @@ function get_users( $args = array() ) { * @phpstan-return ( * $args is array{ echo: false|0|''|'0', ... } * ? string - * : ( $args is ''|array ? void : string|null ) + * : ( $args is ''|'0'|array ? void : string|null ) * ) */ function wp_list_users( $args = array() ) {