From fccc020d291e85ef23b2089e4f3b69ba2254014b Mon Sep 17 00:00:00 2001 From: desrosj Date: Wed, 23 Jun 2021 19:05:57 +0000 Subject: [PATCH] Docs: Various docblock corrections for code added in 5.8. Props johnbillion. See #53461. Built from https://develop.svn.wordpress.org/trunk@51221 git-svn-id: http://core.svn.wordpress.org/trunk@50830 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/block-editor.php | 2 +- wp-includes/block-supports/border.php | 4 +- wp-includes/block-template-utils.php | 5 +- wp-includes/block-template.php | 8 +- wp-includes/blocks.php | 2 - wp-includes/class-wp-image-editor.php | 7 +- wp-includes/class-wp-theme-json-resolver.php | 6 +- wp-includes/class-wp-theme-json.php | 163 +++++++++--------- wp-includes/load.php | 2 +- wp-includes/media.php | 2 +- .../class-wp-rest-templates-controller.php | 2 - wp-includes/script-loader.php | 2 +- wp-includes/version.php | 2 +- wp-includes/widgets/class-wp-widget-block.php | 6 +- 14 files changed, 99 insertions(+), 114 deletions(-) diff --git a/wp-includes/block-editor.php b/wp-includes/block-editor.php index 9b1aa739ad..c533f69b74 100644 --- a/wp-includes/block-editor.php +++ b/wp-includes/block-editor.php @@ -10,7 +10,7 @@ /** * Returns the list of default categories for block types. * - * @since 5.8.0. + * @since 5.8.0 * * @return array[] Array of categories for block types. */ diff --git a/wp-includes/block-supports/border.php b/wp-includes/block-supports/border.php index 172016513a..ffc5cd21a4 100644 --- a/wp-includes/block-supports/border.php +++ b/wp-includes/block-supports/border.php @@ -45,7 +45,7 @@ function wp_register_border_support( $block_type ) { * @since 5.8.0 * @access private * - * @param WP_Block_type $block_type Block type. + * @param WP_Block_Type $block_type Block type. * @param array $block_attributes Block attributes. * * @return array Border CSS classes and inline styles. @@ -123,7 +123,7 @@ function wp_apply_border_support( $block_type, $block_attributes ) { * @since 5.8.0 * @access private * - * @param WP_Block_type $block_type Block type. + * @param WP_Block_Type $block_type Block type. * * @return boolean */ diff --git a/wp-includes/block-template-utils.php b/wp-includes/block-template-utils.php index ecdd8ec8fd..5658d1e552 100644 --- a/wp-includes/block-template-utils.php +++ b/wp-includes/block-template-utils.php @@ -56,9 +56,8 @@ function _build_template_result_from_post( $post ) { * @type array $slug__in List of slugs to include. * @type int $wp_id Post ID of customized template. * } - * @param string $template_type wp_template. - * - * @return array Templates. + * @param string $template_type Optional. The template type (post type). Default 'wp_template'. + * @return WP_Block_Template[] Block template objects. */ function get_block_templates( $query = array(), $template_type = 'wp_template' ) { $wp_query_args = array( diff --git a/wp-includes/block-template.php b/wp-includes/block-template.php index d185580f01..332cfd0a62 100644 --- a/wp-includes/block-template.php +++ b/wp-includes/block-template.php @@ -93,10 +93,8 @@ function locate_block_template( $template, $type, array $templates ) { * @access private * @since 5.8.0 * - * Accepts an optional $template_hierarchy argument as a hint. - * * @param string $template_type The current template type. - * @param string[] $template_hierarchy (optional) The current template hierarchy, ordered by priority. + * @param string[] $template_hierarchy The current template hierarchy, ordered by priority. * @return WP_Block_Template|null template A template object, or null if none could be found. */ function resolve_block_template( $template_type, $template_hierarchy ) { @@ -187,10 +185,10 @@ function get_the_block_template_html() { /** * Renders a 'viewport' meta tag. * + * This is hooked into {@see 'wp_head'} to decouple its output from the default template canvas. + * * @access private * @since 5.8.0 - * - * This is hooked into {@see 'wp_head'} to decouple its output from the default template canvas. */ function _block_template_viewport_meta_tag() { echo '' . "\n"; diff --git a/wp-includes/blocks.php b/wp-includes/blocks.php index 1c1de18254..dc9f9110c5 100644 --- a/wp-includes/blocks.php +++ b/wp-includes/blocks.php @@ -214,8 +214,6 @@ function register_block_type_from_metadata( $file_or_folder, $args = array() ) { /** * Add `style` and `editor_style` for core blocks if missing. - * - * @since 5.8.0 */ if ( ! empty( $metadata['name'] ) && 0 === strpos( $metadata['name'], 'core/' ) ) { $block_name = str_replace( 'core/', '', $metadata['name'] ); diff --git a/wp-includes/class-wp-image-editor.php b/wp-includes/class-wp-image-editor.php index 37b65ca8d1..d97332625b 100644 --- a/wp-includes/class-wp-image-editor.php +++ b/wp-includes/class-wp-image-editor.php @@ -326,13 +326,12 @@ abstract class WP_Image_Editor { * * @since 5.8.0 * - * @param array $output_format { + * @param string[] $output_format { * An array of mime type mappings. Maps a source mime type to a new * destination mime type. Default empty array. * - * @type array $mime_type The source mime type { - * @type string $mime_type The new mime type. - * } + * @type string ...$0 The new mime type. + * } * @param string $filename Path to the image. * @param string $mime_type The source image mime type. * } diff --git a/wp-includes/class-wp-theme-json-resolver.php b/wp-includes/class-wp-theme-json-resolver.php index c40b5a504e..5e000c0b51 100644 --- a/wp-includes/class-wp-theme-json-resolver.php +++ b/wp-includes/class-wp-theme-json-resolver.php @@ -265,7 +265,7 @@ class WP_Theme_JSON_Resolver { * * @since 5.8.0 * - * @param array $theme_support_data Theme support data in theme.json format. + * @param array $theme_support_data Theme support data in theme.json format. Default empty array. * @return WP_Theme_JSON Entity that holds theme data. */ public static function get_theme_data( $theme_support_data = array() ) { @@ -318,7 +318,9 @@ class WP_Theme_JSON_Resolver { /** * Whether the current theme has a theme.json file. * - * @return boolean + * @since 5.8.0 + * + * @return bool */ public static function theme_has_support() { if ( ! isset( self::$theme_has_support ) ) { diff --git a/wp-includes/class-wp-theme-json.php b/wp-includes/class-wp-theme-json.php index 2940920704..4733e6e497 100644 --- a/wp-includes/class-wp-theme-json.php +++ b/wp-includes/class-wp-theme-json.php @@ -355,23 +355,23 @@ class WP_Theme_JSON { * * Example: * - * { - * 'core/paragraph': { - * 'selector': 'p', - * 'elements': { - * 'link' => 'link selector', - * 'etc' => 'element selector' + * { + * 'core/paragraph': { + * 'selector': 'p', + * 'elements': { + * 'link' => 'link selector', + * 'etc' => 'element selector' + * } + * }, + * 'core/heading': { + * 'selector': 'h1', + * 'elements': {} + * } + * 'core/group': { + * 'selector': '.wp-block-group', + * 'elements': {} + * } * } - * }, - * 'core/heading': { - * 'selector': 'h1', - * 'elements': {} - * } - * 'core/group': { - * 'selector': '.wp-block-group', - * 'elements': {} - * } - * } * * @since 5.8.0 * @@ -517,25 +517,25 @@ class WP_Theme_JSON { * Additionally, it'll also create new rulesets * as classes for each preset value such as: * - * .has-value-color { - * color: value; - * } + * .has-value-color { + * color: value; + * } * - * .has-value-background-color { - * background-color: value; - * } + * .has-value-background-color { + * background-color: value; + * } * - * .has-value-font-size { - * font-size: value; - * } + * .has-value-font-size { + * font-size: value; + * } * - * .has-value-gradient-background { - * background: value; - * } + * .has-value-gradient-background { + * background: value; + * } * - * p.has-value-gradient-background { - * background: value; - * } + * p.has-value-gradient-background { + * background: value; + * } * * @since 5.8.0 * @@ -580,10 +580,10 @@ class WP_Theme_JSON { * * For each section this creates a new ruleset such as: * - * block-selector { - * --wp--preset--category--slug: value; - * --wp--custom--variable: value; - * } + * block-selector { + * --wp--preset--category--slug: value; + * --wp--custom--variable: value; + * } * * @since 5.8.0 * @@ -613,9 +613,6 @@ class WP_Theme_JSON { * Given a selector and a declaration list, * creates the corresponding ruleset. * - * To help debugging, will add some space - * if SCRIPT_DEBUG is defined and true. - * * @since 5.8.0 * * @param string $selector CSS selector. @@ -731,12 +728,10 @@ class WP_Theme_JSON { * for the presets and adds them to the $declarations array * following the format: * - * ```php - * array( - * 'name' => 'property_name', - * 'value' => 'property_value, - * ) - * ``` + * array( + * 'name' => 'property_name', + * 'value' => 'property_value, + * ) * * @since 5.8.0 * @@ -765,12 +760,10 @@ class WP_Theme_JSON { * for the custom values and adds them to the $declarations * array following the format: * - * ```php - * array( - * 'name' => 'property_name', - * 'value' => 'property_value, - * ) - * ``` + * array( + * 'name' => 'property_name', + * 'value' => 'property_value, + * ) * * @since 5.8.0 * @@ -808,19 +801,19 @@ class WP_Theme_JSON { * For example, assuming the given prefix is '--wp' * and the token is '--', for this input tree: * - * { - * 'some/property': 'value', - * 'nestedProperty': { - * 'sub-property': 'value' - * } - * } + * { + * 'some/property': 'value', + * 'nestedProperty': { + * 'sub-property': 'value' + * } + * } * * it'll return this output: * - * { - * '--wp--some-property': 'value', - * '--wp--nested-property--sub-property': 'value' - * } + * { + * '--wp--some-property': 'value', + * '--wp--nested-property--sub-property': 'value' + * } * * @since 5.8.0 * @@ -856,12 +849,10 @@ class WP_Theme_JSON { * Given a styles array, it extracts the style properties * and adds them to the $declarations array following the format: * - * ```php - * array( - * 'name' => 'property_name', - * 'value' => 'property_value, - * ) - * ``` + * array( + * 'name' => 'property_name', + * 'value' => 'property_value, + * ) * * @since 5.8.0 * @@ -967,16 +958,16 @@ class WP_Theme_JSON { /** * Builds metadata for the setting nodes, which returns in the form of: * - * [ - * [ - * 'path' => ['path', 'to', 'some', 'node' ], - * 'selector' => 'CSS selector for some node' - * ], - * [ - * 'path' => [ 'path', 'to', 'other', 'node' ], - * 'selector' => 'CSS selector for other node' - * ], - * ] + * [ + * [ + * 'path' => ['path', 'to', 'some', 'node' ], + * 'selector' => 'CSS selector for some node' + * ], + * [ + * 'path' => [ 'path', 'to', 'other', 'node' ], + * 'selector' => 'CSS selector for other node' + * ], + * ] * * @since 5.8.0 * @@ -1021,16 +1012,16 @@ class WP_Theme_JSON { /** * Builds metadata for the style nodes, which returns in the form of: * - * [ - * [ - * 'path' => [ 'path', 'to', 'some', 'node' ], - * 'selector' => 'CSS selector for some node' - * ], - * [ - * 'path' => ['path', 'to', 'other', 'node' ], - * 'selector' => 'CSS selector for other node' - * ], - * ] + * [ + * [ + * 'path' => [ 'path', 'to', 'some', 'node' ], + * 'selector' => 'CSS selector for some node' + * ], + * [ + * 'path' => ['path', 'to', 'other', 'node' ], + * 'selector' => 'CSS selector for other node' + * ], + * ] * * @since 5.8.0 * diff --git a/wp-includes/load.php b/wp-includes/load.php index 5ba217516c..efe69a67d7 100644 --- a/wp-includes/load.php +++ b/wp-includes/load.php @@ -667,7 +667,7 @@ function wp_start_object_cache() { // Only perform the following checks once. /** - * Filters whether to enable loading of the objectcache.php drop-in. + * Filters whether to enable loading of the object-cache.php drop-in. * * This filter runs before it can be used by plugins. It is designed for non-web * run-times. If false is returned, object-cache.php will never be loaded. diff --git a/wp-includes/media.php b/wp-includes/media.php index 4a9849d3ca..5c73db8f30 100644 --- a/wp-includes/media.php +++ b/wp-includes/media.php @@ -4356,7 +4356,7 @@ function wp_enqueue_media( $args = array() ) { * * @since 5.8.0 * - * @param bool $value The filtered value, defaults to `false`. + * @param bool $infinite Whether the Media Library grid has infinite scrolling. */ $infinite_scrolling = apply_filters( 'media_library_infinite_scrolling', false ); diff --git a/wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php b/wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php index ff71dc024a..8f89284e5c 100644 --- a/wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php +++ b/wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php @@ -42,8 +42,6 @@ class WP_REST_Templates_Controller extends WP_REST_Controller { * Registers the controllers routes. * * @since 5.8.0 - * - * @return void */ public function register_routes() { // Lists all templates. diff --git a/wp-includes/script-loader.php b/wp-includes/script-loader.php index b2abe86f26..9c54709a7a 100644 --- a/wp-includes/script-loader.php +++ b/wp-includes/script-loader.php @@ -2603,7 +2603,7 @@ function wp_maybe_inline_styles() { * * @since 5.8.0 * - * @param int $total_inline_limit The file-size threshold, in bytes. Defaults to 20000. + * @param int $total_inline_limit The file-size threshold, in bytes. Default 20000. */ $total_inline_limit = apply_filters( 'styles_inline_size_limit', $total_inline_limit ); diff --git a/wp-includes/version.php b/wp-includes/version.php index 1ce4cb7cd1..334b941d8b 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @global string $wp_version */ -$wp_version = '5.8-beta3-51220'; +$wp_version = '5.8-beta3-51221'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. diff --git a/wp-includes/widgets/class-wp-widget-block.php b/wp-includes/widgets/class-wp-widget-block.php index ecbc02d043..35a2c966e5 100644 --- a/wp-includes/widgets/class-wp-widget-block.php +++ b/wp-includes/widgets/class-wp-widget-block.php @@ -98,7 +98,7 @@ class WP_Widget_Block extends WP_Widget { * * @since 5.8.0 * - * @param array $content The HTML content of the current block widget. + * @param string $content The HTML content of the current block widget. * * @return string The classname to use in the block widget's container HTML. */ @@ -191,9 +191,9 @@ class WP_Widget_Block extends WP_Widget { * * @since 5.8.0 * - * @param array $instance Current instance. - * * @see WP_Widget_Custom_HTML::render_control_template_scripts() + * + * @param array $instance Current instance. */ public function form( $instance ) { $instance = wp_parse_args( (array) $instance, $this->default_instance );