WP_HTML_Tag_Processor: Its reference in the Developer Resources is broken

[juanmaguitar]

The WP_HTML_Tag_Processor reference in the Developer Resources is broken.

See:

• ​https://developer.wordpress.org/reference/classes/wp_html_tag_processor/
• ​https://developer.wordpress.org/reference/classes/wp_html_tag_processor/get_attribute/
• ​https://developer.wordpress.org/reference/classes/wp_html_tag_processor/is_tag_closer/
• ​https://developer.wordpress.org/reference/classes/wp_html_tag_processor/get_tag/

And there could be more

These docs seem to be produced from the PHPDoc comments in the relevant files. Some of these comments apparently are not properly processed by whatever tools are being used to generate the online reference docs from them.

The issue seems to be that somehow fails to close the example, and the following text ends up being part of it.

Those pages are generated from PHPDocs, so it’s either some unsupported syntax used or the tool that converts comments to that page has bugs.

[coffee2code]

This is actually the result of a few things.

The use of code fences (```php ... ```) in inline docs is prominent with the newly introduced WP_HTML_Tag_Processor and is just about the only usage in core. There is one preexisting case for ​WP_Theme_JSON::get_metadata_boolean(), which was introduced in WP 6.0 and also exhibits this issue.

Both the ​phpdoc-parser and the ​DevHub theme recognize the Markdown conversion of the beginning of a code block when it becomes <pre><code>. But by the code fence specifying the language, it results in the language being explicitly added to the resultant markup, e.g. <pre><code class="language-php"> which is different than what is expected. This results in:

1. The parser ​fails to recognize the code block and thus does not preserve its newlines.
2. The theme ​fails to recognize the code block and thus fails to replace the <pre><code class="language-php"> opening tags with the opening [code lang="php"] shortcode, but does replace the closing </code></pre> with [/code], resulting in unbalanced markup and the code shortcode not being invoked.

Both pieces of code can of course be updated, and I think that'll do it. It'll then require a reparsing. Things are slightly complicated by the fact that the DevHub theme isn't currently running its repo's trunk.

So this is probably more a meta.trac ticket than core.trac. Core could use simple code fences that don't specify 'php' which would "fix" things after a reparsing without any code changes, but ideally the parser and the theme should accommodate such syntax.

[azaozz]

Replying to coffee2code:

Something similar happens when importing comments with highlighted code from GitHub to Trac tickets, see: https://core.trac.wordpress.org/ticket/57375#comment:24. Or is this still part from the DevHub theme?

So this is probably more a meta.trac ticket than core.trac. Core could use simple code fences that don't specify 'php' which would "fix" things after a reparsing without any code changes, but ideally the parser and the theme should accommodate such syntax.

+1.

In the meantime such cases can probably be fixed in the inline docs/docblocks. As these are docs changes, they can be backported to the 6.2 branch immediately.

Also maybe it would be nice to have a warning to not use code highlighting when commenting on ​https://github.com/WordPress/wordpress-develop PRs for now, perhaps in the default "New PR" text.

[costdev]

@coffee2code To clarify, is the inline docs/docblocks fix just to remove php from ```php?

[coffee2code]

I have opened up (and resolved) related tickets for:

• phpdoc-parser: ​Retain newlines for code blocks when the code tag has attributes
• wporg-developer theme: ​Properly format code blocks when the code tag has attributes

The formatting issues raised by this ticket are resolved. The parser and DevHub will now properly recognize and display code blocks defined using code fences, including when a language is specified for the code fence. (Though it currently assumes all such code fences refer to PHP despite what may be specified.)

However, whether the code fences should have been used in the first place is a discussion for #core-docs people. Core's ​inline documentation standard indicate that inline code examples should be defined using an indentation of 4 spaces.

As I see it, either that documentation should be amended to indicate that code fences are supported (and if so, if the language should be specified or not) and either recommend its usage or indicate indentation is recommended), or the code fences should be removed entirely.

[coffee2code]

@costdev: Sorry, I was waiting on making and testing parser and DevHub fixes to accommodate the code fence syntax. As I just noted in my prior comment, that support has been added and the issues reported here are no longer an issue in the Code Reference.

However, as I also noted, the use of code fences in inline docs is new. #core-docs people should determine if its usage should be added to the documentation standard or if the existing handful of code fence syntax usage should be removed from core. Again, see the last bit of my previous comment.

[SergeyBiryukov]

Replying to coffee2code:

However, whether the code fences should have been used in the first place is a discussion for #core-docs people. Core's ​inline documentation standard indicate that inline code examples should be defined using an indentation of 4 spaces.

Ah yes, good catch. In my understanding, using a different format here appears to be accidental rather than intentional, so I would suggest updating these examples to match the format used by the rest of core, see 58028.diff​.

[coffee2code]

@SergeyBiryukov: Looks good, though bare code fences (those not explicitly specifying PHP) should be updated as well (e.g. ​WP_HTML_Tag_Processor::set_bookmark()).

There are only a handful of them and they're all also in wp-includes/html-api/class-wp-html-tag-processor.php.

[dmsnell]

cc: @johnbillion who just removed a fair amount of the indenting 😄

[johnbillion]

I must admit that in [55718] I chose to retain the backtick code fences over the indentation as they declare the language of the code contained within, but yes, this goes against the docs coding standards which state indentation should be used. Happy to switch back to indentation minus the backtick fences.

[SergeyBiryukov]

In 55727:

Docs: Update code examples formatting in WP_HTML_Tag_Processor documentation.

Per the ​documentation standards, code samples should be created by indenting every line of the code by 4 spaces, with a blank line before and after. This matches the format used by the rest of core.

Follow-up to [55203], [55304], [55718], [55724].

Props juanmaguitar, coffee2code, azaozz, costdev, dmsnell, johnbillion, SergeyBiryukov.
Fixes #58028.

[SergeyBiryukov]

Reopening for 6.2.1.

[SergeyBiryukov]

In 55729:

Docs: Update code examples formatting in WP_HTML_Tag_Processor documentation.

Per the ​documentation standards, code samples should be created by indenting every line of the code by 4 spaces, with a blank line before and after. This matches the format used by the rest of core.

Follow-up to [55203], [55304], [55718], [55724].

Props juanmaguitar, coffee2code, azaozz, costdev, dmsnell, johnbillion, SergeyBiryukov.
Merges [55727] to the 6.2 branch.
Fixes #58028.