From a2cff5b189ff4643a46e905396271bb2c521ce6f Mon Sep 17 00:00:00 2001 From: Dennis Snell Date: Wed, 26 Jul 2023 12:16:26 -0700 Subject: [PATCH] HTML API: Adjust code stying to Gutenberg's linter's preferences --- ...ass-wp-html-active-formatting-elements.php | 5 ++-- .../html-api/class-wp-html-open-elements.php | 28 ++++++++++++++----- .../html-api/class-wp-html-processor.php | 27 +++++++++--------- 3 files changed, 36 insertions(+), 24 deletions(-) diff --git a/src/wp-includes/html-api/class-wp-html-active-formatting-elements.php b/src/wp-includes/html-api/class-wp-html-active-formatting-elements.php index 73831e9f36fab..baa34de5a32aa 100644 --- a/src/wp-includes/html-api/class-wp-html-active-formatting-elements.php +++ b/src/wp-includes/html-api/class-wp-html-active-formatting-elements.php @@ -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 @@ public function remove_node( $token ) { * > 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 @@ public function walk_down() { * > 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 */ diff --git a/src/wp-includes/html-api/class-wp-html-open-elements.php b/src/wp-includes/html-api/class-wp-html-open-elements.php index fabac341c66b9..8852d04997035 100644 --- a/src/wp-includes/html-api/class-wp-html-open-elements.php +++ b/src/wp-includes/html-api/class-wp-html-open-elements.php @@ -110,7 +110,7 @@ public function current_node() { * @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 @@ public function has_element_in_scope( $tag_name ) { 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 @@ public function has_element_in_scope( $tag_name ) { * * @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 @@ public function has_element_in_button_scope( $tag_name ) { 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 @@ public function has_element_in_button_scope( $tag_name ) { * * @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 @@ public function has_element_in_table_scope( $tag_name ) { * * @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 @@ public function has_element_in_select_scope( $tag_name ) { * * @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 @@ public function remove_node( $token ) { * > 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 @@ public function walk_down() { * > 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 */ diff --git a/src/wp-includes/html-api/class-wp-html-processor.php b/src/wp-includes/html-api/class-wp-html-processor.php index 68bd3418f24d9..d5f813a44aa68 100644 --- a/src/wp-includes/html-api/class-wp-html-processor.php +++ b/src/wp-includes/html-api/class-wp-html-processor.php @@ -232,16 +232,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 = '', $encoding = 'UTF-8' ) { - if ( '' !== $context ) { + if ( '' !== $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 +332,7 @@ public function get_last_error() { * * @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 +410,7 @@ public function next_tag( $query = null ) { * * @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 +496,7 @@ public function get_breadcrumbs() { * * @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 @@ -641,7 +641,7 @@ private function step_in_body() { * * @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. */ @@ -859,7 +859,7 @@ public function set_bookmark( $bookmark_name ) { * * @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 */ @@ -873,8 +873,6 @@ private function close_a_p_element() { * * @since 6.4.0 * - * @throws 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. @@ -902,7 +900,7 @@ private function generate_implied_end_tags( $except_for_this_element = null ) { * * @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 * @@ -919,6 +917,7 @@ private function reconstruct_active_formatting_elements() { $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. @@ -944,7 +943,7 @@ private function reconstruct_active_formatting_elements() { * * @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 */ @@ -1165,7 +1164,7 @@ public static function is_special( $tag_name ) { 'WBR' === $tag_name || 'XMP' === $tag_name || - // MathML + // MathML. 'MI' === $tag_name || 'MO' === $tag_name || 'MN' === $tag_name || @@ -1173,7 +1172,7 @@ public static function is_special( $tag_name ) { 'MTEXT' === $tag_name || 'ANNOTATION-XML' === $tag_name || - // SVG + // SVG. 'FOREIGNOBJECT' === $tag_name || 'DESC' === $tag_name || 'TITLE' === $tag_name