Docs: Replace void with null in union return types in various core files

src/wp-includes/canonical.php

@@ -37,13 +37,13 @@
  * @param string $requested_url Optional. The URL that was requested, used to
  *                              figure if redirect is needed.
  * @param bool   $do_redirect   Optional. Redirect to the new URL.
- * @return string|void The string of the URL, if redirect needed.
+ * @return string|null The string of the URL, if redirect needed. Never if a redirect occurs.
  */
 function redirect_canonical( $requested_url = null, $do_redirect = true ) {
 	global $wp_rewrite, $is_IIS, $wp_query, $wpdb, $wp;
 
 	if ( isset( $_SERVER['REQUEST_METHOD'] ) && ! in_array( strtoupper( $_SERVER['REQUEST_METHOD'] ), array( 'GET', 'HEAD' ), true ) ) {
-		return;
+		return null;
 	}
 
 	/*
@@ -62,7 +62,7 @@ function redirect_canonical( $requested_url = null, $do_redirect = true ) {
 	if ( is_admin() || is_search() || is_preview() || is_trackback() || is_favicon()
 		|| ( $is_IIS && ! iis7_supports_permalinks() )
 	) {
-		return;
+		return null;
 	}
 
 	if ( ! $requested_url && isset( $_SERVER['HTTP_HOST'] ) ) {
@@ -74,7 +74,7 @@ function redirect_canonical( $requested_url = null, $do_redirect = true ) {
 
 	$original = parse_url( $requested_url );
 	if ( false === $original ) {
-		return;
+		return null;
 	}
 
 	// Notice fixing.
@@ -771,7 +771,7 @@ function redirect_canonical( $requested_url = null, $do_redirect = true ) {
 	}
 
 	if ( ! $redirect_url || $redirect_url === $requested_url ) {
-		return;
+		return null;
 	}
 
 	// Hex-encoded octets are case-insensitive.
@@ -830,7 +830,7 @@ function lowercase_octets( $matches ) {
 
 	// Yes, again -- in case the filter aborted the request.
 	if ( ! $redirect_url || strip_fragment_from_url( $redirect_url ) === strip_fragment_from_url( $requested_url ) ) {
-		return;
+		return null;
 	}
 
 	if ( $do_redirect ) {
@@ -841,7 +841,7 @@ function lowercase_octets( $matches ) {
 		} else {
 			// Debug.
 			// die("1: $redirect_url<br />2: " . redirect_canonical( $redirect_url, false ) );
-			return;
+			return null;
 		}
 	} else {
 		return $redirect_url;

src/wp-includes/capabilities.php

@@ -1130,11 +1130,11 @@ function get_role( $role ) {
  * @param string                               $display_name Display name for role.
  * @param array<string,bool>|array<int,string> $capabilities Capabilities to be added to the role.
  *                                                           Default empty array.
- * @return WP_Role|void WP_Role object, if the role is added.
+ * @return WP_Role|null WP_Role object, if the role is added.
  */
 function add_role( $role, $display_name, $capabilities = array() ) {
 	if ( empty( $role ) ) {
-		return;
+		return null;
 	}
 
 	return wp_roles()->add_role( $role, $display_name, $capabilities );

src/wp-includes/class-wp-block-type.php

@@ -122,7 +122,7 @@ class WP_Block_Type {
 	 *
 	 * @since 5.8.0
 	 * @since 6.5.0 Only accessible through magic getter. null by default.
-	 * @var array[]|null
+	 * @var array<int, array<string, mixed>>|null
 	 */
 	private $variations = null;
 
@@ -358,8 +358,8 @@ public function __construct( $block_type, $args = array() ) {
 	 *
 	 * @param string $name Deprecated property name.
 	 *
-	 * @return string|string[]|null|void The value read from the new property if the first item in the array provided,
-	 *                                   null when value not found, or void when unknown property name provided.
+	 * @return string|string[]|array<int, array<string, mixed>>|null The value read from the new property if the first item in the array provided,
+	 *                                                              null when value not found or when unknown property name provided.
 	 */
 	public function __get( $name ) {
 		if ( 'variations' === $name ) {
@@ -371,7 +371,7 @@ public function __get( $name ) {
 		}
 
 		if ( ! in_array( $name, $this->deprecated_properties, true ) ) {
-			return;
+			return null;
 		}
 
 		$new_name = $name . '_handles';
@@ -595,7 +595,7 @@ public function get_attributes() {
 	 *
 	 * @since 6.5.0
 	 *
-	 * @return array[]
+	 * @return array<int, array<string, mixed>> Variations.
 	 */
 	public function get_variations() {
 		if ( ! isset( $this->variations ) ) {
@@ -610,8 +610,8 @@ public function get_variations() {
 		 *
 		 * @since 6.5.0
 		 *
-		 * @param array         $variations Array of registered variations for a block type.
-		 * @param WP_Block_Type $block_type The full block type object.
+		 * @param array<int, array<string, mixed>> $variations Array of registered variations for a block type.
+		 * @param WP_Block_Type        $block_type The full block type object.
 		 */
 		return apply_filters( 'get_block_type_variations', $this->variations, $this );
 	}

src/wp-includes/class-wp-plugin-dependencies.php

@@ -29,7 +29,7 @@ class WP_Plugin_Dependencies {
 	 *
 	 * @since 6.5.0
 	 *
-	 * @var array
+	 * @var array<string, string>
 	 */
 	protected static $plugin_dirnames;
 
@@ -71,7 +71,7 @@ class WP_Plugin_Dependencies {
 	 *
 	 * @since 6.5.0
 	 *
-	 * @var array
+	 * @var array<string, array<string, mixed>>
 	 */
 	protected static $dependency_api_data;
 
@@ -295,7 +295,7 @@ public static function get_dependent_names( $plugin_file ) {
 	 * @since 6.5.0
 	 *
 	 * @param string $plugin_file The dependent plugin's filepath, relative to the plugins directory.
-	 * @return array An array of dependency names.
+	 * @return array<string, string> An array of dependency names.
 	 */
 	public static function get_dependency_names( $plugin_file ) {
 		$dependency_api_data = self::get_dependency_api_data();
@@ -346,7 +346,7 @@ public static function get_dependency_filepath( $slug ) {
 	 * @since 6.5.0
 	 *
 	 * @param string $slug The dependency's slug.
-	 * @return array|false The dependency's API data on success, otherwise false.
+	 * @return array<string, mixed>|false The dependency's API data on success, otherwise false.
 	 */
 	public static function get_dependency_data( $slug ) {
 		$dependency_api_data = self::get_dependency_api_data();
@@ -643,13 +643,13 @@ protected static function get_dependency_filepaths() {
 	 *
 	 * @global string $pagenow The filename of the current screen.
 	 *
-	 * @return array|void An array of dependency API data, or void on early exit.
+	 * @return array<string, array<string, mixed>>|null An array of dependency API data, or null on early exit.
 	 */
 	protected static function get_dependency_api_data() {
 		global $pagenow;
 
 		if ( ! is_admin() || ( 'plugins.php' !== $pagenow && 'plugin-install.php' !== $pagenow ) ) {
-			return;
+			return null;
 		}
 
 		if ( is_array( self::$dependency_api_data ) ) {
@@ -727,7 +727,7 @@ protected static function get_dependency_api_data() {
 	 *
 	 * @since 6.5.0
 	 *
-	 * @return array An array of plugin directory names.
+	 * @return array<string, string> An array of plugin directory names.
 	 */
 	protected static function get_plugin_dirnames() {
 		if ( is_array( self::$plugin_dirnames ) ) {

src/wp-includes/class-wp-recovery-mode.php

@@ -160,10 +160,10 @@ public function is_initialized() {
 	 *
 	 * @since 5.2.0
 	 *
-	 * @param array $error Error details from `error_get_last()`.
-	 * @return true|WP_Error|void True if the error was handled and headers have already been sent.
-	 *                            Or the request will exit to try and catch multiple errors at once.
-	 *                            WP_Error if an error occurred preventing it from being handled.
+	 * @param array<string, mixed> $error Error details from `error_get_last()`.
+	 * @return true|WP_Error True if the error was handled and headers have already been sent.
+	 *                       Or the request will exit to try and catch multiple errors at once.
+	 *                       WP_Error if an error occurred preventing it from being handled.
 	 */
 	public function handle_error( array $error ) {
 
@@ -455,6 +455,8 @@ protected function store_error( $error ) {
 	 * next request again. Otherwise it will create a redirect loop.
 	 *
 	 * @since 5.2.0
+	 *
+	 * @return never
 	 */
 	protected function redirect_protected() {
 		// Pluggable is usually loaded after plugins, so we manually include it here for redirection functionality.

src/wp-includes/class-wp-roles.php

@@ -171,11 +171,11 @@ public function reinit() {
 	 * @param string                               $display_name Role display name.
 	 * @param array<string,bool>|array<int,string> $capabilities Capabilities to be added to the role.
 	 *                                                           Default empty array.
-	 * @return WP_Role|void WP_Role object, if the role is added.
+	 * @return WP_Role|null WP_Role object, if the role is added.
 	 */
 	public function add_role( $role, $display_name, $capabilities = array() ) {
 		if ( empty( $role ) || isset( $this->roles[ $role ] ) ) {
-			return;
+			return null;
 		}
 
 		if ( wp_is_numeric_array( $capabilities ) ) {

src/wp-includes/class-wp-scripts.php

@@ -201,7 +201,7 @@ 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|void Void if no data exists, extra scripts if `$display` is true,
+	 * @return bool|string|null Null if no data exists, extra scripts if `$display` is true,
 	 *                          true otherwise.
 	 */
 	public function print_scripts_l10n( $handle, $display = true ) {
@@ -217,13 +217,13 @@ 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|void Void if no data exists, extra scripts if `$display` is true,
+	 * @return bool|string|null Null if no data exists, extra scripts if `$display` is true,
 	 *                          true otherwise.
 	 */
 	public function print_extra_script( $handle, $display = true ) {
 		$output = $this->get_data( $handle, 'data' );
 		if ( ! $output ) {
-			return;
+			return null;
 		}
 
 		/*

src/wp-includes/class-wp-theme-json.php

@@ -4267,7 +4267,7 @@ public function get_data() {
 	 *                   generated in the constructor and merge methods instead
 	 *                   of manually after instantiation.
 	 *
-	 * @return null|void
+	 * @return void
 	 */
 	public function set_spacing_sizes() {
 		_deprecated_function( __METHOD__, '6.6.0' );
@@ -4296,12 +4296,12 @@ public function set_spacing_sizes() {
 					E_USER_NOTICE
 				);
 			}
-			return null;
+			return;
 		}
 
 		// If theme authors want to prevent the generation of the core spacing scale they can set their theme.json spacingScale.steps to 0.
 		if ( 0 === $spacing_scale['steps'] ) {
-			return null;
+			return;
 		}
 
 		$spacing_sizes = static::compute_spacing_sizes( $spacing_scale );

src/wp-includes/class-wp-widget.php

@@ -138,7 +138,7 @@ public function update( $new_instance, $old_instance ) {
 	 * @since 2.8.0
 	 *
 	 * @param array $instance The settings for the particular instance of the widget.
-	 * @return string|void Default return is 'noform'.
+	 * @return string|null Default return is 'noform'. A subclass may opt to return null.
 	 */
 	public function form( $instance ) {
 		echo '<p class="no-options-widget">' . __( 'There are no options for this widget.' ) . '</p>';

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

@@ -353,7 +353,7 @@ public function login_pass_ok(
 	 * @since 1.5.2
 	 *
 	 * @param string|array $data Escape single string or array of strings.
-	 * @return string|void Returns with string is passed, alters by-reference
+	 * @return string|null Returns with string if passed, alters by-reference
 	 *                     when array is passed.
 	 */
 	public function escape( &$data ) {
@@ -368,6 +368,7 @@ public function escape( &$data ) {
 				$v = wp_slash( $v );
 			}
 		}
+		return null;
 	}
 
 	/**

src/wp-includes/comment.php

@@ -2806,7 +2806,7 @@ function wp_defer_comment_counting( $defer = null ) {
  * @param int|null $post_id     Post ID.
  * @param bool     $do_deferred Optional. Whether to process previously deferred
  *                              post comment counts. Default false.
- * @return bool|void True on success, false on failure or if post with ID does
+ * @return bool|null True on success, false on failure or if post with ID does
  *                   not exist.
  */
 function wp_update_comment_count( $post_id, $do_deferred = false ) {
@@ -2831,6 +2831,7 @@ function wp_update_comment_count( $post_id, $do_deferred = false ) {
 	} elseif ( $post_id ) {
 		return wp_update_comment_count_now( $post_id );
 	}
+	return null;
 }
 
 /**
@@ -3313,13 +3314,13 @@ function privacy_ping_filter( $sites ) {
  * @param string $title         Title of post.
  * @param string $excerpt       Excerpt of post.
  * @param int    $post_id       Post ID.
- * @return int|false|void Database query from update.
+ * @return int|false|null Database query from update.
  */
 function trackback( $trackback_url, $title, $excerpt, $post_id ) {
 	global $wpdb;
 
 	if ( empty( $trackback_url ) ) {
-		return;
+		return null;
 	}
 
 	$options            = array();
@@ -3334,7 +3335,7 @@ function trackback( $trackback_url, $title, $excerpt, $post_id ) {
 	$response = wp_safe_remote_post( $trackback_url, $options );
 
 	if ( is_wp_error( $response ) ) {
-		return;
+		return null;
 	}
 
 	$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET pinged = CONCAT(pinged, '\n', %s) WHERE ID = %d", $trackback_url, $post_id ) );

src/wp-includes/formatting.php

@@ -6232,7 +6232,7 @@ function url_shorten( $url, $length = 35 ) {
  * @since 3.4.0
  *
  * @param string $color
- * @return string|void
+ * @return string|null The sanitized hex color, or null if invalid.
  */
 function sanitize_hex_color( $color ) {
 	if ( '' === $color ) {
@@ -6243,6 +6243,7 @@ function sanitize_hex_color( $color ) {
 	if ( preg_match( '|^#([A-Fa-f0-9]{3}){1,2}$|', $color ) ) {
 		return $color;
 	}
+	return null;
 }
 
 /**

src/wp-includes/functions.php

@@ -2994,7 +2994,7 @@ function wp_upload_bits( $name, $deprecated, $bits, $time = null ) {
  * @since 2.5.0
  *
  * @param string $ext The extension to search.
- * @return string|void The file type, example: audio, video, document, spreadsheet, etc.
+ * @return string|null The file type, example: audio, video, document, spreadsheet, etc.
  */
 function wp_ext2type( $ext ) {
 	$ext = strtolower( $ext );
@@ -3005,6 +3005,7 @@ function wp_ext2type( $ext ) {
 			return $type;
 		}
 	}
+	return null;
 }
 
 /**
@@ -8553,7 +8554,7 @@ function wp_get_default_update_php_url() {
  * @param string $after   Markup to output after the annotation. Default `</p>`.
  * @param bool   $display Whether to echo or return the markup. Default `true` for echo.
  *
- * @return string|void
+ * @return string|null Update PHP page annotation if available and $display is false, null otherwise.
  */
 function wp_update_php_annotation( $before = '<p class="description">', $after = '</p>', $display = true ) {
 	$annotation = wp_get_update_php_annotation();
@@ -8565,6 +8566,7 @@ function wp_update_php_annotation( $before = '<p class="description">', $after =
 			return $before . $annotation . $after;
 		}
 	}
+	return null;
 }
 
 /**