Make WordPress Core

#58028 closed defect (bug) (fixed)

WP_HTML_Tag_Processor: Its reference in the Developer Resources is broken

Reported by: juanmaguitar's profile juanmaguitar Owned by: sergeybiryukov's profile SergeyBiryukov
Milestone: 6.2.1 Priority: normal
Severity: normal Version: 6.2
Component: HTML API Keywords: has-patch fixed-major
Focuses: docs Cc:

Description

The WP_HTML_Tag_Processor reference in the Developer Resources is broken.

See:

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.

Attachments (1)

58028.diff (8.0 KB) - added by SergeyBiryukov 14 months ago.

Download all attachments as: .zip

Change History (16)

This ticket was mentioned in Slack in #core-editor by juanmaguitar. View the logs.


15 months ago

#2 @SergeyBiryukov
15 months ago

  • Component changed from General to HTML API
  • Milestone changed from Awaiting Review to 6.2.1

#3 follow-up: @coffee2code
15 months ago

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.

#4 in reply to: ↑ 3 @azaozz
15 months ago

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.

Last edited 15 months ago by azaozz (previous) (diff)

#5 @costdev
15 months ago

  • Keywords dev-feedback added

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

#6 follow-up: @coffee2code
14 months ago

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

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.

#7 @coffee2code
14 months ago

  • Keywords dev-feedback removed

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

#8 in reply to: ↑ 6 @SergeyBiryukov
14 months ago

  • Keywords has-patch added

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.

#9 @coffee2code
14 months ago

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

#10 @dmsnell
14 months ago

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

#11 @johnbillion
14 months ago

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.

This ticket was mentioned in Slack in #core by audrasjb. View the logs.


14 months ago

#13 @SergeyBiryukov
14 months ago

  • Owner set to SergeyBiryukov
  • Resolution set to fixed
  • Status changed from new to closed

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.

#14 @SergeyBiryukov
14 months ago

  • Keywords fixed-major added
  • Resolution fixed deleted
  • Status changed from closed to reopened

Reopening for 6.2.1.

#15 @SergeyBiryukov
14 months ago

  • Resolution set to fixed
  • Status changed from reopened to closed

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.

Note: See TracTickets for help on using tickets.