From 4ff1233e758fa3e617cf6b09b1e0364e6f6f0f8b Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Tue, 14 Jul 2020 11:56:04 +0000 Subject: [PATCH] Docs: Correct and improve inline docs for parameters that accept a callback function. See #49572 Built from https://develop.svn.wordpress.org/trunk@48473 git-svn-id: http://core.svn.wordpress.org/trunk@48242 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/ajax-actions.php | 22 +++++++-------- wp-admin/includes/class-wp-screen.php | 12 ++++---- wp-admin/includes/class-wp-site-health.php | 2 +- wp-admin/includes/nav-menu.php | 10 +++---- wp-includes/class-wp-customize-control.php | 2 +- wp-includes/class-wp-customize-setting.php | 2 +- wp-includes/comment-template.php | 32 +++++++++++----------- wp-includes/functions.php | 6 ++-- wp-includes/meta.php | 4 +-- wp-includes/version.php | 2 +- wp-includes/widgets.php | 28 +++++++++---------- 11 files changed, 61 insertions(+), 61 deletions(-) diff --git a/wp-admin/includes/ajax-actions.php b/wp-admin/includes/ajax-actions.php index c9f30f5158..54fb2782dc 100644 --- a/wp-admin/includes/ajax-actions.php +++ b/wp-admin/includes/ajax-actions.php @@ -4778,11 +4778,11 @@ function wp_ajax_wp_privacy_export_personal_data() { * @type array { * Array of personal data exporters. * - * @type string $callback Callable exporter function that accepts an - * email address and a page and returns an array - * of name => value pairs of personal data. - * @type string $exporter_friendly_name Translated user facing friendly name for the - * exporter. + * @type callable $callback Callable exporter function that accepts an + * email address and a page and returns an array + * of name => value pairs of personal data. + * @type string $exporter_friendly_name Translated user facing friendly name for the + * exporter. * } * } */ @@ -4968,12 +4968,12 @@ function wp_ajax_wp_privacy_erase_personal_data() { * @type array { * Array of personal data exporters. * - * @type string $callback Callable eraser that accepts an email address and - * a page and returns an array with boolean values for - * whether items were removed or retained and any messages - * from the eraser, as well as if additional pages are - * available. - * @type string $exporter_friendly_name Translated user facing friendly name for the eraser. + * @type callable $callback Callable eraser that accepts an email address and + * a page and returns an array with boolean values for + * whether items were removed or retained and any messages + * from the eraser, as well as if additional pages are + * available. + * @type string $exporter_friendly_name Translated user facing friendly name for the eraser. * } * } */ diff --git a/wp-admin/includes/class-wp-screen.php b/wp-admin/includes/class-wp-screen.php index 6443d34d76..600ffa8411 100644 --- a/wp-admin/includes/class-wp-screen.php +++ b/wp-admin/includes/class-wp-screen.php @@ -620,12 +620,12 @@ final class WP_Screen { * @param array $args { * Array of arguments used to display the help tab. * - * @type string $title Title for the tab. Default false. - * @type string $id Tab ID. Must be HTML-safe and should be unique for this menu. - * It is NOT allowed to contain any empty spaces. Default false. - * @type string $content Optional. Help tab content in plain text or HTML. Default empty string. - * @type string $callback Optional. A callback to generate the tab content. Default false. - * @type int $priority Optional. The priority of the tab, used for ordering. Default 10. + * @type string $title Title for the tab. Default false. + * @type string $id Tab ID. Must be HTML-safe and should be unique for this menu. + * It is NOT allowed to contain any empty spaces. Default false. + * @type string $content Optional. Help tab content in plain text or HTML. Default empty string. + * @type callable $callback Optional. A callback to generate the tab content. Default false. + * @type int $priority Optional. The priority of the tab, used for ordering. Default 10. * } */ public function add_help_tab( $args ) { diff --git a/wp-admin/includes/class-wp-site-health.php b/wp-admin/includes/class-wp-site-health.php index 2b48212d32..a86e422fe7 100644 --- a/wp-admin/includes/class-wp-site-health.php +++ b/wp-admin/includes/class-wp-site-health.php @@ -147,7 +147,7 @@ class WP_Site_Health { * * @since 5.4.0 * - * @param $callback + * @param callable $callback * @return mixed|void */ private function perform_test( $callback ) { diff --git a/wp-admin/includes/nav-menu.php b/wp-admin/includes/nav-menu.php index ed786c9e2c..8621b357d7 100644 --- a/wp-admin/includes/nav-menu.php +++ b/wp-admin/includes/nav-menu.php @@ -332,7 +332,7 @@ function wp_nav_menu_item_link_meta_box() { * * @type string $id Meta box 'id' attribute. * @type string $title Meta box title. - * @type string $callback Meta box display callback. + * @type callable $callback Meta box display callback. * @type WP_Post_Type $args Extra meta box arguments (the post type object for this meta box). * } */ @@ -684,10 +684,10 @@ function wp_nav_menu_item_post_type_meta_box( $object, $box ) { * @param array $box { * Taxonomy menu item meta box arguments. * - * @type string $id Meta box 'id' attribute. - * @type string $title Meta box title. - * @type string $callback Meta box display callback. - * @type object $args Extra meta box arguments (the taxonomy object for this meta box). + * @type string $id Meta box 'id' attribute. + * @type string $title Meta box title. + * @type callable $callback Meta box display callback. + * @type object $args Extra meta box arguments (the taxonomy object for this meta box). * } */ function wp_nav_menu_item_taxonomy_meta_box( $object, $box ) { diff --git a/wp-includes/class-wp-customize-control.php b/wp-includes/class-wp-customize-control.php index f01d82b827..52ffc30d58 100644 --- a/wp-includes/class-wp-customize-control.php +++ b/wp-includes/class-wp-customize-control.php @@ -204,7 +204,7 @@ class WP_Customize_Control { * 'textarea', 'radio', 'select', and 'dropdown-pages'. Additional * input types such as 'email', 'url', 'number', 'hidden', and * 'date' are supported implicitly. Default 'text'. - * @type callback $active_callback Active callback. + * @type callable $active_callback Active callback. * } */ public function __construct( $manager, $id, $args = array() ) { diff --git a/wp-includes/class-wp-customize-setting.php b/wp-includes/class-wp-customize-setting.php index 70bfd50d80..170e6746d9 100644 --- a/wp-includes/class-wp-customize-setting.php +++ b/wp-includes/class-wp-customize-setting.php @@ -97,7 +97,7 @@ class WP_Customize_Setting { * Callback to convert a Customize PHP setting value to a value that is JSON serializable. * * @since 3.4.0 - * @var string + * @var callable */ public $sanitize_js_callback = ''; diff --git a/wp-includes/comment-template.php b/wp-includes/comment-template.php index f52c4989ff..ad21f20ab2 100644 --- a/wp-includes/comment-template.php +++ b/wp-includes/comment-template.php @@ -2007,22 +2007,22 @@ function comment_form_title( $noreplytext = false, $replytext = false, $linktopa * @param string|array $args { * Optional. Formatting options. * - * @type object $walker Instance of a Walker class to list comments. Default null. - * @type int $max_depth The maximum comments depth. Default empty. - * @type string $style The style of list ordering. Default 'ul'. Accepts 'ul', 'ol'. - * @type string $callback Callback function to use. Default null. - * @type string $end-callback Callback function to use at the end. Default null. - * @type string $type Type of comments to list. - * Default 'all'. Accepts 'all', 'comment', 'pingback', 'trackback', 'pings'. - * @type int $page Page ID to list comments for. Default empty. - * @type int $per_page Number of comments to list per page. Default empty. - * @type int $avatar_size Height and width dimensions of the avatar size. Default 32. - * @type bool $reverse_top_level Ordering of the listed comments. If true, will display newest comments first. - * @type bool $reverse_children Whether to reverse child comments in the list. Default null. - * @type string $format How to format the comments list. - * Default 'html5' if the theme supports it. Accepts 'html5', 'xhtml'. - * @type bool $short_ping Whether to output short pings. Default false. - * @type bool $echo Whether to echo the output or return it. Default true. + * @type object $walker Instance of a Walker class to list comments. Default null. + * @type int $max_depth The maximum comments depth. Default empty. + * @type string $style The style of list ordering. Default 'ul'. Accepts 'ul', 'ol'. + * @type callable $callback Callback function to use. Default null. + * @type callable $end-callback Callback function to use at the end. Default null. + * @type string $type Type of comments to list. + * Default 'all'. Accepts 'all', 'comment', 'pingback', 'trackback', 'pings'. + * @type int $page Page ID to list comments for. Default empty. + * @type int $per_page Number of comments to list per page. Default empty. + * @type int $avatar_size Height and width dimensions of the avatar size. Default 32. + * @type bool $reverse_top_level Ordering of the listed comments. If true, will display newest comments first. + * @type bool $reverse_children Whether to reverse child comments in the list. Default null. + * @type string $format How to format the comments list. + * Default 'html5' if the theme supports it. Accepts 'html5', 'xhtml'. + * @type bool $short_ping Whether to output short pings. Default false. + * @type bool $echo Whether to echo the output or return it. Default true. * } * @param WP_Comment[] $comments Optional. Array of WP_Comment objects. * @return void|string Void if 'echo' argument is true, or no comments to list. diff --git a/wp-includes/functions.php b/wp-includes/functions.php index 16d3a0f5d4..3c0937ed32 100644 --- a/wp-includes/functions.php +++ b/wp-includes/functions.php @@ -4149,7 +4149,7 @@ function wp_send_json_error( $data = null, $status_code = null ) { } /** - * Checks that a JSONP callback is a valid JavaScript callback. + * Checks that a JSONP callback is a valid JavaScript callback name. * * Only allows alphanumeric characters and the dot character in callback * function names. This helps to mitigate XSS attacks caused by directly @@ -4157,8 +4157,8 @@ function wp_send_json_error( $data = null, $status_code = null ) { * * @since 4.6.0 * - * @param string $callback Supplied JSONP callback function. - * @return bool True if valid callback, otherwise false. + * @param string $callback Supplied JSONP callback function name. + * @return bool Whether the callback function name is valid. */ function wp_check_jsonp_callback( $callback ) { if ( ! is_string( $callback ) ) { diff --git a/wp-includes/meta.php b/wp-includes/meta.php index 816be548be..805725074b 100644 --- a/wp-includes/meta.php +++ b/wp-includes/meta.php @@ -1240,8 +1240,8 @@ function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype = * When using a non-single meta key, the default value is for the first entry. * In other words, when calling get_metadata() with `$single` set to `false`, * the default value given here will be wrapped in an array. - * @type string $sanitize_callback A function or method to call when sanitizing `$meta_key` data. - * @type string $auth_callback Optional. A function or method to call when performing edit_post_meta, + * @type callable $sanitize_callback A function or method to call when sanitizing `$meta_key` data. + * @type callable $auth_callback Optional. A function or method to call when performing edit_post_meta, * add_post_meta, and delete_post_meta capability checks. * @type bool|array $show_in_rest Whether data associated with this meta key can be considered public and * should be accessible via the REST API. A custom post type must also declare diff --git a/wp-includes/version.php b/wp-includes/version.php index e02b2ced6b..e36acd77e1 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @global string $wp_version */ -$wp_version = '5.5-beta1-48472'; +$wp_version = '5.5-beta1-48473'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. diff --git a/wp-includes/widgets.php b/wp-includes/widgets.php index 732a89653e..939e45b07e 100644 --- a/wp-includes/widgets.php +++ b/wp-includes/widgets.php @@ -787,16 +787,16 @@ function dynamic_sidebar( $index = 1 ) { * @param array $widget_id { * An associative array of widget arguments. * - * @type string $name Name of the widget. - * @type string $id Widget ID. - * @type array|callable $callback When the hook is fired on the front end, $callback is an array - * containing the widget object. Fired on the back end, $callback - * is 'wp_widget_control', see $_callback. - * @type array $params An associative array of multi-widget arguments. - * @type string $classname CSS class applied to the widget container. - * @type string $description The widget description. - * @type array $_callback When the hook is fired on the back end, $_callback is populated - * with an array containing the widget object, see $callback. + * @type string $name Name of the widget. + * @type string $id Widget ID. + * @type callable $callback When the hook is fired on the front end, $callback is an array + * containing the widget object. Fired on the back end, $callback + * is 'wp_widget_control', see $_callback. + * @type array $params An associative array of multi-widget arguments. + * @type string $classname CSS class applied to the widget container. + * @type string $description The widget description. + * @type array $_callback When the hook is fired on the back end, $_callback is populated + * with an array containing the widget object, see $callback. * } */ do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] ); @@ -857,10 +857,10 @@ function dynamic_sidebar( $index = 1 ) { * * @global array $wp_registered_widgets * - * @param string|false $callback Optional, Widget callback to check. Default false. - * @param int|false $widget_id Optional. Widget ID. Optional, but needed for checking. Default false. - * @param string|false $id_base Optional. The base ID of a widget created by extending WP_Widget. Default false. - * @param bool $skip_inactive Optional. Whether to check in 'wp_inactive_widgets'. Default true. + * @param callable|false $callback Optional, Widget callback to check. Default false. + * @param int|false $widget_id Optional. Widget ID. Optional, but needed for checking. Default false. + * @param string|false $id_base Optional. The base ID of a widget created by extending WP_Widget. Default false. + * @param bool $skip_inactive Optional. Whether to check in 'wp_inactive_widgets'. Default true. * @return string|false False if widget is not active or id of sidebar in which the widget is active. */ function is_active_widget( $callback = false, $widget_id = false, $id_base = false, $skip_inactive = true ) {