WordPress.org
Get WordPress

Make WordPress Core

Changeset 56363


Ignore:
Timestamp:
08/07/2023 01:48:55 PM (3 years ago)
Author:
Bernhard Reiter
Message:

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.

Location:
trunk/src/wp-includes/html-api
Files:
4 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/html-api/class-wp-html-active-formatting-elements.php

    r56274 r56363  
    5151         * @param WP_HTML_Token $token Look for this node in the stack.
    5252         * @return bool Whether the referenced node is in the stack of active formatting elements.
    53          *
    5453         */
    5554        public function contains_node( $token ) {
    … …  
    150149         *
    151150         * To start with the most-recently added element and walk towards the top,
    152          * @see WP_HTML_Active_Formatting_Elements::walk_up
     151         * see WP_HTML_Active_Formatting_Elements::walk_up().
    153152         *
    154153         * @since 6.4.0
    … …  
    177176         *
    178177         * To start with the first added element and walk towards the bottom,
    179          * @see WP_HTML_Active_Formatting_Elements::walk_down
     178         * see WP_HTML_Active_Formatting_Elements::walk_down().
    180179         *
    181180         * @since 6.4.0

  • trunk/src/wp-includes/html-api/class-wp-html-open-elements.php

    r56274 r56363  
    111111         * @return bool Whether the element was found in a specific scope.
    112112         */
    113         public function has_element_in_specific_scope( $tag_name, $termination_list ) {
     113        public function has_element_in_specific_scope( $tag_name, $termination_list ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
    114114                foreach ( $this->walk_up() as $node ) {
    115115                        if ( $node->node_name === $tag_name ) {
    … …  
    135135                        $tag_name,
    136136                        array(
     137
    137138                                /*
    138139                                 * Because it's not currently possible to encounter
    … …  
    153154         * @see https://html.spec.whatwg.org/#has-an-element-in-list-item-scope
    154155         *
     156         * @throws WP_HTML_Unsupported_Exception Always until this function is implemented.
     157         *
    155158         * @param string $tag_name Name of tag to check.
    156159         * @return bool Whether given element is in scope.
    157160         */
    158         public function has_element_in_list_item_scope( $tag_name ) {
     161        public function has_element_in_list_item_scope( $tag_name ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
    159162                throw new WP_HTML_Unsupported_Exception( 'Cannot process elements depending on list item scope.' );
     163
     164                return false; // The linter requires this unreachable code until the function is implemented and can return.
    160165        }
    161166
    … …  
    174179                        $tag_name,
    175180                        array(
     181
    176182                                /*
    177183                                 * Because it's not currently possible to encounter
    … …  
    192198         * @see https://html.spec.whatwg.org/#has-an-element-in-table-scope
    193199         *
     200         * @throws WP_HTML_Unsupported_Exception Always until this function is implemented.
     201         *
    194202         * @param string $tag_name Name of tag to check.
    195203         * @return bool Whether given element is in scope.
    196204         */
    197         public function has_element_in_table_scope( $tag_name ) {
     205        public function has_element_in_table_scope( $tag_name ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
    198206                throw new WP_HTML_Unsupported_Exception( 'Cannot process elements depending on table scope.' );
     207
     208                return false; // The linter requires this unreachable code until the function is implemented and can return.
    199209        }
    200210
    … …  
    205215         *
    206216         * @see https://html.spec.whatwg.org/#has-an-element-in-select-scope
     217         *
     218         * @throws WP_HTML_Unsupported_Exception Always until this function is implemented.
    207219         *
    208220         * @param string $tag_name Name of tag to check.
    209221         * @return bool Whether given element is in scope.
    210222         */
    211         public function has_element_in_select_scope( $tag_name ) {
     223        public function has_element_in_select_scope( $tag_name ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
    212224                throw new WP_HTML_Unsupported_Exception( 'Cannot process elements depending on select scope.' );
     225
     226                return false; // The linter requires this unreachable code until the function is implemented and can return.
    213227        }
    214228
    … …  
    220234         * @see https://html.spec.whatwg.org/#has-an-element-in-button-scope
    221235         *
    222          * @return bool
     236         * @return bool Whether a P is in BUTTON scope.
    223237         */
    224238        public function has_p_in_button_scope() {
    … …  
    321335         *
    322336         * To start with the most-recently added element and walk towards the top,
    323          * @see WP_HTML_Open_Elements::walk_up
     337         * see WP_HTML_Open_Elements::walk_up().
    324338         *
    325339         * @since 6.4.0
    … …  
    348362         *
    349363         * To start with the first added element and walk towards the bottom,
    350          * @see WP_HTML_Open_Elements::walk_down
     364         * see WP_HTML_Open_Elements::walk_down().
    351365         *
    352366         * @since 6.4.0

  • trunk/src/wp-includes/html-api/class-wp-html-processor.php

    r56331 r56363  
    1717 * the document. The HTML Processor should never break an HTML document.
    1818 *
    19  * While the {@see WP_HTML_Tag_Processor} is a valuable tool for modifying
     19 * While the `WP_HTML_Tag_Processor` is a valuable tool for modifying
    2020 * attributes on individual HTML tags, the HTML Processor is more capable
    2121 * and useful for the following operations:
    … …  
    4848 * Breadcrumbs represent the stack of open elements from the root
    4949 * of the document or fragment down to the currently-matched node,
    50  * if one is currently selected. Call {@see WP_HTML_Processor::get_breadcrumbs}
     50 * if one is currently selected. Call WP_HTML_Processor::get_breadcrumbs()
    5151 * to inspect the breadcrumbs for a matched tag.
    5252 *
    … …  
    122122 * @since 6.4.0
    123123 *
     124 * @see WP_HTML_Tag_Processor
    124125 * @see https://html.spec.whatwg.org/
    125126 */
    … …  
    233234         */
    234235        public static function createFragment( $html, $context = '<body>', $encoding = 'UTF-8' ) {
    235                 if ( '<body>' !== $context ) {
     236                if ( '<body>' !== $context || 'UTF-8' !== $encoding ) {
    236237                        return null;
    237238                }
    238239
    239                 $p = new self( $html, self::CONSTRUCTOR_UNLOCK_CODE );
     240                $p                        = new self( $html, self::CONSTRUCTOR_UNLOCK_CODE );
    240241                $p->state->context_node   = array( 'BODY', array() );
    241242                $p->state->insertion_mode = WP_HTML_Processor_State::INSERTION_MODE_IN_BODY;
    242243
    243244                // @TODO: Create "fake" bookmarks for non-existent but implied nodes.
    244                 $p->bookmarks['root-node'] = new WP_HTML_Span( 0, 0 );
     245                $p->bookmarks['root-node']    = new WP_HTML_Span( 0, 0 );
    245246                $p->bookmarks['context-node'] = new WP_HTML_Span( 0, 0 );
    246247
    … …  
    333334         * @since 6.4.0
    334335         *
    335          * @throws WP_HTML_Unsupported_Exception
     336         * @throws Exception When unable to allocate a bookmark for the next token in the input HTML document.
    336337         *
    337338         * @param array|string|null $query {
    … …  
    411412         * @since 6.4.0
    412413         *
    413          * @throws Exception
     414         * @throws Exception When unable to allocate a bookmark for the next token in the input HTML document.
    414415         *
    415416         * @see self::PROCESS_NEXT_NODE
    … …  
    497498         * @since 6.4.0
    498499         *
    499          * @throws WP_HTML_Unsupported_Exception
     500         * @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
    500501         *
    501502         * @see https://html.spec.whatwg.org/#parsing-main-inbody
    … …  
    673674         * @since 6.4.0
    674675         *
    675          * @throws Exception
     676         * @throws Exception When unable to allocate requested bookmark.
    676677         *
    677678         * @return string|false Name of created bookmark, or false if unable to create.
    … …  
    891892         * @since 6.4.0
    892893         *
    893          * @throws WP_HTML_Unsupported_Exception
     894         * @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
    894895         *
    895896         * @see https://html.spec.whatwg.org/#close-a-p-element
    … …  
    904905         *
    905906         * @since 6.4.0
    906          *
    907          * @throws WP_HTML_Unsupported_Exception
    908907         *
    909908         * @see https://html.spec.whatwg.org/#generate-implied-end-tags
    … …  
    929928         *
    930929         * See the HTML specification for an explanation why this is
    931          * different from {@see WP_HTML_Processor::generate_implied_end_tags}.
    932          *
    933          * @since 6.4.0
    934          *
     930         * different from generating end tags in the normal sense.
     931         *
     932         * @since 6.4.0
     933         *
     934         * @see WP_HTML_Processor::generate_implied_end_tags
    935935         * @see https://html.spec.whatwg.org/#generate-implied-end-tags
    936936         */
    … …  
    954954         * @since 6.4.0
    955955         *
    956          * @throws WP_HTML_Unsupported_Exception
     956         * @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
    957957         *
    958958         * @see https://html.spec.whatwg.org/#reconstruct-the-active-formatting-elements
    … …  
    971971                $last_entry = $this->state->active_formatting_elements->current_node();
    972972                if (
     973
    973974                        /*
    974975                         * > If the last (most recently added) entry in the list of active formatting elements is a marker;
    … …  
    996997         * @since 6.4.0
    997998         *
    998          * @throws WP_HTML_Unsupported_Exception
     999         * @throws WP_HTML_Unsupported_Exception When encountering unsupported HTML input.
    9991000         *
    10001001         * @see https://html.spec.whatwg.org/#adoption-agency-algorithm
    … …  
    12171218                        'XMP' === $tag_name ||
    12181219
    1219                         // MathML
     1220                        // MathML.
    12201221                        'MI' === $tag_name ||
    12211222                        'MO' === $tag_name ||
    … …  
    12251226                        'ANNOTATION-XML' === $tag_name ||
    12261227
    1227                         // SVG
     1228                        // SVG.
    12281229                        'FOREIGNOBJECT' === $tag_name ||
    12291230                        'DESC' === $tag_name ||
    … …  
    13081309         * Unlock code that must be passed into the constructor to create this class.
    13091310         *
    1310          * This class extends {@see WP_HTML_Tag_Processor}, which has a public class
     1311         * This class extends the WP_HTML_Tag_Processor, which has a public class
    13111312         * constructor. Therefore, it's not possible to have a private constructor here.
    13121313         *

  • trunk/src/wp-includes/html-api/class-wp-html-token.php

    r56274 r56363  
    3737         * Name of node; lowercase names such as "marker" are not HTML elements.
    3838         *
    39          * For HTML elements/tags this value should come from {@see WP_HTML_Processor::get_tag}.
     39         * For HTML elements/tags this value should come from WP_HTML_Processor::get_tag().
    4040         *
    4141         * @since 6.4.0
     42         *
     43         * @see WP_HTML_Processor::get_tag()
    4244         *
    4345         * @var string
Note: See TracChangeset for help on using the changeset viewer.