From fa83c8e1cd4e082bfdc28e2c6122ad1ce9dac0b2 Mon Sep 17 00:00:00 2001 From: Bernhard Reiter Date: Mon, 7 Aug 2023 13:50:27 +0000 Subject: [PATCH] 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 --- ...ass-wp-html-active-formatting-elements.php | 5 +-- .../html-api/class-wp-html-open-elements.php | 28 ++++++++++---- .../html-api/class-wp-html-processor.php | 37 ++++++++++--------- wp-includes/html-api/class-wp-html-token.php | 4 +- wp-includes/version.php | 2 +- 5 files changed, 46 insertions(+), 30 deletions(-) diff --git a/wp-includes/html-api/class-wp-html-active-formatting-elements.php b/wp-includes/html-api/class-wp-html-active-formatting-elements.php index 73831e9f36..95989914be 100644 --- a/wp-includes/html-api/class-wp-html-active-formatting-elements.php +++ b/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 @@ 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 */ diff --git a/wp-includes/html-api/class-wp-html-open-elements.php b/wp-includes/html-api/class-wp-html-open-elements.php index fabac341c6..0518ccb8bf 100644 --- a/wp-includes/html-api/class-wp-html-open-elements.php +++ b/wp-includes/html-api/class-wp-html-open-elements.php @@ -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 */ diff --git a/wp-includes/html-api/class-wp-html-processor.php b/wp-includes/html-api/class-wp-html-processor.php index c8e898389c..0e361cca27 100644 --- a/wp-includes/html-api/class-wp-html-processor.php +++ b/wp-includes/html-api/class-wp-html-processor.php @@ -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 = '', $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 +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 diff --git a/wp-includes/html-api/class-wp-html-token.php b/wp-includes/html-api/class-wp-html-token.php index 3725711466..f6edd52355 100644 --- a/wp-includes/html-api/class-wp-html-token.php +++ b/wp-includes/html-api/class-wp-html-token.php @@ -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; diff --git a/wp-includes/version.php b/wp-includes/version.php index e989dd8900..367dbf7d12 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -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.