Docs: Add never return types to functions that always terminate.

Documents `@return never` on 30 functions and methods whose every control-flow path ends in `exit`, `die()`, `wp_die()`, or `wp_send_json_*()`, so static analysis knows the code following a call to them is unreachable. Native `never` requires PHP 8.1, so these are PHPDoc-only.

Where terminating depends on a parameter, a conditional `@phpstan-return` describes each case rather than over-widening to the union of both. The seven `wp_die()` handlers gain the same conditional `wp_die()` itself already carries. `trackback_response()` and `wp_protect_special_option()` never return for the parameter values that die, while `redirect_canonical()`, `check_admin_referer()`, `check_ajax_referer()`, and `get_cli_args()` narrow their return types accordingly.

The bottom type `never` was also incorrectly declared in the return type union for `get_cli_args()`, so it was removed.

Developed as subset of WordPress#12488.
Follow-up to r62703, r62178, r62177.

Props westonruter, mukesh27.
See #64896, #64898.


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

Author: westonruter

src/wp-admin/includes/class-custom-background.php

@@ -569,6 +569,8 @@ public function handle_upload() {
 	 * Media Manager.
 	 *
 	 * @since 4.1.0
+	 *
+	 * @return never
 	 */
 	public function ajax_background_add() {
 		check_ajax_referer( 'background-add', 'nonce' );
@@ -612,6 +614,8 @@ public function filter_upload_tabs( $tabs ) {
 	/**
 	 * @since 3.4.0
 	 * @deprecated 3.5.0
+	 *
+	 * @return never
 	 */
 	public function wp_set_background_image() {
 		check_ajax_referer( 'custom-background' );

src/wp-admin/includes/class-custom-image-header.php

@@ -1383,6 +1383,8 @@ final public function insert_attachment( $attachment, $cropped ) {
 	 * new object. Returns JSON-encoded object details.
 	 *
 	 * @since 3.9.0
+	 *
+	 * @return never
 	 */
 	public function ajax_header_crop() {
 		check_ajax_referer( 'image_editor-' . $_POST['id'], 'nonce' );
@@ -1452,6 +1454,8 @@ public function ajax_header_crop() {
 	 * Media Manager, even if s/he doesn't save that change.
 	 *
 	 * @since 3.9.0
+	 *
+	 * @return never
 	 */
 	public function ajax_header_add() {
 		check_ajax_referer( 'header-add', 'nonce' );
@@ -1480,6 +1484,8 @@ public function ajax_header_add() {
 	 * choice in the Customizer's Header tool.
 	 *
 	 * @since 3.9.0
+	 *
+	 * @return never
 	 */
 	public function ajax_header_remove() {
 		check_ajax_referer( 'header-remove', 'nonce' );

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

@@ -298,8 +298,11 @@ public function stop_the_insanity() {
  *
  * @param string $param    The parameter name to retrieve.
  * @param bool   $required Optional. Whether the parameter is required. Default false.
- * @return string|true|null|never The parameter value or true if found, null otherwise.
- *                                The function exits when a required parameter is missing.
+ * @return string|true|null The parameter value, or true if the parameter was supplied
+ *                          without a value, or null if it was not supplied at all.
+ *                          Never returns when `$required` is true and the parameter
+ *                          is missing, as the function exits instead.
+ * @phpstan-return ( $required is true ? string|true : string|true|null )
  */
 function get_cli_args( $param, $required = false ) {
 	$args = $_SERVER['argv'];

src/wp-admin/includes/class-wp-list-table.php

@@ -1843,6 +1843,8 @@ protected function handle_row_actions( $item, $column_name, $primary ) {
 	 * Handles an incoming ajax request (called from admin-ajax.php)
 	 *
 	 * @since 3.1.0
+	 *
+	 * @return never
 	 */
 	public function ajax_response() {
 		$this->prepare_items();

src/wp-admin/includes/comment.php

@@ -294,6 +294,7 @@ function enqueue_comment_hotkeys_js() {
  * @since 2.5.0
  *
  * @param string $msg Error Message. Assumed to contain HTML and be sanitized.
+ * @return never
  */
 function comment_footer_die( $msg ) {
 	echo "<div class='wrap'><p>$msg</p></div>";

src/wp-admin/includes/post.php

@@ -2183,6 +2183,7 @@ function wp_autosave( $post_data ) {
  * @since 2.7.0
  *
  * @param int $post_id Optional. Post ID.
+ * @return never
  */
 function redirect_post( $post_id = 0 ) {
 	if ( isset( $_POST['save'] ) || isset( $_POST['publish'] ) ) {

src/wp-admin/includes/theme-install.php

@@ -251,6 +251,8 @@ function display_themes() {
  * @since 2.8.0
  *
  * @global WP_Theme_Install_List_Table $wp_list_table
+ *
+ * @return never
  */
 function install_theme_information() {
 	global $wp_list_table;

src/wp-includes/canonical.php

@@ -38,6 +38,7 @@
  *                              figure if redirect is needed.
  * @param bool   $do_redirect   Optional. Redirect to the new URL.
  * @return string|null The string of the URL, if redirect needed. Never returns if a redirect occurs, depending on $do_redirect.
+ * @phpstan-return ( $do_redirect is true ? null : string|null )
  */
 function redirect_canonical( $requested_url = null, $do_redirect = true ) {
 	global $wp_rewrite, $is_IIS, $wp_query, $wpdb, $wp;

src/wp-includes/class-wp-ajax-response.php

@@ -148,6 +148,8 @@ public function add( $args = '' ) {
 	 * Sets the content type header to text/xml.
 	 *
 	 * @since 2.1.0
+	 *
+	 * @return never
 	 */
 	public function send() {
 		header( 'Content-Type: text/xml; charset=' . get_option( 'blog_charset' ) );

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

@@ -447,6 +447,7 @@ public function doing_ajax( $action = null ) {
 	 *
 	 * @param string|WP_Error $ajax_message Ajax return.
 	 * @param string          $message      Optional. UI message.
+	 * @return never
 	 */
 	protected function wp_die( $ajax_message, $message = null ) {
 		if ( $this->doing_ajax() ) {
@@ -2427,6 +2428,8 @@ public function prepare_setting_validity_for_js( $validity ) {
 	 *
 	 * @since 3.4.0
 	 * @since 4.7.0 The semantics of this method have changed to update a changeset, optionally to also change the status and other attributes.
+	 *
+	 * @return never
 	 */
 	public function save() {
 		if ( ! is_user_logged_in() ) {
@@ -3386,6 +3389,8 @@ public function check_changeset_lock_with_heartbeat( $response, $data, $screen_i
 	 * Removes changeset lock when take over request is sent via Ajax.
 	 *
 	 * @since 4.9.0
+	 *
+	 * @return never
 	 */
 	public function handle_override_changeset_lock_request() {
 		if ( ! $this->is_preview() ) {
@@ -3685,6 +3690,8 @@ protected function update_stashed_theme_mod_settings( $inactive_theme_mod_settin
 	 * Refreshes nonces for the current preview.
 	 *
 	 * @since 4.2.0
+	 *
+	 * @return never
 	 */
 	public function refresh_nonces() {
 		if ( ! $this->is_preview() ) {
@@ -3698,6 +3705,8 @@ public function refresh_nonces() {
 	 * Deletes a given auto-draft changeset or the autosave revision for a given changeset or delete changeset lock.
 	 *
 	 * @since 4.9.0
+	 *
+	 * @return never
 	 */
 	public function handle_dismiss_autosave_or_lock_request() {
 		// Calls to dismiss_user_auto_draft_changesets() and wp_get_post_autosave() require non-zero get_current_user_id().
@@ -5824,6 +5833,8 @@ public function register_dynamic_settings() {
 	 * Loads themes into the theme browsing/installation UI.
 	 *
 	 * @since 4.9.0
+	 *
+	 * @return never
 	 */
 	public function handle_load_themes_request() {
 		check_ajax_referer( 'switch_themes', 'nonce' );