From 6ddd314762a58ac82dc106db58e7d2c7764df39c Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@xwp.co>
Date: Mon, 30 Mar 2026 06:02:42 +0000
Subject: [PATCH] Code Quality: Replace `void` with proper return types in
 Administration PHPDoc annotations.

Replace `void` in union return types with `null` or remove it where the function always returns a value or dies, across 8 files in `wp-admin/includes`. Adds explicit `return null;` statements where functions previously fell through without a return value.

Additionally:
* Adds `@return never` for `media_send_to_editor()` and removes misleading `return` from its callers.
* Removes `void` from return types where the function always returns a value or exits: `write_post()`, `WP_Importer::set_blog()`, `WP_Importer::set_user()`.
* Replaces `mixed|void` with a specific array shape for `WP_Site_Health::perform_test()`.

Developed in https://github.com/WordPress/wordpress-develop/pull/11008

Follow-up to r62178, r62177, r61766, r61719.

Props apermo, xate, westonruter, mukesh27, desrosj.
Fixes #64702.

Built from https://develop.svn.wordpress.org/trunk@62179


git-svn-id: http://core.svn.wordpress.org/trunk@61461 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-admin/includes/class-wp-importer.php              | 12 +++++++++---
 .../includes/class-wp-privacy-requests-table.php     |  3 ++-
 wp-admin/includes/class-wp-site-health.php           | 12 +++++++++++-
 wp-admin/includes/dashboard.php                      |  3 ++-
 wp-admin/includes/file.php                           |  3 ++-
 wp-admin/includes/media.php                          |  7 ++++---
 wp-admin/includes/plugin.php                         |  5 +++--
 wp-admin/includes/post.php                           |  6 +++---
 wp-includes/version.php                              |  2 +-
 9 files changed, 37 insertions(+), 16 deletions(-)

