Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 2 commits into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
266012f
HTML API: Adjust code stying to Gutenberg's linter's preferences
dmsnell Jul 26, 2023
1593b89
Adjust styling to avoid using PHPDoc syntax
dmsnell Aug 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions src/wp-includes/html-api/class-wp-html-active-formatting-elements.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 ) {
Expand Down Expand Up @@ -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
*/
Expand All @@ -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
*/
Expand Down
28 changes: 21 additions & 7 deletions src/wp-includes/html-api/class-wp-html-open-elements.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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
Expand All @@ -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.
}

/**
Expand All @@ -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
Expand All @@ -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.
}

/**
Expand All @@ -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.
}

/**
Expand All @@ -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;
Expand Down Expand Up @@ -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
*/
Expand All @@ -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
*/
Expand Down
37 changes: 19 additions & 18 deletions src/wp-includes/html-api/class-wp-html-processor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
*
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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 ) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dmsnell The PR mentions that there should be no code changes. Is this change intentional?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good eye @dream-encode - I didn't mean to mislead there. this should be the single code change, and when I overlooked it it's because it was always intended to be the case to only support UTF-8 and bail if any others are passed. all the docs omit this argument but it's important to be there as we continue to build support into the class.

hopefully there should be no behavioral change, unless someone was intentionally trying to run this in an unsupported mode (which should not be the case as this only merged into trunk a few days ago).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated the description to better explain

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(
Expand Down Expand Up @@ -332,7 +333,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.
Expand Down Expand Up @@ -410,7 +411,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
Expand Down Expand Up @@ -496,7 +497,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
Expand Down Expand Up @@ -672,7 +673,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.
*/
Expand Down Expand Up @@ -890,7 +891,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
*/
Expand All @@ -904,8 +905,6 @@ private function close_a_p_element() {
*
* @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.
Expand All @@ -928,10 +927,11 @@ private function generate_implied_end_tags( $except_for_this_element = null ) {
* 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() {
Expand All @@ -953,7 +953,7 @@ private function generate_implied_end_tags_thoroughly() {
*
* @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
*
Expand All @@ -970,6 +970,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.
Expand All @@ -995,7 +996,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
*/
Expand Down Expand Up @@ -1216,15 +1217,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
Expand Down Expand Up @@ -1307,7 +1308,7 @@ public static function is_void( $tag_name ) {
/**
* 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
Expand Down
4 changes: 3 additions & 1 deletion src/wp-includes/html-api/class-wp-html-token.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down