HTML API: Adjust code stying to Gutenberg's linter's preferences

Author: dmsnell

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
 	 */

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
 	 */

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 = '<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 +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,15 +1164,15 @@ public static function is_special( $tag_name ) {
 			'WBR' === $tag_name ||
 			'XMP' === $tag_name ||
 
-			// MathML
+			// MathML.
 			'MI' === $tag_name ||
 			'MO' === $tag_name ||
 			'MN' === $tag_name ||
 			'MS' === $tag_name ||
 			'MTEXT' === $tag_name ||
 			'ANNOTATION-XML' === $tag_name ||
 
-			// SVG
+			// SVG.
 			'FOREIGNOBJECT' === $tag_name ||
 			'DESC' === $tag_name ||
 			'TITLE' === $tag_name