From beac9601fa588ffa453fa2f1a6c5321dd3abd70e Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 29 Apr 2022 19:17:11 +0000 Subject: [PATCH] Docs: Corrections and improvements to docblocks for function and hooks relating to fatal error handling. See #54729 Built from https://develop.svn.wordpress.org/trunk@53316 git-svn-id: http://core.svn.wordpress.org/trunk@52905 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/class-wp-fatal-error-handler.php | 7 ++-- .../class-wp-paused-extensions-storage.php | 12 ++++--- .../class-wp-recovery-mode-email-service.php | 32 +++++++++++++++---- wp-includes/class-wp-recovery-mode.php | 6 ++-- .../class-wp-customize-selective-refresh.php | 2 +- wp-includes/error-protection.php | 2 +- wp-includes/version.php | 2 +- 7 files changed, 44 insertions(+), 19 deletions(-) diff --git a/wp-includes/class-wp-fatal-error-handler.php b/wp-includes/class-wp-fatal-error-handler.php index 5a24793124..ca4bc8651e 100644 --- a/wp-includes/class-wp-fatal-error-handler.php +++ b/wp-includes/class-wp-fatal-error-handler.php @@ -66,7 +66,8 @@ class WP_Fatal_Error_Handler { * * @since 5.2.0 * - * @return array|null Error that was triggered, or null if no error received or if the error should not be handled. + * @return array|null Error information returned by `error_get_last()`, or null + * if none was recorded or the error should not be handled. */ protected function detect_error() { $error = error_get_last(); @@ -90,7 +91,7 @@ class WP_Fatal_Error_Handler { * * @since 5.2.0 * - * @param array $error Error information retrieved from error_get_last(). + * @param array $error Error information retrieved from `error_get_last()`. * @return bool Whether WordPress should handle this error. */ protected function should_handle_error( $error ) { @@ -116,7 +117,7 @@ class WP_Fatal_Error_Handler { * @since 5.2.0 * * @param bool $should_handle_error Whether the error should be handled by the fatal error handler. - * @param array $error Error information retrieved from error_get_last(). + * @param array $error Error information retrieved from `error_get_last()`. */ return (bool) apply_filters( 'wp_should_handle_php_error', false, $error ); } diff --git a/wp-includes/class-wp-paused-extensions-storage.php b/wp-includes/class-wp-paused-extensions-storage.php index 477b26ec7d..a2859d308f 100644 --- a/wp-includes/class-wp-paused-extensions-storage.php +++ b/wp-includes/class-wp-paused-extensions-storage.php @@ -42,11 +42,11 @@ class WP_Paused_Extensions_Storage { * * @param string $extension Plugin or theme directory name. * @param array $error { - * Error that was triggered. + * Error information returned by `error_get_last()`. * - * @type string $type The error type. + * @type int $type The error type. * @type string $file The name of the file in which the error occurred. - * @type string $line The line number in which the error occurred. + * @type int $line The line number in which the error occurred. * @type string $message The error message. * } * @return bool True on success, false on failure. @@ -141,7 +141,11 @@ class WP_Paused_Extensions_Storage { * * @since 5.2.0 * - * @return array Associative array of extension slugs to the error recorded. + * @return array { + * Associative array of errors keyed by extension slug. + * + * @type array ...$0 Error information returned by `error_get_last()`. + * } */ public function get_all() { if ( ! $this->is_api_loaded() ) { diff --git a/wp-includes/class-wp-recovery-mode-email-service.php b/wp-includes/class-wp-recovery-mode-email-service.php index 574744b138..e375f38bf1 100644 --- a/wp-includes/class-wp-recovery-mode-email-service.php +++ b/wp-includes/class-wp-recovery-mode-email-service.php @@ -40,7 +40,7 @@ final class WP_Recovery_Mode_Email_Service { * @since 5.2.0 * * @param int $rate_limit Number of seconds before another email can be sent. - * @param array $error Error details from {@see error_get_last()} + * @param array $error Error details from `error_get_last()`. * @param array $extension { * The extension that caused the error. * @@ -101,8 +101,13 @@ final class WP_Recovery_Mode_Email_Service { * @since 5.2.0 * * @param int $rate_limit Number of seconds before another email can be sent. - * @param array $error Error details from {@see error_get_last()} - * @param array $extension Extension that caused the error. + * @param array $error Error details from `error_get_last()`. + * @param array $extension { + * The extension that caused the error. + * + * @type string $slug The extension slug. The directory of the plugin or theme. + * @type string $type The extension type. Either 'plugin' or 'theme'. + * } * @return bool Whether the email was sent successfully. */ private function send_recovery_mode_email( $rate_limit, $error, $extension ) { @@ -256,7 +261,12 @@ When seeking help with this issue, you may be asked for some of the following in * * @since 5.2.0 * - * @param array $extension The extension that caused the error. + * @param array $extension { + * The extension that caused the error. + * + * @type string $slug The extension slug. The directory of the plugin or theme. + * @type string $type The extension type. Either 'plugin' or 'theme'. + * } * @return string Message about which extension caused the error. */ private function get_cause( $extension ) { @@ -288,7 +298,12 @@ When seeking help with this issue, you may be asked for some of the following in * * @since 5.3.0 * - * @param array $extension The extension that caused the error. + * @param array $extension { + * The extension that caused the error. + * + * @type string $slug The extension slug. The directory of the plugin or theme. + * @type string $type The extension type. Either 'plugin' or 'theme'. + * } * @return array|false A plugin array {@see get_plugins()} or `false` if no plugin was found. */ private function get_plugin( $extension ) { @@ -317,7 +332,12 @@ When seeking help with this issue, you may be asked for some of the following in * * @since 5.3.0 * - * @param array $extension The extension that caused the error. + * @param array $extension { + * The extension that caused the error. + * + * @type string $slug The extension slug. The directory of the plugin or theme. + * @type string $type The extension type. Either 'plugin' or 'theme'. + * } * @return array An associative array of debug information. */ private function get_debug( $extension ) { diff --git a/wp-includes/class-wp-recovery-mode.php b/wp-includes/class-wp-recovery-mode.php index 1694e42e56..e61290090e 100644 --- a/wp-includes/class-wp-recovery-mode.php +++ b/wp-includes/class-wp-recovery-mode.php @@ -159,7 +159,7 @@ class WP_Recovery_Mode { * * @since 5.2.0 * - * @param array $error Error details from {@see error_get_last()} + * @param array $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. @@ -339,7 +339,7 @@ class WP_Recovery_Mode { * * @global array $wp_theme_directories * - * @param array $error Error that was triggered. + * @param array $error Error details from `error_get_last()`. * @return array|false { * Extension details. * @@ -425,7 +425,7 @@ class WP_Recovery_Mode { * * @since 5.2.0 * - * @param array $error Error that was triggered. + * @param array $error Error details from `error_get_last()`. * @return bool True if the error was stored successfully, false otherwise. */ protected function store_error( $error ) { diff --git a/wp-includes/customize/class-wp-customize-selective-refresh.php b/wp-includes/customize/class-wp-customize-selective-refresh.php index 9ab7cce5d7..e5e3bcbba5 100644 --- a/wp-includes/customize/class-wp-customize-selective-refresh.php +++ b/wp-includes/customize/class-wp-customize-selective-refresh.php @@ -281,7 +281,7 @@ final class WP_Customize_Selective_Refresh { * @param int $errno Error number. * @param string $errstr Error string. * @param string $errfile Error file. - * @param string $errline Error line. + * @param int $errline Error line. * @return true Always true. */ public function handle_error( $errno, $errstr, $errfile = null, $errline = null ) { diff --git a/wp-includes/error-protection.php b/wp-includes/error-protection.php index 379b470171..dea49be023 100644 --- a/wp-includes/error-protection.php +++ b/wp-includes/error-protection.php @@ -41,7 +41,7 @@ function wp_paused_themes() { * * @since 5.2.0 * - * @param array $error Error details {@see error_get_last()} + * @param array $error Error details from `error_get_last()`. * @return string Formatted error description. */ function wp_get_extension_error_description( $error ) { diff --git a/wp-includes/version.php b/wp-includes/version.php index 6e6210dce6..c89f016387 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.0-beta3-53315'; +$wp_version = '6.0-beta3-53316'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.