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 #11008

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

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


git-svn-id: https://develop.svn.wordpress.org/trunk@62179 602fd350-edb4-49c9-b593-d223f7449a82

Author: westonruter

src/wp-admin/includes/class-wp-importer.php

@@ -135,8 +135,14 @@ public function get_imported_comments( $blog_id ) {
 	}
 
 	/**
-	 * @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 @@ public function set_blog( $blog_id ) {
 
 	/**
 	 * @param int $user_id
-	 * @return int|void
+	 * @return int
 	 */
 	public function set_user( $user_id ) {
 		if ( is_numeric( $user_id ) ) {

src/wp-admin/includes/class-wp-privacy-requests-table.php

@@ -435,7 +435,7 @@ public function column_cb( $item ) {
 	 * @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 @@ public function column_status( $item ) {
 		}
 
 		echo '</span>';
+		return null;
 	}
 
 	/**

src/wp-admin/includes/class-wp-site-health.php

@@ -167,7 +167,17 @@ public function enqueue_scripts() {
 	 * @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 ) {
 		/**

src/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;
 }
 
 /**

src/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;
 }
 
 /**

src/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'] ) ) {

src/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;
 }
 
 //

src/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;
 }
 
 //