HTML API: Adjust code styling to Gutenberg's linter's preferences.

Adjust the code style according to the rules that the linting process in Gutenberg requires.

There are only a couple code changes that should have no effect on the runtime:
 - A missing check to verify that only `UTF-8` is supported has been added (brought up because it was identified as an undefined variable).
 - A few `return false;` statements have been added to avoid having the linter complain that functions don't return a value despite indicating they return `bool`. The functions are stubs for coming support and currently `throw`, so the `return` statements are unreachable.

Props dmsnell, costdev, davidbaumwald, peterwilsoncc, SergeyBiryukov.
Fixes #58918.
Built from https://develop.svn.wordpress.org/trunk@56363


git-svn-id: http://core.svn.wordpress.org/trunk@55875 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Bernhard Reiter 2023-08-07 13:50:27 +00:00
parent da0f366b22
commit fa83c8e1cd
5 changed files with 46 additions and 30 deletions

View File

@ -50,7 +50,6 @@ class WP_HTML_Active_Formatting_Elements {
*
* @param WP_HTML_Token $token Look for this node in the stack.
* @return bool Whether the referenced node is in the stack of active formatting elements.
*
*/
public function contains_node( $token ) {
foreach ( $this->walk_up() as $item ) {
@ -149,7 +148,7 @@ class WP_HTML_Active_Formatting_Elements {
* > EM -> STRONG -> A ->
*
* To start with the most-recently added element and walk towards the top,
* @see WP_HTML_Active_Formatting_Elements::walk_up
* see WP_HTML_Active_Formatting_Elements::walk_up().
*
* @since 6.4.0
*/
@ -176,7 +175,7 @@ class WP_HTML_Active_Formatting_Elements {
* > A -> STRONG -> EM ->
*
* To start with the first added element and walk towards the bottom,
* @see WP_HTML_Active_Formatting_Elements::walk_down
* see WP_HTML_Active_Formatting_Elements::walk_down().
*
* @since 6.4.0
*/

View File

@ -110,7 +110,7 @@ class WP_HTML_Open_Elements {
* @param string[] $termination_list List of elements that terminate the search.
* @return bool Whether the element was found in a specific scope.
*/
public function has_element_in_specific_scope( $tag_name, $termination_list ) {
public function has_element_in_specific_scope( $tag_name, $termination_list ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
foreach ( $this->walk_up() as $node ) {
if ( $node->node_name === $tag_name ) {
return true;
@ -134,6 +134,7 @@ class WP_HTML_Open_Elements {
return $this->has_element_in_specific_scope(
$tag_name,
array(
/*
* Because it's not currently possible to encounter
* one of the termination elements, they don't need
@ -152,11 +153,15 @@ class WP_HTML_Open_Elements {
*
* @see https://html.spec.whatwg.org/#has-an-element-in-list-item-scope
*
* @throws WP_HTML_Unsupported_Exception Always until this function is implemented.
*
* @param string $tag_name Name of tag to check.
* @return bool Whether given element is in scope.
*/
public function has_element_in_list_item_scope( $tag_name ) {
public function has_element_in_list_item_scope( $tag_name ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
throw new WP_HTML_Unsupported_Exception( 'Cannot process elements depending on list item scope.' );
return false; // The linter requires this unreachable code until the function is implemented and can return.
}
/**
@ -173,6 +178,7 @@ class WP_HTML_Open_Elements {
return $this->has_element_in_specific_scope(
$tag_name,
array(
/*
* Because it's not currently possible to encounter
* one of the termination elements, they don't need
@ -191,11 +197,15 @@ class WP_HTML_Open_Elements {
*
* @see https://html.spec.whatwg.org/#has-an-element-in-table-scope
*
* @throws WP_HTML_Unsupported_Exception Always until this function is implemented.
*
* @param string $tag_name Name of tag to check.
* @return bool Whether given element is in scope.
*/
public function has_element_in_table_scope( $tag_name ) {
public function has_element_in_table_scope( $tag_name ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
throw new WP_HTML_Unsupported_Exception( 'Cannot process elements depending on table scope.' );
return false; // The linter requires this unreachable code until the function is implemented and can return.
}
/**
@ -205,11 +215,15 @@ class WP_HTML_Open_Elements {
*
* @see https://html.spec.whatwg.org/#has-an-element-in-select-scope
*
* @throws WP_HTML_Unsupported_Exception Always until this function is implemented.
*
* @param string $tag_name Name of tag to check.
* @return bool Whether given element is in scope.
*/
public function has_element_in_select_scope( $tag_name ) {
public function has_element_in_select_scope( $tag_name ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
throw new WP_HTML_Unsupported_Exception( 'Cannot process elements depending on select scope.' );
return false; // The linter requires this unreachable code until the function is implemented and can return.
}
/**
@ -219,7 +233,7 @@ class WP_HTML_Open_Elements {
*
* @see https://html.spec.whatwg.org/#has-an-element-in-button-scope
*
* @return bool
* @return bool Whether a P is in BUTTON scope.
*/
public function has_p_in_button_scope() {
return $this->has_p_in_button_scope;
@ -320,7 +334,7 @@ class WP_HTML_Open_Elements {
* > EM -> STRONG -> A ->
*
* To start with the most-recently added element and walk towards the top,
* @see WP_HTML_Open_Elements::walk_up
* see WP_HTML_Open_Elements::walk_up().
*
* @since 6.4.0
*/
@ -347,7 +361,7 @@ class WP_HTML_Open_Elements {
* > A -> STRONG -> EM ->
*
* To start with the first added element and walk towards the bottom,
* @see WP_HTML_Open_Elements::walk_down
* see WP_HTML_Open_Elements::walk_down().
*
* @since 6.4.0
*/

View File

@ -16,7 +16,7 @@
* unsupported markup, it aborts early to avoid unintentionally breaking
* the document. The HTML Processor should never break an HTML document.
*
* While the {@see WP_HTML_Tag_Processor} is a valuable tool for modifying
* While the `WP_HTML_Tag_Processor` is a valuable tool for modifying
* attributes on individual HTML tags, the HTML Processor is more capable
* and useful for the following operations:
*
@ -47,7 +47,7 @@
*
* Breadcrumbs represent the stack of open elements from the root
* of the document or fragment down to the currently-matched node,
* if one is currently selected. Call {@see WP_HTML_Processor::get_breadcrumbs}
* if one is currently selected. Call WP_HTML_Processor::get_breadcrumbs()
* to inspect the breadcrumbs for a matched tag.
*
* Breadcrumbs can specify nested HTML structure and are equivalent
@ -121,6 +121,7 @@
*
* @since 6.4.0
*
* @see WP_HTML_Tag_Processor
* @see https://html.spec.whatwg.org/
*/
class WP_HTML_Processor extends WP_HTML_Tag_Processor {
@ -232,16 +233,16 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
* @return WP_HTML_Processor|null The created processor if successful, otherwise null.
*/
public static function createFragment( $html, $context = '<body>', $encoding = 'UTF-8' ) {
if ( '<body>' !== $context ) {
if ( '<body>' !== $context || 'UTF-8' !== $encoding ) {
return null;
}
$p = new self( $html, self::CONSTRUCTOR_UNLOCK_CODE );
$p = new self( $html, self::CONSTRUCTOR_UNLOCK_CODE );
$p->state->context_node = array( 'BODY', array() );
$p->state->insertion_mode = WP_HTML_Processor_State::INSERTION_MODE_IN_BODY;
// @TODO: Create "fake" bookmarks for non-existent but implied nodes.
$p->bookmarks['root-node'] = new WP_HTML_Span( 0, 0 );
$p->bookmarks['root-node'] = new WP_HTML_Span( 0, 0 );
$p->bookmarks['context-node'] = new WP_HTML_Span( 0, 0 );
$p->state->stack_of_open_elements->push(
@ -332,7 +333,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
*
* @since 6.4.0
*
* @throws WP_HTML_Unsupported_Exception
* @throws Exception When unable to allocate a bookmark for the next token in the input HTML document.
*
* @param array|string|null $query {
* Optional. Which tag name to find, having which class, etc. Default is to find any tag.
@ -410,7 +411,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
*
* @since 6.4.0
*
* @throws Exception
* @throws Exception When unable to allocate a bookmark for the next token in the input HTML document.
*
* @see self::PROCESS_NEXT_NODE
* @see self::REPROCESS_CURRENT_NODE
@ -496,7 +497,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
*
* @since 6.4.0
*
* @throws WP_HTML_Unsupported_Exception
* @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
*
* @see https://html.spec.whatwg.org/#parsing-main-inbody
* @see self::step
@ -672,7 +673,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
*
* @since 6.4.0
*
* @throws Exception
* @throws Exception When unable to allocate requested bookmark.
*
* @return string|false Name of created bookmark, or false if unable to create.
*/
@ -890,7 +891,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
*
* @since 6.4.0
*
* @throws WP_HTML_Unsupported_Exception
* @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
*
* @see https://html.spec.whatwg.org/#close-a-p-element
*/
@ -904,8 +905,6 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
*
* @since 6.4.0
*
* @throws WP_HTML_Unsupported_Exception
*
* @see https://html.spec.whatwg.org/#generate-implied-end-tags
*
* @param string|null $except_for_this_element Perform as if this element doesn't exist in the stack of open elements.
@ -928,10 +927,11 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
* Closes elements that have implied end tags, thoroughly.
*
* See the HTML specification for an explanation why this is
* different from {@see WP_HTML_Processor::generate_implied_end_tags}.
* different from generating end tags in the normal sense.
*
* @since 6.4.0
*
* @see WP_HTML_Processor::generate_implied_end_tags
* @see https://html.spec.whatwg.org/#generate-implied-end-tags
*/
private function generate_implied_end_tags_thoroughly() {
@ -953,7 +953,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
*
* @since 6.4.0
*
* @throws WP_HTML_Unsupported_Exception
* @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
*
* @see https://html.spec.whatwg.org/#reconstruct-the-active-formatting-elements
*
@ -970,6 +970,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
$last_entry = $this->state->active_formatting_elements->current_node();
if (
/*
* > If the last (most recently added) entry in the list of active formatting elements is a marker;
* > stop this algorithm.
@ -995,7 +996,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
*
* @since 6.4.0
*
* @throws WP_HTML_Unsupported_Exception
* @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
*
* @see https://html.spec.whatwg.org/#adoption-agency-algorithm
*/
@ -1216,7 +1217,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
'WBR' === $tag_name ||
'XMP' === $tag_name ||
// MathML
// MathML.
'MI' === $tag_name ||
'MO' === $tag_name ||
'MN' === $tag_name ||
@ -1224,7 +1225,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
'MTEXT' === $tag_name ||
'ANNOTATION-XML' === $tag_name ||
// SVG
// SVG.
'FOREIGNOBJECT' === $tag_name ||
'DESC' === $tag_name ||
'TITLE' === $tag_name
@ -1307,7 +1308,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
/**
* Unlock code that must be passed into the constructor to create this class.
*
* This class extends {@see WP_HTML_Tag_Processor}, which has a public class
* This class extends the WP_HTML_Tag_Processor, which has a public class
* constructor. Therefore, it's not possible to have a private constructor here.
*
* This unlock code is used to ensure that anyone calling the constructor is

View File

@ -36,10 +36,12 @@ class WP_HTML_Token {
/**
* Name of node; lowercase names such as "marker" are not HTML elements.
*
* For HTML elements/tags this value should come from {@see WP_HTML_Processor::get_tag}.
* For HTML elements/tags this value should come from WP_HTML_Processor::get_tag().
*
* @since 6.4.0
*
* @see WP_HTML_Processor::get_tag()
*
* @var string
*/
public $node_name = null;

View File

@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
$wp_version = '6.4-alpha-56362';
$wp_version = '6.4-alpha-56363';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.