HTML API: Satisfy return types in new methods

[dlh]

A handful of methods introduced to the HTML API for WordPress 6.7 declare return types but don't return a value in some (improbable) circumstances. The linked PR updates the new methods to return a value in even these cases to avoid generating fatal errors when the return type isn't met.

​See discussion in the #core-html-api Slack channel.

@dlh01 I've updated the comment and called $this->bail() in the HTML Processor, which would return false and bring the notice up for inspection, should someone want to investigate.

for the Tag Processor I returned the tag name instead of null since it was more in line with what ought to be there.

ultimately I'd rather not make these kind of code adjustments, but we already have a few where the tooling is wrong or the code isn't structured in a way that the tooling can understand. if we can rearrange the code so that it's not surprising in these ways that would seem like another nice improvement.

[dmsnell]

In 59001:

HTML API: Add sentinels for unreachable code.

There are places in the HTML API code where some tools get confused and flag invalid types for the return of a function because they are unable to detect that the end of the function is unreachable.

Since PHP doesn't provide a way to encode total matching in the source code, this patch adds a few extra lines in those unreachable locations to satisfy any tooling which isn't able to fully analyze the code.

Additionally this serves as extra guarding in case someone changes these functions in a way which would break them and the existing test suite doesn't catch those breakages.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/7315
Discussed in https://core.trac.wordpress.org/ticket/62018

Props dlh, dmsnell.
Fixes #62018.

Merged in [59001]
​https://github.com/wordpress/wordpress-develop/commit/ad1db1158c9e0ea1101e7e0e6077f8d73e5c0773

[dmsnell]

@dlh I reclassified this ticket as an enhancement since the code in question was unreachable. also, while I understand this guards against future breakages to the code, there are no current bugs, and in a sense all code is susceptible to being changed in ways that introduce type errors - this isn't unique the lines changed by this patch.

anyway, thanks for submitting this patch. if you want to explore ways to eliminate the need for it by rearranging code in a way that other tooling can understand, please be invited to do so!