diff --git a/wp-admin/includes/class-wp-importer.php b/wp-admin/includes/class-wp-importer.php
index 085a5adc0e..e1531eb260 100644
--- a/wp-admin/includes/class-wp-importer.php
+++ b/wp-admin/includes/class-wp-importer.php
@@ -135,8 +135,14 @@ class WP_Importer {
 	}
 
 	/**
-	 * @param int $blog_id
-	 * @return int|void
+	 * Sets the blog to import to.
+	 *
+	 * Accepts a numeric blog ID or a URL string. When given a URL,
+	 * the blog is looked up by domain and path. On multisite, switches
+	 * to the resolved blog. Exits with an error if the blog cannot be found.
+	 *
+	 * @param int|string $blog_id Blog ID or URL.
+	 * @return int Blog ID on success. Exits on failure.
 	 */
 	public function set_blog( $blog_id ) {
 		if ( is_numeric( $blog_id ) ) {
@@ -177,7 +183,7 @@ class WP_Importer {
 
 	/**
 	 * @param int $user_id
-	 * @return int|void
+	 * @return int
 	 */
 	public function set_user( $user_id ) {
 		if ( is_numeric( $user_id ) ) {
diff --git a/wp-admin/includes/class-wp-privacy-requests-table.php b/wp-admin/includes/class-wp-privacy-requests-table.php
index cffd2218f1..8544190695 100644
--- a/wp-admin/includes/class-wp-privacy-requests-table.php
+++ b/wp-admin/includes/class-wp-privacy-requests-table.php
@@ -435,7 +435,7 @@ abstract class WP_Privacy_Requests_Table extends WP_List_Table {
 	 * @since 4.9.6
 	 *
 	 * @param WP_User_Request $item Item being shown.
-	 * @return string|void Status column markup. Returns a string if no status is found,
+	 * @return string|null Status column markup. Returns a string if no status is found,
 	 *                     otherwise it displays the markup.
 	 */
 	public function column_status( $item ) {
@@ -465,6 +465,7 @@ abstract class WP_Privacy_Requests_Table extends WP_List_Table {
 		}
 
 		echo '</span>';
+		return null;
 	}
 
 	/**
diff --git a/wp-admin/includes/class-wp-site-health.php b/wp-admin/includes/class-wp-site-health.php
index 44c04175ab..75e046ef8f 100644
--- a/wp-admin/includes/class-wp-site-health.php
+++ b/wp-admin/includes/class-wp-site-health.php
@@ -167,7 +167,17 @@ class WP_Site_Health {
 	 * @since 5.4.0
 	 *
 	 * @param callable $callback
-	 * @return mixed|void
+	 * @return array{
+	 *     label: string,
+	 *     status: 'good'|'recommended'|'critical',
+	 *     badge: array{
+	 *         label: string,
+	 *         color: string,
+	 *     },
+	 *     description: string,
+	 *     actions: string,
+	 *     test: string,
+	 * }
 	 */
 	private function perform_test( $callback ) {
 		/**
diff --git a/wp-admin/includes/dashboard.php b/wp-admin/includes/dashboard.php
index 94d95f749f..5415e5961b 100644
--- a/wp-admin/includes/dashboard.php
+++ b/wp-admin/includes/dashboard.php
@@ -1648,7 +1648,7 @@ function wp_dashboard_primary_output( $widget_id, $feeds ) {
  *
  * @since 3.0.0
  *
- * @return true|void True if not multisite, user can't upload files, or the space check option is disabled.
+ * @return true|null True if not multisite, user can't upload files, or the space check option is disabled.
  */
 function wp_dashboard_quota() {
 	if ( ! is_multisite() || ! current_user_can( 'upload_files' )
@@ -1709,6 +1709,7 @@ function wp_dashboard_quota() {
 	</ul>
 	</div>
 	<?php
+	return null;
 }
 
 /**
diff --git a/wp-admin/includes/file.php b/wp-admin/includes/file.php
index bea00005d9..0c6d968ea0 100644
--- a/wp-admin/includes/file.php
+++ b/wp-admin/includes/file.php
@@ -734,7 +734,7 @@ function wp_tempnam( $filename = '', $dir = '' ) {
  * @param string   $file          File the user is attempting to edit.
  * @param string[] $allowed_files Optional. Array of allowed files to edit.
  *                                `$file` must match an entry exactly.
- * @return string|void Returns the file name on success, dies on failure.
+ * @return string|null Returns the file name on success, null in case of absolute Windows drive paths, and dies on failure.
  */
 function validate_file_to_edit( $file, $allowed_files = array() ) {
 	$code = validate_file( $file, $allowed_files );
@@ -753,6 +753,7 @@ function validate_file_to_edit( $file, $allowed_files = array() ) {
 		case 3:
 			wp_die( __( 'Sorry, that file cannot be edited.' ) );
 	}
+	return null;
 }
 
 /**
diff --git a/wp-admin/includes/media.php b/wp-admin/includes/media.php
index 7cb942f1c9..f4fd963ae5 100644
--- a/wp-admin/includes/media.php
+++ b/wp-admin/includes/media.php
@@ -269,6 +269,7 @@ function _cleanup_image_add_caption( $matches ) {
  * @since 2.5.0
  *
  * @param string $html
+ * @return never
  */
 function media_send_to_editor( $html ) {
 	?>
@@ -753,7 +754,7 @@ function get_upload_iframe_src( $type = null, $post_id = null, $tab = null ) {
  *
  * @since 2.5.0
  *
- * @return null|array|void Array of error messages keyed by attachment ID, null or void on success.
+ * @return null|array Array of error messages keyed by attachment ID, null on success, or exit.
  */
 function media_upload_form_handler() {
 	check_admin_referer( 'media-form' );
@@ -874,7 +875,7 @@ function media_upload_form_handler() {
 		 */
 		$html = apply_filters( 'media_send_to_editor', $html, $send_id, $attachment );
 
-		return media_send_to_editor( $html );
+		media_send_to_editor( $html );
 	}
 
 	return $errors;
@@ -976,7 +977,7 @@ function wp_media_upload_handler() {
 			$html = apply_filters( 'image_send_to_editor_url', $html, sanitize_url( $src ), $alt, $align );
 		}
 
-		return media_send_to_editor( $html );
+		media_send_to_editor( $html );
 	}
 
 	if ( isset( $_POST['save'] ) ) {
diff --git a/wp-admin/includes/plugin.php b/wp-admin/includes/plugin.php
index fae10f1a67..94d4a585a8 100644
--- a/wp-admin/includes/plugin.php
+++ b/wp-admin/includes/plugin.php
@@ -1296,8 +1296,8 @@ function is_uninstallable_plugin( $plugin ) {
  * @since 2.7.0
  *
  * @param string $plugin Path to the plugin file relative to the plugins directory.
- * @return true|void True if a plugin's uninstall.php file has been found and included.
- *                   Void otherwise.
+ * @return true|null True if a plugin's uninstall.php file has been found and included.
+ *                   Null otherwise.
  */
 function uninstall_plugin( $plugin ) {
 	$file = plugin_basename( $plugin );
@@ -1350,6 +1350,7 @@ function uninstall_plugin( $plugin ) {
 		 */
 		do_action( "uninstall_{$file}" );
 	}
+	return null;
 }
 
 //
diff --git a/wp-admin/includes/post.php b/wp-admin/includes/post.php
index a087e6b560..8d52c1487a 100644
--- a/wp-admin/includes/post.php
+++ b/wp-admin/includes/post.php
@@ -982,15 +982,15 @@ function wp_write_post() {
  *
  * @since 2.0.0
  *
- * @return int|void Post ID on success, void on failure.
+ * @return int Post ID on success. Dies on failure.
  */
 function write_post() {
 	$result = wp_write_post();
 	if ( is_wp_error( $result ) ) {
 		wp_die( $result->get_error_message() );
-	} else {
-		return $result;
 	}
+
+	return $result;
 }
 
 //
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 94d861338e..4e825b7431 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '7.1-alpha-62178';
+$wp_version = '7.1-alpha-62179';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.