From 17debfe6243227eafc41c4be6fa882b09350d37f Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 2 May 2024 19:54:13 +0000 Subject: [PATCH] Docs: Document the array shapes for parsed blocks, template part areas, and template types. See #60699 Built from https://develop.svn.wordpress.org/trunk@58084 git-svn-id: http://core.svn.wordpress.org/trunk@57549 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/block-template-utils.php | 50 +++++++++++- wp-includes/blocks.php | 105 ++++++++++++++++++++++++-- wp-includes/class-wp-block-parser.php | 18 ++++- wp-includes/class-wp-block.php | 11 ++- wp-includes/version.php | 2 +- 5 files changed, 170 insertions(+), 16 deletions(-) diff --git a/wp-includes/block-template-utils.php b/wp-includes/block-template-utils.php index a7586061ad..b953993b67 100644 --- a/wp-includes/block-template-utils.php +++ b/wp-includes/block-template-utils.php @@ -53,7 +53,19 @@ function get_block_theme_folders( $theme_stylesheet = null ) { * * @since 5.9.0 * - * @return array[] The supported template part area values. + * @return array[] { + * The allowed template part area values. + * + * @type array ...$0 { + * Data for the allowed template part area. + * + * @type string $area Template part area name. + * @type string $label Template part area label. + * @type string $description Template part area description. + * @type string $icon Template part area icon. + * @type string $area_tag Template part area tag. + * } + * } */ function get_allowed_block_template_part_areas() { $default_area_definitions = array( @@ -91,7 +103,19 @@ function get_allowed_block_template_part_areas() { * * @since 5.9.0 * - * @param array[] $default_area_definitions An array of supported area objects. + * @param array[] $default_area_definitions { + * The allowed template part area values. + * + * @type array ...$0 { + * Data for the template part area. + * + * @type string $area Template part area name. + * @type string $label Template part area label. + * @type string $description Template part area description. + * @type string $icon Template part area icon. + * @type string $area_tag Template part area tag. + * } + * } */ return apply_filters( 'default_wp_template_part_areas', $default_area_definitions ); } @@ -103,7 +127,16 @@ function get_allowed_block_template_part_areas() { * * @since 5.9.0 * - * @return array[] The default template types. + * @return array[] { + * The default template types. + * + * @type array ...$0 { + * Data for the template type. + * + * @type string $title Template type title. + * @type string $description Template type description. + * } + * } */ function get_default_block_template_types() { $default_template_types = array( @@ -178,7 +211,16 @@ function get_default_block_template_types() { * * @since 5.9.0 * - * @param array[] $default_template_types An array of template types, formatted as [ slug => [ title, description ] ]. + * @param array[] $default_template_types { + * The default template types. + * + * @type array ...$0 { + * Data for the template type. + * + * @type string $title Template type title. + * @type string $description Template type description. + * } + * } */ return apply_filters( 'default_template_types', $default_template_types ); } diff --git a/wp-includes/blocks.php b/wp-includes/blocks.php index 854992de57..986af9a865 100644 --- a/wp-includes/blocks.php +++ b/wp-includes/blocks.php @@ -1201,7 +1201,17 @@ function get_comment_delimited_block_content( $block_name, $block_attributes, $b * * @since 5.3.1 * - * @param array $block A representative array of a single parsed block object. See WP_Block_Parser_Block. + * @param array $block { + * A representative array of a single parsed block object. See WP_Block_Parser_Block. + * + * @type string $blockName Name of block. + * @type array $attrs Attributes from block comment delimiters. + * @type array[] $innerBlocks List of inner blocks. An array of arrays that + * have the same structure as this one. + * @type string $innerHTML HTML from inside block comment delimiters. + * @type array $innerContent List of string fragments and null markers where + * inner blocks were found. + * } * @return string String of rendered HTML. */ function serialize_block( $block ) { @@ -1229,7 +1239,21 @@ function serialize_block( $block ) { * * @since 5.3.1 * - * @param array[] $blocks An array of representative arrays of parsed block objects. See serialize_block(). + * @param array[] $blocks { + * Array of block structures. + * + * @type array ...$0 { + * A representative array of a single parsed block object. See WP_Block_Parser_Block. + * + * @type string $blockName Name of block. + * @type array $attrs Attributes from block comment delimiters. + * @type array[] $innerBlocks List of inner blocks. An array of arrays that + * have the same structure as this one. + * @type string $innerHTML HTML from inside block comment delimiters. + * @type array $innerContent List of string fragments and null markers where + * inner blocks were found. + * } + * } * @return string String of rendered HTML. */ function serialize_blocks( $blocks ) { @@ -1638,7 +1662,17 @@ function _excerpt_render_inner_blocks( $parsed_block, $allowed_blocks ) { * * @global WP_Post $post The post to edit. * - * @param array $parsed_block A single parsed block object. + * @param array $parsed_block { + * A representative array of the block being rendered. See WP_Block_Parser_Block. + * + * @type string $blockName Name of block. + * @type array $attrs Attributes from block comment delimiters. + * @type array[] $innerBlocks List of inner blocks. An array of arrays that + * have the same structure as this one. + * @type string $innerHTML HTML from inside block comment delimiters. + * @type array $innerContent List of string fragments and null markers where + * inner blocks were found. + * } * @return string String of rendered HTML. */ function render_block( $parsed_block ) { @@ -1652,7 +1686,17 @@ function render_block( $parsed_block ) { * @since 5.9.0 The `$parent_block` parameter was added. * * @param string|null $pre_render The pre-rendered content. Default null. - * @param array $parsed_block The block being rendered. + * @param array $parsed_block { + * A representative array of the block being rendered. See WP_Block_Parser_Block. + * + * @type string $blockName Name of block. + * @type array $attrs Attributes from block comment delimiters. + * @type array[] $innerBlocks List of inner blocks. An array of arrays that + * have the same structure as this one. + * @type string $innerHTML HTML from inside block comment delimiters. + * @type array $innerContent List of string fragments and null markers where + * inner blocks were found. + * } * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block. */ $pre_render = apply_filters( 'pre_render_block', null, $parsed_block, $parent_block ); @@ -1668,8 +1712,29 @@ function render_block( $parsed_block ) { * @since 5.1.0 * @since 5.9.0 The `$parent_block` parameter was added. * - * @param array $parsed_block The block being rendered. - * @param array $source_block An un-modified copy of $parsed_block, as it appeared in the source content. + * @param array $parsed_block { + * A representative array of the block being rendered. See WP_Block_Parser_Block. + * + * @type string $blockName Name of block. + * @type array $attrs Attributes from block comment delimiters. + * @type array[] $innerBlocks List of inner blocks. An array of arrays that + * have the same structure as this one. + * @type string $innerHTML HTML from inside block comment delimiters. + * @type array $innerContent List of string fragments and null markers where + * inner blocks were found. + * } + * @param array $source_block { + * An un-modified copy of `$parsed_block`, as it appeared in the source content. + * See WP_Block_Parser_Block. + * + * @type string $blockName Name of block. + * @type array $attrs Attributes from block comment delimiters. + * @type array[] $innerBlocks List of inner blocks. An array of arrays that + * have the same structure as this one. + * @type string $innerHTML HTML from inside block comment delimiters. + * @type array $innerContent List of string fragments and null markers where + * inner blocks were found. + * } * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block. */ $parsed_block = apply_filters( 'render_block_data', $parsed_block, $source_block, $parent_block ); @@ -1695,7 +1760,17 @@ function render_block( $parsed_block ) { * @since 5.9.0 The `$parent_block` parameter was added. * * @param array $context Default context. - * @param array $parsed_block Block being rendered, filtered by `render_block_data`. + * @param array $parsed_block { + * A representative array of the block being rendered. See WP_Block_Parser_Block. + * + * @type string $blockName Name of block. + * @type array $attrs Attributes from block comment delimiters. + * @type array[] $innerBlocks List of inner blocks. An array of arrays that + * have the same structure as this one. + * @type string $innerHTML HTML from inside block comment delimiters. + * @type array $innerContent List of string fragments and null markers where + * inner blocks were found. + * } * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block. */ $context = apply_filters( 'render_block_context', $context, $parsed_block, $parent_block ); @@ -1711,7 +1786,21 @@ function render_block( $parsed_block ) { * @since 5.0.0 * * @param string $content Post content. - * @return array[] Array of parsed block objects. + * @return array[] { + * Array of block structures. + * + * @type array ...$0 { + * A representative array of a single parsed block object. See WP_Block_Parser_Block. + * + * @type string $blockName Name of block. + * @type array $attrs Attributes from block comment delimiters. + * @type array[] $innerBlocks List of inner blocks. An array of arrays that + * have the same structure as this one. + * @type string $innerHTML HTML from inside block comment delimiters. + * @type array $innerContent List of string fragments and null markers where + * inner blocks were found. + * } + * } */ function parse_blocks( $content ) { /** diff --git a/wp-includes/class-wp-block-parser.php b/wp-includes/class-wp-block-parser.php index 543f53691c..c4ffc5eb99 100644 --- a/wp-includes/class-wp-block-parser.php +++ b/wp-includes/class-wp-block-parser.php @@ -49,7 +49,7 @@ class WP_Block_Parser { public $stack; /** - * Parses a document and returns a list of block structures + * Parses a document and returns a list of block structures. * * When encountering an invalid parse will return a best-effort * parse. In contrast to the specification parser this does not @@ -58,7 +58,21 @@ class WP_Block_Parser { * @since 5.0.0 * * @param string $document Input document being parsed. - * @return array[] + * @return array[] { + * Array of block structures. + * + * @type array ...$0 { + * A representative array of a single parsed block object. See WP_Block_Parser_Block. + * + * @type string $blockName Name of block. + * @type array $attrs Attributes from block comment delimiters. + * @type array[] $innerBlocks List of inner blocks. An array of arrays that + * have the same structure as this one. + * @type string $innerHTML HTML from inside block comment delimiters. + * @type array $innerContent List of string fragments and null markers where + * inner blocks were found. + * } + * } */ public function parse( $document ) { $this->document = $document; diff --git a/wp-includes/class-wp-block.php b/wp-includes/class-wp-block.php index 60c026e0ac..4885b99219 100644 --- a/wp-includes/class-wp-block.php +++ b/wp-includes/class-wp-block.php @@ -113,7 +113,16 @@ class WP_Block { * * @since 5.5.0 * - * @param array $block Array of parsed block properties. + * @param array $block { + * A representative array of a single parsed block object. See WP_Block_Parser_Block. + * + * @type string $blockName Name of block. + * @type array $attrs Attributes from block comment delimiters. + * @type array $innerBlocks List of inner blocks. An array of arrays that + * have the same structure as this one. + * @type string $innerHTML HTML from inside block comment delimiters. + * @type array $innerContent List of string fragments and null markers where inner blocks were found. + * } * @param array $available_context Optional array of ancestry context values. * @param WP_Block_Type_Registry $registry Optional block type registry. */ diff --git a/wp-includes/version.php b/wp-includes/version.php index 7a4e68fc97..77c87e6d05 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.6-alpha-58082'; +$wp_version = '6.6-alpha-58084'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.