WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
05/24/2021 01:24:05 PM (5 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.