diff --git a/src/wp-content/themes/twentytwenty/inc/template-tags.php b/src/wp-content/themes/twentytwenty/inc/template-tags.php
index e15ae6652bbec..28eaad2b4e42d 100644
--- a/src/wp-content/themes/twentytwenty/inc/template-tags.php
+++ b/src/wp-content/themes/twentytwenty/inc/template-tags.php
@@ -107,13 +107,15 @@ 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 to display.
+ * @return string|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 ) {
$description = get_bloginfo( 'description' );
if ( ! $description ) {
- return;
+ return null;
}
$wrapper = '%s
';
diff --git a/src/wp-includes/author-template.php b/src/wp-includes/author-template.php
index 4c715a62b51f1..77b1adaf96ac0 100644
--- a/src/wp-includes/author-template.php
+++ b/src/wp-includes/author-template.php
@@ -449,7 +449,12 @@ function get_author_posts_url( $author_id, $author_nicename = '' ) {
* @type int[]|string $exclude Array or comma/space-separated list of author IDs to exclude. Default empty.
* @type int[]|string $include Array or comma/space-separated list of author IDs to include. Default empty.
* }
- * @return void|string Void if 'echo' argument is true, list of authors if 'echo' is false.
+ * @return string|void List of authors if 'echo' is false, nothing otherwise.
+ * @phpstan-return (
+ * $args is array{ echo: false|0|''|'0', ... }
+ * ? string
+ * : ( $args is ''|array ? void : string|null )
+ * )
*/
function wp_list_authors( $args = '' ) {
global $wpdb;
diff --git a/src/wp-includes/bookmark-template.php b/src/wp-includes/bookmark-template.php
index 893494a7e92cd..b3f94decef2d2 100644
--- a/src/wp-includes/bookmark-template.php
+++ b/src/wp-includes/bookmark-template.php
@@ -206,7 +206,12 @@ function _walk_bookmarks( $bookmarks, $args = '' ) {
* $categorize is true. Accepts 'ASC' (ascending) or 'DESC' (descending).
* Default 'ASC'.
* }
- * @return void|string Void if 'echo' argument is true, HTML list of bookmarks if 'echo' is false.
+ * @return string|void HTML list of bookmarks if 'echo' is false, nothing otherwise.
+ * @phpstan-return (
+ * $args is array{ echo: false|0|''|'0', ... }
+ * ? string
+ * : ( $args is ''|array ? void : string|null )
+ * )
*/
function wp_list_bookmarks( $args = '' ) {
$defaults = array(
diff --git a/src/wp-includes/category-template.php b/src/wp-includes/category-template.php
index 76409d0832f2e..633c8faf81c51 100644
--- a/src/wp-includes/category-template.php
+++ b/src/wp-includes/category-template.php
@@ -710,8 +710,16 @@ function wp_list_categories( $args = '' ) {
* associated with the taxonomy.
* @type bool $echo Whether or not to echo the return value. Default true.
* }
- * @return void|string|string[] Void if 'echo' argument is true, or on failure. Otherwise, tag cloud
- * as a string or an array, depending on 'format' argument.
+ * @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'.
+ * @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 ) )
+ * )
*/
function wp_tag_cloud( $args = '' ) {
$defaults = array(
@@ -745,7 +753,7 @@ function wp_tag_cloud( $args = '' ) {
); // Always query top tags.
if ( empty( $tags ) || is_wp_error( $tags ) ) {
- return;
+ return null;
}
foreach ( $tags as $key => $tag ) {
@@ -756,7 +764,7 @@ function wp_tag_cloud( $args = '' ) {
}
if ( is_wp_error( $link ) ) {
- return;
+ return null;
}
$tags[ $key ]->link = $link;
diff --git a/src/wp-includes/class-wp-scripts.php b/src/wp-includes/class-wp-scripts.php
index e48658a1e7f7c..f8d32d375d040 100644
--- a/src/wp-includes/class-wp-scripts.php
+++ b/src/wp-includes/class-wp-scripts.php
@@ -201,8 +201,9 @@ public function print_scripts( $handles = false, $group = false ) {
* @param string $handle The script's registered handle.
* @param bool $display Optional. Whether to print the extra script
* instead of just returning it. Default true.
- * @return bool|string|null Null if no data exists, extra scripts if `$display` is true,
+ * @return bool|string|null Null if no data exists, extra scripts if `$display` is false,
* true otherwise.
+ * @phpstan-return ( $display is true ? true|null : string|null )
*/
public function print_scripts_l10n( $handle, $display = true ) {
_deprecated_function( __FUNCTION__, '3.3.0', 'WP_Scripts::print_extra_script()' );
@@ -217,8 +218,9 @@ public function print_scripts_l10n( $handle, $display = true ) {
* @param string $handle The script's registered handle.
* @param bool $display Optional. Whether to print the extra script
* instead of just returning it. Default true.
- * @return bool|string|null Null if no data exists, extra scripts if `$display` is true,
+ * @return bool|string|null Null if no data exists, extra scripts if `$display` is false,
* true otherwise.
+ * @phpstan-return ( $display is true ? true|null : string|null )
*/
public function print_extra_script( $handle, $display = true ) {
$output = $this->get_data( $handle, 'data' );
diff --git a/src/wp-includes/class-wp-styles.php b/src/wp-includes/class-wp-styles.php
index 20487ca9b7068..531940951a5a1 100644
--- a/src/wp-includes/class-wp-styles.php
+++ b/src/wp-includes/class-wp-styles.php
@@ -296,8 +296,9 @@ public function add_inline_style( $handle, $code ) {
* @param string $handle The style's registered handle.
* @param bool $display Optional. Whether to print the inline style
* instead of just returning it. Default true.
- * @return string|bool False if no data exists, inline styles if `$display` is true,
+ * @return string|bool False if no data exists, inline styles if `$display` is false,
* true otherwise.
+ * @phpstan-return ( $display is true ? bool : string|false )
*/
public function print_inline_style( $handle, $display = true ) {
$output = $this->get_data( $handle, 'after' );
diff --git a/src/wp-includes/comment-template.php b/src/wp-includes/comment-template.php
index 43bd68ff972a4..68091c5f4c65e 100644
--- a/src/wp-includes/comment-template.php
+++ b/src/wp-includes/comment-template.php
@@ -488,7 +488,8 @@ function comment_author_url_link( $link_text = '', $before = '', $after = '', $c
* @param int|WP_Post $post Optional. Post ID or WP_Post object. Default current post.
* @param bool $display Optional. Whether to print or return the output.
* Default true.
- * @return void|string Void if `$display` argument is true, comment classes if `$display` is false.
+ * @return string|void Comment classes if `$display` is false, nothing otherwise.
+ * @phpstan-return ( $display is true ? void : string )
*/
function comment_class( $css_class = '', $comment = null, $post = null, $display = true ) {
// Separates classes with a single space, collates classes for comment DIV.
@@ -1239,10 +1240,14 @@ function get_trackback_url() {
* Displays the current post's trackback URL.
*
* @since 0.71
+ * @since 2.5.0 Deprecated the `$deprecated_echo` argument.
*
- * @param bool $deprecated_echo Not used.
- * @return void|string Should only be used to echo the trackback URL, use get_trackback_url()
- * for the result instead.
+ * @see get_trackback_url()
+ *
+ * @param bool $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 )
*/
function trackback_url( $deprecated_echo = true ) {
if ( true !== $deprecated_echo ) {
@@ -2228,8 +2233,13 @@ 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 void|string Void if 'echo' argument is true, or no comments to list.
- * Otherwise, HTML list of comments.
+ * @return string|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 )
+ * )
*/
function wp_list_comments( $args = array(), $comments = null ) {
global $wp_query, $comment_alt, $comment_depth, $comment_thread_alt, $overridden_cpage, $in_comment_loop;
@@ -2274,12 +2284,12 @@ function wp_list_comments( $args = array(), $comments = null ) {
if ( null !== $comments ) {
$comments = (array) $comments;
if ( empty( $comments ) ) {
- return;
+ return null;
}
if ( 'all' !== $parsed_args['type'] ) {
$comments_by_type = separate_comments( $comments );
if ( empty( $comments_by_type[ $parsed_args['type'] ] ) ) {
- return;
+ return null;
}
$_comments = $comments_by_type[ $parsed_args['type'] ];
} else {
@@ -2320,7 +2330,7 @@ function wp_list_comments( $args = array(), $comments = null ) {
if ( 'all' !== $parsed_args['type'] ) {
$comments_by_type = separate_comments( $comments );
if ( empty( $comments_by_type[ $parsed_args['type'] ] ) ) {
- return;
+ return null;
}
$_comments = $comments_by_type[ $parsed_args['type'] ];
@@ -2332,14 +2342,14 @@ function wp_list_comments( $args = array(), $comments = null ) {
// Otherwise, fall back on the comments from `$wp_query->comments`.
} else {
if ( empty( $wp_query->comments ) ) {
- return;
+ return null;
}
if ( 'all' !== $parsed_args['type'] ) {
if ( empty( $wp_query->comments_by_type ) ) {
$wp_query->comments_by_type = separate_comments( $wp_query->comments );
}
if ( empty( $wp_query->comments_by_type[ $parsed_args['type'] ] ) ) {
- return;
+ return null;
}
$_comments = $wp_query->comments_by_type[ $parsed_args['type'] ];
} else {
diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index 3d488c286d4a3..5b59d393213ac 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -8737,19 +8737,22 @@ 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|null Update PHP page annotation if available and $display is false, null otherwise.
+ * @return string|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 ) {
$annotation = wp_get_update_php_annotation();
- if ( $annotation ) {
- if ( $display ) {
- echo $before . $annotation . $after;
- } else {
- return $before . $annotation . $after;
- }
+ if ( ! $annotation ) {
+ return null;
}
- return null;
+
+ if ( ! $display ) {
+ return $before . $annotation . $after;
+ }
+
+ echo $before . $annotation . $after;
}
/**
diff --git a/src/wp-includes/general-template.php b/src/wp-includes/general-template.php
index b626b5ca605ce..85493cb0b059f 100644
--- a/src/wp-includes/general-template.php
+++ b/src/wp-includes/general-template.php
@@ -236,7 +236,8 @@ function get_template_part( $slug, $name = null, $args = array() ) {
* multiple search forms on the same page and improve
* accessibility. Default empty.
* }
- * @return void|string Void if 'echo' argument is true, search form HTML if 'echo' is false.
+ * @return string|void Search form HTML if 'echo' is false, nothing otherwise.
+ * @phpstan-return ( $args is array{ echo: false|0|''|'0', ... } ? string : void )
*/
function get_search_form( $args = array() ) {
/**
@@ -581,7 +582,8 @@ function wp_get_tooltip_helper( $content, $args = array() ) {
*
* @param string $redirect Optional path to redirect to on login/logout.
* @param bool $display Default to echo and not return the link.
- * @return void|string Void if `$display` argument is true, log in/out link if `$display` is false.
+ * @return string|void Log in/out link if `$display` is false, nothing otherwise.
+ * @phpstan-return ( $display is true ? void : string )
*/
function wp_loginout( $redirect = '', $display = true ) {
if ( ! is_user_logged_in() ) {
@@ -721,7 +723,8 @@ function wp_registration_url() {
* Default false.
*
* }
- * @return void|string Void if 'echo' argument is true, login form HTML if 'echo' is false.
+ * @return string|void Login form HTML if 'echo' is false, nothing otherwise.
+ * @phpstan-return ( $args is array{ echo: false|0|''|'0', ... } ? string : void )
*/
function wp_login_form( $args = array() ) {
$defaults = array(
@@ -901,8 +904,9 @@ function wp_lostpassword_url( $redirect = '' ) {
* @param string $before Text to output before the link. Default ``.
* @param string $after Text to output after the link. Default ``.
* @param bool $display Default to echo and not return the link.
- * @return void|string Void if `$display` argument is true, registration or admin link
- * if `$display` is false.
+ * @return string|void Registration or admin link if `$display` is false,
+ * nothing otherwise.
+ * @phpstan-return ( $display is true ? void : string )
*/
function wp_register( $before = '', $after = '', $display = true ) {
if ( ! is_user_logged_in() ) {
@@ -1543,7 +1547,8 @@ function _wp_render_title_tag() {
* Default '»'.
* @param bool $display Optional. Whether to display or retrieve title. Default true.
* @param string $seplocation Optional. Location of the separator (either 'left' or 'right').
- * @return string|null String when `$display` is false, null otherwise.
+ * @return string|void String when `$display` is false, nothing otherwise.
+ * @phpstan-return ( $display is true ? void : string )
*/
function wp_title( $sep = '»', $display = true, $seplocation = '' ) {
global $wp_locale;
@@ -1678,8 +1683,6 @@ function wp_title( $sep = '»', $display = true, $seplocation = '' ) {
}
echo $title;
-
- return null;
}
/**
@@ -1696,7 +1699,9 @@ 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|null Title when retrieving.
+ * @return string|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 ) {
$_post = get_queried_object();
@@ -1720,8 +1725,6 @@ function single_post_title( $prefix = '', $display = true ) {
}
echo $prefix . $title;
-
- return null;
}
/**
@@ -1734,7 +1737,9 @@ 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|null Title when retrieving, null when displaying or on failure.
+ * @return string|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 ) {
if ( ! is_post_type_archive() ) {
@@ -1763,8 +1768,6 @@ function post_type_archive_title( $prefix = '', $display = true ) {
}
echo $prefix . $title;
-
- return null;
}
/**
@@ -1778,10 +1781,16 @@ 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|null Title when retrieving.
+ * @return string|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 ) {
- return single_term_title( $prefix, $display );
+ if ( ! $display ) {
+ return single_term_title( $prefix, false );
+ }
+
+ single_term_title( $prefix, true );
}
/**
@@ -1795,10 +1804,16 @@ 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|null Title when retrieving.
+ * @return string|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 ) {
- return single_term_title( $prefix, $display );
+ if ( ! $display ) {
+ return single_term_title( $prefix, false );
+ }
+
+ single_term_title( $prefix, true );
}
/**
@@ -1812,7 +1827,9 @@ 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|null Title when retrieving.
+ * @return string|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 ) {
$term = get_queried_object();
@@ -1861,8 +1878,6 @@ function single_term_title( $prefix = '', $display = true ) {
}
echo $prefix . $term_name;
-
- return null;
}
/**
@@ -2214,7 +2229,13 @@ 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 void|string Void if 'echo' argument is true, archive links if 'echo' is false.
+ * @return string|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 )
+ * )
*/
function wp_get_archives( $args = '' ) {
global $wpdb, $wp_locale;
@@ -2250,7 +2271,7 @@ function wp_get_archives( $args = '' ) {
$post_type_object = get_post_type_object( $parsed_args['post_type'] );
if ( ! is_post_type_viewable( $post_type_object ) ) {
- return;
+ return null;
}
$parsed_args['post_type'] = $post_type_object->name;
@@ -2484,7 +2505,9 @@ 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 void|string Void if `$display` argument is true, calendar HTML if `$display` is false.
+ * @return string|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() ) {
global $wpdb, $m, $monthnum, $year, $wp_locale, $posts;
@@ -2595,7 +2618,7 @@ function get_calendar( $args = array() ) {
if ( ! $gotsome ) {
$cache[ $key ] = '';
wp_cache_set( 'get_calendar', $cache, 'calendar' );
- return;
+ return null;
}
}
@@ -2898,7 +2921,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|null String if retrieving.
+ * @return string|void String if retrieving.
+ * @phpstan-return ( $display is true ? void : string )
*/
function the_date( $format = '', $before = '', $after = '', $display = true ) {
global $currentday, $previousday;
@@ -2927,8 +2951,6 @@ function the_date( $format = '', $before = '', $after = '', $display = true ) {
}
echo $the_date;
-
- return null;
}
/**
@@ -2975,7 +2997,8 @@ 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|null String if retrieving.
+ * @return string|void String if retrieving.
+ * @phpstan-return ( $display is true ? void : string )
*/
function the_modified_date( $format = '', $before = '', $after = '', $display = true ) {
$the_modified_date = $before . get_the_modified_date( $format ) . $after;
@@ -2997,8 +3020,6 @@ function the_modified_date( $format = '', $before = '', $after = '', $display =
}
echo $the_modified_date;
-
- return null;
}
/**
diff --git a/src/wp-includes/l10n.php b/src/wp-includes/l10n.php
index 0f9dd0d4016a0..a0be55146f7e6 100644
--- a/src/wp-includes/l10n.php
+++ b/src/wp-includes/l10n.php
@@ -1735,7 +1735,9 @@ function wp_get_l10n_php_file_data( $php_file ) {
* @type bool $explicit_option_en_us Whether the English (United States) option uses an explicit value of en_US
* instead of an empty value. Default false.
* }
- * @return string|void HTML dropdown list of languages.
+ * @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.
*/
function wp_dropdown_languages( $args = array() ) {
diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php
index b50328793857e..a785e12d36d47 100644
--- a/src/wp-includes/link-template.php
+++ b/src/wp-includes/link-template.php
@@ -1131,7 +1131,9 @@ 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|null HTML content.
+ * @return string|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 ) {
if ( is_null( $term ) ) {
@@ -1169,8 +1171,6 @@ function edit_term_link( $link = '', $before = '', $after = '', $term = null, $d
}
echo $link;
-
- return null;
}
/**
@@ -2543,7 +2543,8 @@ function get_next_posts_page_link( $max_page = 0 ) {
*
* @param int $max_page Optional. Max pages. Default 0.
* @param bool $display Optional. Whether to echo the link. Default true.
- * @return string|null The link URL for next posts page if `$display = false`.
+ * @return string|void The link URL for next posts page if `$display = false`.
+ * @phpstan-return ( $display is true ? void : string )
*/
function next_posts( $max_page = 0, $display = true ) {
$link = get_next_posts_page_link( $max_page );
@@ -2554,8 +2555,6 @@ function next_posts( $max_page = 0, $display = true ) {
}
echo $output;
-
- return null;
}
/**
@@ -2655,7 +2654,8 @@ function get_previous_posts_page_link() {
* @since 0.71
*
* @param bool $display Optional. Whether to echo the link. Default true.
- * @return string|null The previous posts page link if `$display = false`.
+ * @return string|void The previous posts page link if `$display = false`.
+ * @phpstan-return ( $display is true ? void : string )
*/
function previous_posts( $display = true ) {
$link = get_previous_posts_page_link();
@@ -2666,8 +2666,6 @@ function previous_posts( $display = true ) {
}
echo $output;
-
- return null;
}
/**
@@ -3268,16 +3266,23 @@ 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 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.
+ * @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'.
+ * @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 ) )
+ * )
*/
function paginate_comments_links( $args = array() ) {
global $wp_rewrite;
if ( ! is_singular() ) {
- return;
+ return null;
}
$page = get_query_var( 'cpage' );
diff --git a/src/wp-includes/post-template.php b/src/wp-includes/post-template.php
index ea06ad3b64a7b..0c21f6815a28b 100644
--- a/src/wp-includes/post-template.php
+++ b/src/wp-includes/post-template.php
@@ -37,14 +37,15 @@ 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 void|string Void if `$display` argument is true or the title is empty,
- * current post title if `$display` is false.
+ * @return string|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 ) {
$title = get_the_title();
if ( strlen( $title ) === 0 ) {
- return;
+ return null;
}
$title = $before . $title . $after;
@@ -76,7 +77,13 @@ 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 void|string Void if 'echo' argument is true, the title attribute if 'echo' is false.
+ * @return string|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 )
+ * )
*/
function the_title_attribute( $args = '' ) {
$defaults = array(
@@ -90,7 +97,7 @@ function the_title_attribute( $args = '' ) {
$title = get_the_title( $parsed_args['post'] );
if ( strlen( $title ) === 0 ) {
- return;
+ return null;
}
$title = $parsed_args['before'] . $title . $parsed_args['after'];
@@ -1298,7 +1305,12 @@ function wp_dropdown_pages( $args = '' ) {
* @type Walker $walker Walker instance to use for listing pages. Default empty which results in a
* Walker_Page instance being used.
* }
- * @return void|string Void if 'echo' argument is true, HTML list of pages if 'echo' is false.
+ * @return string|void HTML list of pages if 'echo' is false, nothing otherwise.
+ * @phpstan-return (
+ * $args is array{ echo: false|0|''|'0', ... }
+ * ? string
+ * : ( $args is ''|array ? void : string|null )
+ * )
*/
function wp_list_pages( $args = '' ) {
$defaults = array(
@@ -1421,7 +1433,12 @@ function wp_list_pages( $args = '' ) {
* @type Walker $walker Walker instance to use for listing pages. Default empty which results in a
* Walker_Page instance being used.
* }
- * @return void|string Void if 'echo' argument is true, HTML menu if 'echo' is false.
+ * @return string|void HTML menu if 'echo' is false, nothing otherwise.
+ * @phpstan-return (
+ * $args is array{ echo: false|0|''|'0', ... }
+ * ? string
+ * : ( $args is ''|array ? void : string|null )
+ * )
*/
function wp_page_menu( $args = array() ) {
$defaults = array(
diff --git a/src/wp-includes/user.php b/src/wp-includes/user.php
index 01b567a74d86d..0a0aed8348073 100644
--- a/src/wp-includes/user.php
+++ b/src/wp-includes/user.php
@@ -907,7 +907,12 @@ function get_users( $args = array() ) {
* @type string $exclude An array, comma-, or space-separated list of user IDs to exclude. Default empty.
* @type string $include An array, comma-, or space-separated list of user IDs to include. Default empty.
* }
- * @return string|null The output if echo is false. Otherwise null.
+ * @return string|void The output if 'echo' is false, nothing otherwise.
+ * @phpstan-return (
+ * $args is array{ echo: false|0|''|'0', ... }
+ * ? string
+ * : ( $args is ''|array ? void : string|null )
+ * )
*/
function wp_list_users( $args = array() ) {
$defaults = array(
@@ -1015,8 +1020,6 @@ function wp_list_users( $args = array() ) {
}
echo $return;
-
- return null;
}
/**