WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
05/24/2021 01:24:05 PM (4 years ago)
Author:
SergeyBiryukov
Message:

Docs: Some documentation and test improvements for WP_Theme_JSON and WP_Theme_JSON_Resolver classes:

  • Add missing @since tags.
  • Update some DocBlocks per the documentation standards.
  • Rename test files and classes per the naming conventions.
  • Fix some code alignment issues reported by WPCS.

Follow-up to [50959], [50960].

See #52991, #53175.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-wp-theme-json.php

    r50959 r50967  
    11<?php
    22/**
    3  * Process of structures that adhere to the theme.json schema.
     3 * WP_Theme_JSON class
    44 *
    55 * @package WordPress
     6 * @subpackage Theme
     7 * @since 5.8.0
    68 */
    79
    810/**
    9  * Class that encapsulates the processing of
    10  * structures that adhere to the theme.json spec.
     11 * Class that encapsulates the processing of structures that adhere to the theme.json spec.
    1112 *
    1213 * @access private
    … …  
    1718     * Container of data in theme.json format.
    1819     *
     20     * @since 5.8.0
    1921     * @var array
    2022     */
    … …  
    2527     * Shared among all instances so we only process it once.
    2628     *
     29     * @since 5.8.0
    2730     * @var array
    2831     */
    … …  
    6366     * Constructor.
    6467     *
     68     * @since 5.8.0
     69     *
    6570     * @param array $theme_json A structure that follows the theme.json schema.
    6671     */
    … …  
    7176        }
    7277
    73         $this->theme_json  = self::sanitize( $theme_json );
     78        $this->theme_json = self::sanitize( $theme_json );
    7479    }
    7580
    7681    /**
    7782     * Returns the allowed block names.
     83     *
     84     * @since 5.8.0
    7885     *
    7986     * @return array
    … …  
    9299     * Sanitizes the input according to the schemas.
    93100     *
     101     * @since 5.8.0
     102     *
    94103     * @param array $input Structure to sanitize.
    95      *
    96104     * @return array The sanitized output.
    97105     */
    … …  
    144152     * It is recursive and modifies the input in-place.
    145153     *
     154     * @since 5.8.0
     155     *
    146156     * @param array $tree Input to process.
    147157     * @param array $schema Schema to adhere to.
    148      *
    149158     * @return array Returns the modified $tree.
    150159     */
    … …  
    176185     * Example:
    177186     *
    178      * {
    179      *   'root': {
    180      *     'color': {
    181      *       'custom': true
     187     *     {
     188     *       'root': {
     189     *         'color': {
     190     *           'custom': true
     191     *         }
     192     *       },
     193     *       'core/paragraph': {
     194     *         'spacing': {
     195     *           'customPadding': true
     196     *         }
     197     *       }
    182198     *     }
    183      *   },
    184      *   'core/paragraph': {
    185      *     'spacing': {
    186      *       'customPadding': true
    187      *     }
    188      *   }
    189      * }
     199     *
     200     * @since 5.8.0
    190201     *
    191202     * @return array Settings per block.
    … …  
    202213     * Builds metadata for the setting nodes, which returns in the form of:
    203214     *
    204      * [
    205      *   [
    206      *     'path' => ['path', 'to', 'some', 'node' ]
    207      *   ],
    208      *   [
    209      *     'path' => [ 'path', 'to', 'other', 'node' ]
    210      *   ],
    211      * ]
     215     *     [
     216     *       [
     217     *         'path' => ['path', 'to', 'some', 'node' ]
     218     *       ],
     219     *       [
     220     *         'path' => [ 'path', 'to', 'other', 'node' ]
     221     *       ],
     222     *     ]
     223     *
     224     * @since 5.8.0
    212225     *
    213226     * @param array $theme_json The tree to extract setting nodes from.
    214      *
    215227     * @return array
    216228     */
    … …  
    243255     * Merge new incoming data.
    244256     *
     257     * @since 5.8.0
     258     *
    245259     * @param WP_Theme_JSON $incoming Data to merge.
    246260     */
    … …  
    249263        $this->theme_json = array_replace_recursive( $this->theme_json, $incoming_data );
    250264
    251         // The array_replace_recursive algorithm merges at the leaf level.
    252         // For leaf values that are arrays it will use the numeric indexes for replacement.
    253         // In those cases, what we want is to use the incoming value, if it exists.
    254         //
    255         // These are the cases that have array values at the leaf levels.
     265        /*
     266         * The array_replace_recursive algorithm merges at the leaf level.
     267         * For leaf values that are arrays it will use the numeric indexes for replacement.
     268         * In those cases, what we want is to use the incoming value, if it exists.
     269         *
     270         * These are the cases that have array values at the leaf levels.
     271         */
    256272        $properties   = array();
    257273        $properties[] = array( 'color', 'palette' );
    … …  
    278294     * Returns the raw data.
    279295     *
     296     * @since 5.8.0
     297     *
    280298     * @return array Raw data.
    281299     */
    … …  
    285303
    286304    /**
    287      *
    288305     * Transforms the given editor settings according the
    289306     * add_theme_support format to the theme.json format.
    290307     *
     308     * @since 5.8.0
     309     *
    291310     * @param array $settings Existing editor settings.
    292      *
    293311     * @return array Config that adheres to the theme.json schema.
    294312     */
    … …  
    365383        }
    366384
    367         // This allows to make the plugin work with WordPress 5.7 beta
    368         // as well as lower versions. The second check can be removed
    369         // as soon as the minimum WordPress version for the plugin
    370         // is bumped to 5.7.
     385        /*
     386         * This allows to make the plugin work with WordPress 5.8 beta
     387         * as well as lower versions. The second check can be removed
     388         * as soon as the minimum WordPress version for the plugin
     389         * is bumped to 5.8.
     390         */
    371391        if ( isset( $settings['enableCustomSpacing'] ) ) {
    372392            if ( ! isset( $theme_settings['settings']['spacing'] ) ) {
Note: See TracChangeset for help on using the changeset viewer.