Make WordPress Core

Changeset 56179


Ignore:
Timestamp:
07/09/2023 09:38:35 PM (16 months ago)
Author:
audrasjb
Message:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178].

Props costdev, audrasjb.
See #58459.

Location:
trunk/src/wp-includes
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/class-wp-theme-json-resolver.php

    r56157 r56179  
    359359                null === _wp_array_get( $config, array( 'styles', 'blocks', $block_name, 'spacing', 'blockGap' ), null )
    360360            ) {
    361                 // Ensure an empty placeholder value exists for the block, if it provides a default blockGap value.
    362                 // The real blockGap value to be used will be determined when the styles are rendered for output.
     361                /*
     362                 * Ensure an empty placeholder value exists for the block, if it provides a default blockGap value.
     363                 * The real blockGap value to be used will be determined when the styles are rendered for output.
     364                 */
    363365                $config['styles']['blocks'][ $block_name ]['spacing']['blockGap'] = null;
    364366            }
     
    513515            }
    514516
    515             // Very important to verify that the flag isGlobalStylesUserThemeJSON is true.
    516             // If it's not true then the content was not escaped and is not safe.
     517            /*
     518             * Very important to verify that the flag isGlobalStylesUserThemeJSON is true.
     519             * If it's not true then the content was not escaped and is not safe.
     520             */
    517521            if (
    518522                is_array( $decoded_data ) &&
  • trunk/src/wp-includes/class-wp-theme-json.php

    r56101 r56179  
    546546        $class_name = '';
    547547
    548         // TODO: Replace array_key_exists() with isset() check once WordPress drops
    549         // support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     548        /*
     549         * TODO: Replace array_key_exists() with isset() check once WordPress drops
     550         * support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     551         */
    550552        if ( array_key_exists( $element, static::__EXPERIMENTAL_ELEMENT_CLASS_NAMES ) ) {
    551553            $class_name = static::__EXPERIMENTAL_ELEMENT_CLASS_NAMES[ $element ];
     
    672674    protected static function do_opt_in_into_settings( &$context ) {
    673675        foreach ( static::APPEARANCE_TOOLS_OPT_INS as $path ) {
    674             // Use "unset prop" as a marker instead of "null" because
    675             // "null" can be a valid value for some props (e.g. blockGap).
     676            /*
     677             * Use "unset prop" as a marker instead of "null" because
     678             * "null" can be a valid value for some props (e.g. blockGap).
     679             */
    676680            if ( 'unset prop' === _wp_array_get( $context, $path, 'unset prop' ) ) {
    677681                _wp_array_set( $context, $path, true );
     
    737741            $schema_styles_elements[ $element ] = $styles_non_top_level;
    738742
    739             // TODO: Replace array_key_exists() with isset() check once WordPress drops
    740             // support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     743            /*
     744             * TODO: Replace array_key_exists() with isset() check once WordPress drops
     745             * support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     746             */
    741747            if ( array_key_exists( $element, static::VALID_ELEMENT_PSEUDO_SELECTORS ) ) {
    742748                foreach ( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $element ] as $pseudo_selector ) {
     
    10841090                $root_selector = $options['root_selector'];
    10851091            }
    1086             // Base layout styles are provided as part of `styles`, so only output separately if explicitly requested.
    1087             // For backwards compatibility, the Columns block is explicitly included, to support a different default gap value.
     1092            /*
     1093             * Base layout styles are provided as part of `styles`, so only output separately if explicitly requested.
     1094             * For backwards compatibility, the Columns block is explicitly included, to support a different default gap value.
     1095             */
    10881096            $base_styles_nodes = array(
    10891097                array(
     
    12761284        $layout_selector_pattern  = '/^[a-zA-Z0-9\-\.\ *+>:\(\)]*$/'; // Allow alphanumeric classnames, spaces, wildcard, sibling, child combinator and pseudo class selectors.
    12771285
    1278         // Gap styles will only be output if the theme has block gap support, or supports a fallback gap.
    1279         // Default layout gap styles will be skipped for themes that do not explicitly opt-in to blockGap with a `true` or `false` value.
     1286        /*
     1287         * Gap styles will only be output if the theme has block gap support, or supports a fallback gap.
     1288         * Default layout gap styles will be skipped for themes that do not explicitly opt-in to blockGap with a `true` or `false` value.
     1289         */
    12801290        if ( $has_block_gap_support || $has_fallback_gap_support ) {
    12811291            $block_gap_value = null;
     
    15551565    protected static function compute_preset_classes( $settings, $selector, $origins ) {
    15561566        if ( static::ROOT_BLOCK_SELECTOR === $selector ) {
    1557             // Classes at the global level do not need any CSS prefixed,
    1558             // and we don't want to increase its specificity.
     1567            /*
     1568             * Classes at the global level do not need any CSS prefixed,
     1569             * and we don't want to increase its specificity.
     1570             */
    15591571            $selector = '';
    15601572        }
     
    18981910                continue;
    18991911            }
    1900             // Root-level padding styles don't currently support strings with CSS shorthand values.
    1901             // This may change: https://github.com/WordPress/gutenberg/issues/40132.
     1912            /*
     1913             * Root-level padding styles don't currently support strings with CSS shorthand values.
     1914             * This may change: https://github.com/WordPress/gutenberg/issues/40132.
     1915             */
    19021916            if ( '--wp--style--root--padding' === $css_property && is_string( $value ) ) {
    19031917                continue;
     
    19081922            }
    19091923
    1910             // Look up protected properties, keyed by value path.
    1911             // Skip protected properties that are explicitly set to `null`.
     1924            /*
     1925             * Look up protected properties, keyed by value path.
     1926             * Skip protected properties that are explicitly set to `null`.
     1927             */
    19121928            if ( is_array( $value_path ) ) {
    19131929                $path_string = implode( '.', $value_path );
    19141930                if (
    1915                     // TODO: Replace array_key_exists() with isset() check once WordPress drops
    1916                     // support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     1931                    /*
     1932                     * TODO: Replace array_key_exists() with isset() check once WordPress drops
     1933                     * support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     1934                     */
    19171935                    array_key_exists( $path_string, static::PROTECTED_PROPERTIES ) &&
    19181936                    _wp_array_get( $settings, static::PROTECTED_PROPERTIES[ $path_string ], null ) === null
     
    21192137                );
    21202138
    2121                 // Handle any pseudo selectors for the element.
    2122                 // TODO: Replace array_key_exists() with isset() check once WordPress drops
    2123                 // support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     2139                /*
     2140                 * Handle any pseudo selectors for the element.
     2141                 * TODO: Replace array_key_exists() with isset() check once WordPress drops
     2142                 * support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     2143                 */
    21242144                if ( array_key_exists( $element, static::VALID_ELEMENT_PSEUDO_SELECTORS ) ) {
    21252145                    foreach ( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $element ] as $pseudo_selector ) {
     
    22712291                    );
    22722292
    2273                     // Handle any pseudo selectors for the element.
    2274                     // TODO: Replace array_key_exists() with isset() check once WordPress drops
    2275                     // support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     2293                    /*
     2294                     * Handle any pseudo selectors for the element.
     2295                     * TODO: Replace array_key_exists() with isset() check once WordPress drops
     2296                     * support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     2297                     */
    22762298                    if ( array_key_exists( $element, static::VALID_ELEMENT_PSEUDO_SELECTORS ) ) {
    22772299                        foreach ( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $element ] as $pseudo_selector ) {
     
    23522374        $element_pseudo_allowed = array();
    23532375
    2354         // TODO: Replace array_key_exists() with isset() check once WordPress drops
    2355         // support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     2376        /*
     2377         * TODO: Replace array_key_exists() with isset() check once WordPress drops
     2378         * support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     2379         */
    23562380        if ( array_key_exists( $current_element, static::VALID_ELEMENT_PSEUDO_SELECTORS ) ) {
    23572381            $element_pseudo_allowed = static::VALID_ELEMENT_PSEUDO_SELECTORS[ $current_element ];
     
    23792403         */
    23802404        if ( $pseudo_selector && isset( $node[ $pseudo_selector ] ) &&
    2381             // TODO: Replace array_key_exists() with isset() check once WordPress drops
    2382             // support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     2405            /*
     2406             * TODO: Replace array_key_exists() with isset() check once WordPress drops
     2407             * support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
     2408             */
    23832409            array_key_exists( $current_element, static::VALID_ELEMENT_PSEUDO_SELECTORS )
    23842410            && in_array( $pseudo_selector, static::VALID_ELEMENT_PSEUDO_SELECTORS[ $current_element ], true )
     
    28702896             * $output is stripped of pseudo selectors. Re-add and process them
    28712897             * or insecure styles here.
     2898             *
     2899             * TODO: Replace array_key_exists() with isset() check once WordPress drops
     2900             * support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
    28722901             */
    2873             // TODO: Replace array_key_exists() with isset() check once WordPress drops
    2874             // support for PHP 5.6. See https://core.trac.wordpress.org/ticket/57067.
    28752902            if ( array_key_exists( $current_element, static::VALID_ELEMENT_PSEUDO_SELECTORS ) ) {
    28762903                foreach ( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $current_element ] as $pseudo_selector ) {
     
    29933020                $path = static::PROPERTIES_METADATA[ $declaration['name'] ];
    29943021
    2995                 // Check the value isn't an array before adding so as to not
    2996                 // double up shorthand and longhand styles.
     3022                /*
     3023                 * Check the value isn't an array before adding so as to not
     3024                 * double up shorthand and longhand styles.
     3025                 */
    29973026                $value = _wp_array_get( $input, $path, array() );
    29983027                if ( ! is_array( $value ) ) {
     
    32373266        }
    32383267
    3239         // If all of the static::APPEARANCE_TOOLS_OPT_INS are true,
    3240         // this code unsets them and sets 'appearanceTools' instead.
     3268        /*
     3269         * If all of the static::APPEARANCE_TOOLS_OPT_INS are true,
     3270         * this code unsets them and sets 'appearanceTools' instead.
     3271         */
    32413272        foreach ( $nodes as $node ) {
    32423273            $all_opt_ins_are_set = true;
     
    32463277                    $full_path[] = $opt_in_path_item;
    32473278                }
    3248                 // Use "unset prop" as a marker instead of "null" because
    3249                 // "null" can be a valid value for some props (e.g. blockGap).
     3279                /*
     3280                 * Use "unset prop" as a marker instead of "null" because
     3281                 * "null" can be a valid value for some props (e.g. blockGap).
     3282                 */
    32503283                $opt_in_value = _wp_array_get( $output, $full_path, 'unset prop' );
    32513284                if ( 'unset prop' === $opt_in_value ) {
     
    32643297                        $full_path[] = $opt_in_path_item;
    32653298                    }
    3266                     // Use "unset prop" as a marker instead of "null" because
    3267                     // "null" can be a valid value for some props (e.g. blockGap).
     3299                    /*
     3300                     * Use "unset prop" as a marker instead of "null" because
     3301                     * "null" can be a valid value for some props (e.g. blockGap).
     3302                     */
    32683303                    $opt_in_value = _wp_array_get( $output, $full_path, 'unset prop' );
    32693304                    if ( true !== $opt_in_value ) {
     
    32713306                    }
    32723307
    3273                     // The following could be improved to be path independent.
    3274                     // At the moment it relies on a couple of assumptions:
    3275                     //
    3276                     // - all opt-ins having a path of size 2.
    3277                     // - there's two sources of settings: the top-level and the block-level.
     3308                    /*
     3309                     * The following could be improved to be path independent.
     3310                     * At the moment it relies on a couple of assumptions:
     3311                     *
     3312                     * - all opt-ins having a path of size 2.
     3313                     * - there's two sources of settings: the top-level and the block-level.
     3314                     */
    32783315                    if (
    32793316                        ( 1 === count( $node['path'] ) ) &&
     
    35113548     */
    35123549    protected static function get_block_element_selectors( $root_selector ) {
    3513         // Assign defaults, then override those that the block sets by itself.
    3514         // If the block selector is compounded, will append the element to each
    3515         // individual block selector.
    3516         $block_selectors   = explode( ',', $root_selector );
    3517         $element_selectors = array();
    3518 
     3550        /*
     3551         * Assign defaults, then override those that the block sets by itself.
     3552         * If the block selector is compounded, will append the element to each
     3553         * individual block selector.
     3554         * $block_selectors   = explode( ',', $root_selector );
     3555         * $element_selectors = array();
     3556         */
    35193557        foreach ( static::ELEMENTS as $el_name => $el_selector ) {
    35203558            $element_selector = array();
     
    35553593
    35563594        foreach ( $metadata['selectors'] as $feature => $feature_selectors ) {
    3557             // Skip if this is the block's root selector or the block doesn't
    3558             // have any styles for the feature.
     3595            /*
     3596             * Skip if this is the block's root selector or the block doesn't
     3597             * have any styles for the feature.
     3598             */
    35593599            if ( 'root' === $feature || empty( $node[ $feature ] ) ) {
    35603600                continue;
     
    35673607                    }
    35683608
    3569                     // Create temporary node containing only the subfeature data
    3570                     // to leverage existing `compute_style_properties` function.
     3609                    /*
     3610                     * Create temporary node containing only the subfeature data
     3611                     * to leverage existing `compute_style_properties` function.
     3612                     */
    35713613                    $subfeature_node = array(
    35723614                        $feature => array(
     
    35873629                    }
    35883630
    3589                     // Remove the subfeature from the block's node now its
    3590                     // styles will be included under its own selector not the
    3591                     // block's.
     3631                    /*
     3632                     * Remove the subfeature from the block's node now its
     3633                     * styles will be included under its own selector not the
     3634                     * block's.
     3635                     */
    35923636                    unset( $node[ $feature ][ $subfeature ] );
    35933637                }
    35943638            }
    35953639
    3596             // Now subfeatures have been processed and removed we can process
    3597             // feature root selector or simple string selector.
     3640            /*
     3641             * Now subfeatures have been processed and removed we can process
     3642             * feature root selector or simple string selector.
     3643             */
    35983644            if (
    35993645                is_string( $feature_selectors ) ||
     
    36023648                $feature_selector = is_string( $feature_selectors ) ? $feature_selectors : $feature_selectors['root'];
    36033649
    3604                 // Create temporary node containing only the feature data
    3605                 // to leverage existing `compute_style_properties` function.
     3650                /*
     3651                 * Create temporary node containing only the feature data
     3652                 * to leverage existing `compute_style_properties` function.
     3653                 */
    36063654                $feature_node = array( $feature => $node[ $feature ] );
    36073655
     
    36093657                $new_declarations = static::compute_style_properties( $feature_node, $settings, null, $this->theme_json );
    36103658
    3611                 // Merge new declarations with any that already exist for
    3612                 // the feature selector. This may occur when multiple block
    3613                 // support features use the same custom selector.
     3659                /*
     3660                 * Merge new declarations with any that already exist for
     3661                 * the feature selector. This may occur when multiple block
     3662                 * support features use the same custom selector.
     3663                 */
    36143664                if ( isset( $declarations[ $feature_selector ] ) ) {
    36153665                    foreach ( $new_declarations as $new_declaration ) {
     
    36203670                }
    36213671
    3622                 // Remove the feature from the block's node now its styles
    3623                 // will be included under its own selector not the block's.
     3672                /*
     3673                 * Remove the feature from the block's node now its styles
     3674                 * will be included under its own selector not the block's.
     3675                 */
    36243676                unset( $node[ $feature ] );
    36253677            }
Note: See TracChangeset for help on using the changeset viewer.