Some documentation improvements in WP_Block_Parser_Block.

[costdev]

Description

There are some documentation improvements suggested in the WP_Block_Parse_Block class. These changes were originally committed to Core (references at the end), but resulted in a Ensure version-controlled files are not modified or deleted failure in GitHub Actions.

These included:
@since tags

• 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.

It is suggested that 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.

Return value

• WP_Block_Parser::parse() - This appears to have been changed to array[] already.
• 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.

Step-by-step reproduction instructions

Related Trac ticket: https://core.trac.wordpress.org/ticket/56581

Related changesets:

• 54193
• 54194

Screenshots, screen recording, code snippet

No response

Environment info

No response

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

[Mamaduka]

That's an unexpected error for this class and file. While we maintain a few classes and block files in this repo, we don't maintain WP_Block_Parse_Block anymore.

You were correct, and changes should be committed to the Core.

[costdev]

Thanks @Mamaduka! I've left a comment on the Trac ticket and will follow up here once there's confirmation that all went through as expected so that this issue can be closed. 🙂

[gziolo]

The file is located in:

https://github.com/WordPress/gutenberg/blob/trunk/packages/block-serialization-default-parser/parser.php

It gets automatically updated in WordPress core when backporting changes from npm packages:

https://github.com/WordPress/wordpress-develop/blob/099ff6c5fe50c9009c79f9bbb9a0422db5e2f51f/tools/webpack/packages.js#L102

You were correct, and changes should be committed to the Core.

As far as I'm aware, the changes in WP core will get overridden with the file from Gutenberg because of the webpack line I shared. I think it's intended. That would also explain why there was an error on CI.

[Mamaduka]

Oh, thank you, @gziolo!

My grep skills missed that somehow 😞