Wrong doc in WP_Block_Parser class

[Chouby]

WP_Block_Parser::parse() is documented as returning WP_Block_Parser_Block[] but it returns an array or arrays.

WP_Block_Parser::$output is also documented as being WP_Block_Parser_Block[] but is also an array of arrays.

This is visible in several places of the parse() method where $this->output is explicitely casted to an array.

Additionnally, I noticed that several @since seem to refer to Gütenberg versions instead of WordPress versions (as version numbers are < 5.0.0).

[Chouby]

I attached two patches.

• The first one changes WP_Block_Parser_Block[] to array[].
• The second one fixes @since. I separated from the first one as it was not the primary goal of this ticket and looses some changelog information which seems related to early Gütenberg development.

[Chouby]

I wrongly assumed that everything was introduced in 5.0.0. The second patch for @since fixes that as some chnages were introduced in 5.1.0.

[SergeyBiryukov]

Hi there, thanks for the patches!

Replying to Chouby:

I wrongly assumed that everything was introduced in 5.0.0.

Upon a closer look, these properties and methods were all introduced in [43751], [43884], [43955] for the 5.0 branch, and then backported to trunk in [44116], [44261], [44281], respectively. So 56581-since.patch​ appears to be correct.

[SergeyBiryukov]

In 54193:

Docs: Correct @since tags for some block parser properties and methods.

This affects:

• WP_Block_Parser::$empty_attrs
• WP_Block_Parser::next_token()
• WP_Block_Parser::freeform()
• WP_Block_Parser_Block::$innerContent

The @since tags referred to early Gutenberg versions instead of WordPress core. These properties and methods were introduced in WordPress 5.0, so 5.0.0 is the correct version.

Some of the other @since tags are removed, as they are related to early Gutenberg development before it was merged into WordPress core, and are not relevant for core.

Follow-up to [43751], [43884], [43955] for the 5.0 branch, [44116], [44261], [44281] for trunk.

Props Chouby.
See #56581.

[SergeyBiryukov]

Replying to Chouby:

WP_Block_Parser::parse() is documented as returning WP_Block_Parser_Block[] but it returns an array or arrays.

WP_Block_Parser::$output is also documented as being WP_Block_Parser_Block[] but is also an array of arrays.

This is visible in several places of the parse() method where $this->output is explicitely casted to an array.

Indeed. I believe we can use the WP_Block_Parser_Block[][] notation for that (with extra square brackets), there is a precedent for that in core as of [53058].

[SergeyBiryukov]

Replying to SergeyBiryukov:

I believe we can use the WP_Block_Parser_Block[][] notation for that (with extra square brackets), there is a precedent for that in core as of [53058].

Hmm, scratch that. Checking the type of WP_Block_Parser::$output, it is an array of arrays of various values and not an array of arrays of WP_Block_Parser_Block objects as I thought initially. 56581.patch​ is correct.

[SergeyBiryukov]

In 54194:

Docs: Correct @return type for WP_Block_Parser::parse().

This affects:

• WP_Block_Parser::parse()
• WP_Block_Parser::$output

Both the method and the property are documented as returning WP_Block_Parser_Block[] (an array of WP_Block_Parser_Block objects), but the result is in fact an array of arrays of various values, so array[] is the correct notation.

Follow-up to [43751] for the 5.0 branch, [44116] for trunk.

Props Chouby.
Fixes #56581.

[SergeyBiryukov]

It appears that these changes should first be made ​upstream in the Gutenberg respository and then backported to core, as the ​tests fail otherwise:

Ensure version-controlled files are not modified or deleted

Run git diff --exit-code
diff --git a/src/wp-includes/class-wp-block-parser.php b/src/wp-includes/class-wp-block-parser.php
index e987307..27c85cf 100644
--- a/src/wp-includes/class-wp-block-parser.php
+++ b/src/wp-includes/class-wp-block-parser.php
@@ -62,7 +62,7 @@ class WP_Block_Parser_Block {
 	 *   'innerContent' => array( 'Before', null, 'Inner', null, 'After' ),
 	 * )
 	 *
-	 * @since 5.0.0
+	 * @since 4.2.0
 	 * @var array
 	 */
 	public $innerContent;
...

[SergeyBiryukov]

In 54195:

Docs: Revert the WP_Block_Parser documentation changes now.

This commit reverts [54193] and [54194].

It appears that these changes should first be made ​upstream in the Gutenberg respository and then backported to core, as the ​tests fail otherwise.

See #56581.

[SergeyBiryukov]

Since this is a documentation-only change, I believe in can stay in 6.1 for now to be fixed during the beta cycle.

[chaion07]

@Chouby thanks for reporting this. We reviewed this ticket during a recent bug-scrub. Here's the summary of the feedback received from the team we are hoping to see this being merged after changes have been made in the Gutenberg Repo and then backported to Core. Thanks!

Props to @mukesh27 & @robinwpdeveloper

[audrasjb]

With WP 6.1 RC 1 scheduled today (Oct 11, 2022), there is not much time left to address this ticket. Let's move it to the next milestone.

[costdev]

This ticket was discussed during the recent bug scrub. I've opened an issue on the Gutenberg repository so that this can be looked at upstream: ​https://github.com/WordPress/gutenberg/issues/47947

@audrasjb Should this ticket be closed as reported-upstream, or should it be used to track the backport?

[costdev]

@SergeyBiryukov Take a look at @mamaduka's ​comment on the GH issue. It appears that the class is no longer maintained in the Gutenberg repository, and the error was unexpected.

Edit: It appears this was incorrect 😅. See ​this comment on the GitHub issue.

[costdev]

As this has been reported upstream and the change must happen there. I'm closing this ticket as reported-upstream.