Docs: Replace void with null in union return types in wp-includes

src/wp-includes/author-template.php

@@ -449,7 +449,7 @@ 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|null Null if 'echo' argument is true, list of authors if 'echo' is false.
  */
 function wp_list_authors( $args = '' ) {
 	global $wpdb;

src/wp-includes/bookmark-template.php

@@ -206,7 +206,7 @@ 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|null Null if 'echo' argument is true, HTML list of bookmarks if 'echo' is false.
  */
 function wp_list_bookmarks( $args = '' ) {
 	$defaults = array(

src/wp-includes/category-template.php

@@ -532,7 +532,7 @@ function wp_dropdown_categories( $args = '' ) {
  *     @type Walker       $walker                Walker object to use to build the output. Default empty which results
  *                                               in a Walker_Category instance being used.
  * }
- * @return void|string|false Void if 'echo' argument is true, HTML list of categories if 'echo' is false.
+ * @return string|false|null Null 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 = '' ) {
@@ -710,7 +710,7 @@ 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
+ * @return string|string[]|null Null 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 = '' ) {
@@ -745,7 +745,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 +756,7 @@ function wp_tag_cloud( $args = '' ) {
 		}
 
 		if ( is_wp_error( $link ) ) {
-			return;
+			return null;
 		}
 
 		$tags[ $key ]->link = $link;
@@ -1452,7 +1452,7 @@ function get_term_parents_list( $term_id, $taxonomy, $args = array() ) {
  * @param string $before   Optional. String to use before the terms. Default empty.
  * @param string $sep      Optional. String to use between the terms. Default ', '.
  * @param string $after    Optional. String to use after the terms. Default empty.
- * @return void|false Void on success, false on failure.
+ * @return false|null Null on success, false on failure.
  */
 function the_terms( $post_id, $taxonomy, $before = '', $sep = ', ', $after = '' ) {
 	$term_list = get_the_term_list( $post_id, $taxonomy, $before, $sep, $after );

src/wp-includes/class-wp-customize-setting.php

@@ -519,7 +519,7 @@ final public function _multidimensional_preview_filter( $original ) {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @return void|false Void on success, false if cap check fails
+	 * @return false|null Null on success, false if cap check fails
 	 *                    or value isn't set or is invalid.
 	 */
 	final public function save() {

src/wp-includes/class-wp-image-editor-imagick.php

@@ -398,7 +398,7 @@ public function resize( $max_w, $max_h, $crop = false ) {
 	 * @param int    $dst_h       The destination height.
 	 * @param string $filter_name Optional. The Imagick filter to use when resizing. Default 'FILTER_TRIANGLE'.
 	 * @param bool   $strip_meta  Optional. Strip all profiles, excluding color profiles, from the image. Default true.
-	 * @return void|WP_Error
+	 * @return WP_Error|null
 	 */
 	protected function thumbnail_image( $dst_w, $dst_h, $filter_name = 'FILTER_TRIANGLE', $strip_meta = true ) {
 		$allowed_filters = array(

src/wp-includes/class-wp-metadata-lazyloader.php

@@ -75,7 +75,7 @@ public function __construct() {
 	 *
 	 * @param string $object_type Type of object whose meta is to be lazy-loaded. Accepts 'term' or 'comment'.
 	 * @param array  $object_ids  Array of object IDs.
-	 * @return void|WP_Error WP_Error on failure.
+	 * @return WP_Error|null WP_Error on failure.
 	 */
 	public function queue_objects( $object_type, $object_ids ) {
 		if ( ! isset( $this->settings[ $object_type ] ) ) {
@@ -115,7 +115,7 @@ public function queue_objects( $object_type, $object_ids ) {
 	 * @since 4.5.0
 	 *
 	 * @param string $object_type Object type. Accepts 'comment' or 'term'.
-	 * @return void|WP_Error WP_Error on failure.
+	 * @return WP_Error|null WP_Error on failure.
 	 */
 	public function reset_queue( $object_type ) {
 		if ( ! isset( $this->settings[ $object_type ] ) ) {

src/wp-includes/class-wp-xmlrpc-server.php

@@ -1388,7 +1388,7 @@ private function _is_greater_than_one( $count ) {
 	 *
 	 * @param array $post_data
 	 * @param bool  $update
-	 * @return void|IXR_Error
+	 * @return IXR_Error|null
 	 */
 	private function _toggle_sticky( $post_data, $update = false ) {
 		$post_type = get_post_type_object( $post_data['post_type'] );

src/wp-includes/comment-template.php

@@ -488,7 +488,7 @@ 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|null Null if `$display` argument is true, comment classes if `$display` is false.
  */
 function comment_class( $css_class = '', $comment = null, $post = null, $display = true ) {
 	// Separates classes with a single space, collates classes for comment DIV.
@@ -1241,7 +1241,7 @@ function get_trackback_url() {
  * @since 0.71
  *
  * @param bool $deprecated_echo Not used.
- * @return void|string Should only be used to echo the trackback URL, use get_trackback_url()
+ * @return string|null Should only be used to echo the trackback URL, use get_trackback_url()
  *                     for the result instead.
  */
 function trackback_url( $deprecated_echo = true ) {
@@ -2227,7 +2227,7 @@ 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.
+ * @return string|null Null if 'echo' argument is true, or no comments to list.
  *                     Otherwise, HTML list of comments.
  */
 function wp_list_comments( $args = array(), $comments = null ) {
@@ -2273,12 +2273,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 {
@@ -2319,7 +2319,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'] ];
@@ -2331,14 +2331,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 {

src/wp-includes/comment.php

@@ -3090,7 +3090,7 @@ function do_all_trackbacks() {
  * @global wpdb $wpdb WordPress database abstraction object.
  *
  * @param int|WP_Post $post Post ID or object to do trackbacks on.
- * @return void|false Returns false on failure.
+ * @return false|null Null on success, false on failure.
  */
 function do_trackbacks( $post ) {
 	global $wpdb;
@@ -3106,7 +3106,7 @@ function do_trackbacks( $post ) {
 
 	if ( empty( $to_ping ) ) {
 		$wpdb->update( $wpdb->posts, array( 'to_ping' => '' ), array( 'ID' => $post->ID ) );
-		return;
+		return null;
 	}
 
 	if ( empty( $post->post_excerpt ) ) {

src/wp-includes/functions.php

@@ -883,7 +883,7 @@ static function ( $link ) {
  *
  * @param string|null $content Post content. If `null`, the `post_content` field from `$post` is used.
  * @param int|WP_Post $post    Post ID or post object.
- * @return void|false Void on success, false if the post is not found.
+ * @return false|null Null on success, false if the post is not found.
  */
 function do_enclose( $content, $post ) {
 	global $wpdb;

src/wp-includes/general-template.php

@@ -22,7 +22,7 @@
  * @param string|null $name The name of the specialized header. Default null.
  * @param array       $args Optional. Additional arguments passed to the header template.
  *                          Default empty array.
- * @return void|false Void on success, false if the template does not exist.
+ * @return false|null Null on success, false if the template does not exist.
  */
 function get_header( $name = null, $args = array() ) {
 	/**
@@ -66,7 +66,7 @@ function get_header( $name = null, $args = array() ) {
  * @param string|null $name The name of the specialized footer. Default null.
  * @param array       $args Optional. Additional arguments passed to the footer template.
  *                          Default empty array.
- * @return void|false Void on success, false if the template does not exist.
+ * @return false|null Null on success, false if the template does not exist.
  */
 function get_footer( $name = null, $args = array() ) {
 	/**
@@ -110,7 +110,7 @@ function get_footer( $name = null, $args = array() ) {
  * @param string|null $name The name of the specialized sidebar. Default null.
  * @param array       $args Optional. Additional arguments passed to the sidebar template.
  *                          Default empty array.
- * @return void|false Void on success, false if the template does not exist.
+ * @return false|null Null on success, false if the template does not exist.
  */
 function get_sidebar( $name = null, $args = array() ) {
 	/**
@@ -162,7 +162,7 @@ function get_sidebar( $name = null, $args = array() ) {
  * @param string|null $name Optional. The name of the specialized template. Default null.
  * @param array       $args Optional. Additional arguments passed to the template.
  *                          Default empty array.
- * @return void|false Void on success, false if the template does not exist.
+ * @return false|null Null on success, false if the template does not exist.
  */
 function get_template_part( $slug, $name = null, $args = array() ) {
 	/**
@@ -236,7 +236,7 @@ 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|null Null if 'echo' argument is true, search form HTML if 'echo' is false.
  */
 function get_search_form( $args = array() ) {
 	/**
@@ -379,7 +379,7 @@ function get_search_form( $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|null Null if `$display` argument is true, log in/out link if `$display` is false.
  */
 function wp_loginout( $redirect = '', $display = true ) {
 	if ( ! is_user_logged_in() ) {
@@ -519,7 +519,7 @@ function wp_registration_url() {
  *                                     Default false.
  *
  * }
- * @return void|string Void if 'echo' argument is true, login form HTML if 'echo' is false.
+ * @return string|null Null if 'echo' argument is true, login form HTML if 'echo' is false.
  */
 function wp_login_form( $args = array() ) {
 	$defaults = array(
@@ -699,7 +699,7 @@ function wp_lostpassword_url( $redirect = '' ) {
  * @param string $before  Text to output before the link. Default `<li>`.
  * @param string $after   Text to output after the link. Default `</li>`.
  * @param bool   $display Default to echo and not return the link.
- * @return void|string Void if `$display` argument is true, registration or admin link
+ * @return string|null Null if `$display` argument is true, registration or admin link
  *                     if `$display` is false.
  */
 function wp_register( $before = '<li>', $after = '</li>', $display = true ) {
@@ -1997,7 +1997,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 void|string Void if 'echo' argument is true, archive links if 'echo' is false.
+ * @return string|null Null if 'echo' argument is true, archive links if 'echo' is false.
  */
 function wp_get_archives( $args = '' ) {
 	global $wpdb, $wp_locale;
@@ -2033,7 +2033,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;
@@ -2267,7 +2267,7 @@ 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|null Null if `$display` argument is true, calendar HTML if `$display` is false.
  */
 function get_calendar( $args = array() ) {
 	global $wpdb, $m, $monthnum, $year, $wp_locale, $posts;
@@ -2350,7 +2350,7 @@ function get_calendar( $args = array() ) {
 
 		if ( $args['display'] ) {
 			echo $output;
-			return;
+			return null;
 		}
 
 		return $output;
@@ -2378,7 +2378,7 @@ function get_calendar( $args = array() ) {
 		if ( ! $gotsome ) {
 			$cache[ $key ] = '';
 			wp_cache_set( 'get_calendar', $cache, 'calendar' );
-			return;
+			return null;
 		}
 	}
 
@@ -2605,7 +2605,7 @@ function get_calendar( $args = array() ) {
 
 	if ( $args['display'] ) {
 		echo $calendar_output;
-		return;
+		return null;
 	}
 
 	return $calendar_output;

src/wp-includes/link-template.php

@@ -3254,7 +3254,7 @@ 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,
+ * @return string|array|null Null 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.
@@ -3263,7 +3263,7 @@ function paginate_comments_links( $args = array() ) {
 	global $wp_rewrite;
 
 	if ( ! is_singular() ) {
-		return;
+		return null;
 	}
 
 	$page = get_query_var( 'cpage' );

src/wp-includes/nav-menu-template.php

@@ -56,7 +56,7 @@
  *     @type string             $item_spacing         Whether to preserve whitespace within the menu's HTML.
  *                                                    Accepts 'preserve' or 'discard'. Default 'preserve'.
  * }
- * @return void|string|false Void if 'echo' argument is true, menu output if 'echo' is false.
+ * @return string|false|null Null if 'echo' argument is true, menu output if 'echo' is false.
  *                           False if there are no items or no menu was found.
  */
 function wp_nav_menu( $args = array() ) {
@@ -120,7 +120,7 @@ function wp_nav_menu( $args = array() ) {
 	if ( null !== $nav_menu ) {
 		if ( $args->echo ) {
 			echo $nav_menu;
-			return;
+			return null;
 		}
 
 		return $nav_menu;