From 19ea4bd412f43cd22fd9d8bdfead311785dbe499 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Mon, 24 May 2021 13:25:56 +0000 Subject: [PATCH] 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. Built from https://develop.svn.wordpress.org/trunk@50967 git-svn-id: http://core.svn.wordpress.org/trunk@50576 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/class-wp-theme-json-resolver.php | 153 ++++++++++--------- wp-includes/class-wp-theme-json.php | 94 +++++++----- wp-includes/version.php | 2 +- 3 files changed, 139 insertions(+), 110 deletions(-) diff --git a/wp-includes/class-wp-theme-json-resolver.php b/wp-includes/class-wp-theme-json-resolver.php index 87e2fa4bf1..db0747bb84 100644 --- a/wp-includes/class-wp-theme-json-resolver.php +++ b/wp-includes/class-wp-theme-json-resolver.php @@ -1,14 +1,15 @@ [ - * 'path' => [ 'settings', '*', 'typography', 'fontSizes' ], - * 'key' => 'name', - * 'context' => 'Font size name' - * ], - * 1 => [ - * 'path' => [ 'settings', '*', 'typography', 'fontStyles' ], - * 'key' => 'name', - * 'context' => 'Font style name' - * ] - * ] + * [ + * 0 => [ + * 'path' => [ 'settings', '*', 'typography', 'fontSizes' ], + * 'key' => 'name', + * 'context' => 'Font size name' + * ], + * 1 => [ + * 'path' => [ 'settings', '*', 'typography', 'fontStyles' ], + * 'key' => 'name', + * 'context' => 'Font style name' + * ] + * ] + * + * @since 5.8.0 * * @param array $i18n_partial A tree that follows the format of i18n-theme.json. * @param array $current_path Keeps track of the path as we walk down the given tree. - * * @return array A linear array containing the paths to translate. */ private static function extract_paths_to_translate( $i18n_partial, $current_path = array() ) { @@ -134,7 +140,9 @@ class WP_Theme_JSON_Resolver { /** * Returns a data structure used in theme.json translation. * - * @return array An array of theme.json fields that are translatable and the keys that are translatable + * @since 5.8.0 + * + * @return array An array of theme.json fields that are translatable and the keys that are translatable. */ public static function get_fields_to_translate() { if ( null === self::$theme_json_i18n ) { @@ -147,11 +155,12 @@ class WP_Theme_JSON_Resolver { /** * Translates a chunk of the loaded theme.json structure. * + * @since 5.8.0 + * * @param array $array_to_translate The chunk of theme.json to translate. * @param string $key The key of the field that contains the string to translate. * @param string $context The context to apply in the translation call. * @param string $domain Text domain. Unique identifier for retrieving translated strings. - * * @return array Returns the modified $theme_json chunk. */ private static function translate_theme_json_chunk( array $array_to_translate, $key, $context, $domain ) { @@ -168,14 +177,14 @@ class WP_Theme_JSON_Resolver { } /** - * Given a theme.json structure modifies it in place - * to update certain values by its translated strings - * according to the language set by the user. + * Given a theme.json structure modifies it in place to update certain values + * by its translated strings according to the language set by the user. + * + * @since 5.8.0 * * @param array $theme_json The theme.json to translate. - * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. - * Default 'default'. - * + * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. + * Default 'default'. * @return array Returns the modified $theme_json_structure. */ private static function translate( $theme_json, $domain = 'default' ) { @@ -228,6 +237,8 @@ class WP_Theme_JSON_Resolver { /** * Return core's origin config. * + * @since 5.8.0 + * * @return WP_Theme_JSON Entity that holds core data. */ public static function get_core_data() { @@ -245,16 +256,16 @@ class WP_Theme_JSON_Resolver { /** * Returns the theme's data. * - * Data from theme.json can be augmented via the - * $theme_support_data variable. This is useful, for example, - * to backfill the gaps in theme.json that a theme has declared - * via add_theme_supports. + * Data from theme.json can be augmented via the $theme_support_data variable. + * This is useful, for example, to backfill the gaps in theme.json that a theme + * has declared via add_theme_supports. * - * Note that if the same data is present in theme.json - * and in $theme_support_data, the theme.json's is not overwritten. + * Note that if the same data is present in theme.json and in $theme_support_data, + * the theme.json's is not overwritten. + * + * @since 5.8.0 * * @param array $theme_support_data Theme support data in theme.json format. - * * @return WP_Theme_JSON Entity that holds theme data. */ public static function get_theme_data( $theme_support_data = array() ) { @@ -279,22 +290,19 @@ class WP_Theme_JSON_Resolver { } /** - * There are different sources of data for a site: - * core and theme. + * There are different sources of data for a site: core and theme. * - * While the getters {@link get_core_data}, - * {@link get_theme_data} return the raw data - * from the respective origins, this method merges them - * all together. + * While the getters {@link get_core_data}, {@link get_theme_data} return the raw data + * from the respective origins, this method merges them all together. * * If the same piece of data is declared in different origins (core and theme), - * the last origin overrides the previous. For example, - * if core disables custom colors but a theme enables them, - * the theme config wins. + * the last origin overrides the previous. For example, if core disables custom colors + * but a theme enables them, the theme config wins. + * + * @since 5.8.0 * * @param array $settings Existing block editor settings. * Empty array by default. - * * @return WP_Theme_JSON */ public static function get_merged_data( $settings = array() ) { @@ -321,24 +329,23 @@ class WP_Theme_JSON_Resolver { } /** - * Builds the path to the given file - * and checks that it is readable. + * Builds the path to the given file and checks that it is readable. * - * If it isn't, returns an empty string, - * otherwise returns the whole file path. + * If it isn't, returns an empty string, otherwise returns the whole file path. + * + * @since 5.8.0 * * @param string $file_name Name of the file. * @return string The whole file path or empty if the file doesn't exist. */ private static function get_file_path_from_theme( $file_name ) { - // This used to be a locate_template call. - // However, that method proved problematic - // due to its use of constants (STYLESHEETPATH) - // that threw errors in some scenarios. - // - // When the theme.json merge algorithm properly supports - // child themes, this should also fallback - // to the template path, as locate_template did. + /* + * This used to be a locate_template call. However, that method proved problematic + * due to its use of constants (STYLESHEETPATH) that threw errors in some scenarios. + * + * When the theme.json merge algorithm properly supports child themes, + * this should also fall back to the template path, as locate_template did. + */ $located = ''; $candidate = get_stylesheet_directory() . '/' . $file_name; if ( is_readable( $candidate ) ) { @@ -349,12 +356,14 @@ class WP_Theme_JSON_Resolver { /** * Cleans the cached data so it can be recalculated. + * + * @since 5.8.0 */ public static function clean_cached_data() { - self::$core = null; - self::$theme = null; - self::$theme_has_support = null; - self::$theme_json_i18n = null; + self::$core = null; + self::$theme = null; + self::$theme_has_support = null; + self::$theme_json_i18n = null; } } diff --git a/wp-includes/class-wp-theme-json.php b/wp-includes/class-wp-theme-json.php index b78f7c9be4..0cb5a845c5 100644 --- a/wp-includes/class-wp-theme-json.php +++ b/wp-includes/class-wp-theme-json.php @@ -1,13 +1,14 @@ theme_json = self::sanitize( $theme_json ); + $this->theme_json = self::sanitize( $theme_json ); } /** * Returns the allowed block names. * + * @since 5.8.0 + * * @return array */ private static function get_allowed_block_names() { @@ -91,8 +98,9 @@ class WP_Theme_JSON { /** * Sanitizes the input according to the schemas. * - * @param array $input Structure to sanitize. + * @since 5.8.0 * + * @param array $input Structure to sanitize. * @return array The sanitized output. */ private static function sanitize( $input ) { @@ -143,9 +151,10 @@ class WP_Theme_JSON { * * It is recursive and modifies the input in-place. * + * @since 5.8.0 + * * @param array $tree Input to process. * @param array $schema Schema to adhere to. - * * @return array Returns the modified $tree. */ private static function remove_keys_not_in_schema( $tree, $schema ) { @@ -175,18 +184,20 @@ class WP_Theme_JSON { * * Example: * - * { - * 'root': { - * 'color': { - * 'custom': true + * { + * 'root': { + * 'color': { + * 'custom': true + * } + * }, + * 'core/paragraph': { + * 'spacing': { + * 'customPadding': true + * } + * } * } - * }, - * 'core/paragraph': { - * 'spacing': { - * 'customPadding': true - * } - * } - * } + * + * @since 5.8.0 * * @return array Settings per block. */ @@ -201,17 +212,18 @@ class WP_Theme_JSON { /** * Builds metadata for the setting nodes, which returns in the form of: * - * [ - * [ - * 'path' => ['path', 'to', 'some', 'node' ] - * ], - * [ - * 'path' => [ 'path', 'to', 'other', 'node' ] - * ], - * ] + * [ + * [ + * 'path' => ['path', 'to', 'some', 'node' ] + * ], + * [ + * 'path' => [ 'path', 'to', 'other', 'node' ] + * ], + * ] + * + * @since 5.8.0 * * @param array $theme_json The tree to extract setting nodes from. - * * @return array */ private static function get_setting_nodes( $theme_json ) { @@ -242,17 +254,21 @@ class WP_Theme_JSON { /** * Merge new incoming data. * + * @since 5.8.0 + * * @param WP_Theme_JSON $incoming Data to merge. */ public function merge( $incoming ) { $incoming_data = $incoming->get_raw_data(); $this->theme_json = array_replace_recursive( $this->theme_json, $incoming_data ); - // The array_replace_recursive algorithm merges at the leaf level. - // For leaf values that are arrays it will use the numeric indexes for replacement. - // In those cases, what we want is to use the incoming value, if it exists. - // - // These are the cases that have array values at the leaf levels. + /* + * The array_replace_recursive algorithm merges at the leaf level. + * For leaf values that are arrays it will use the numeric indexes for replacement. + * In those cases, what we want is to use the incoming value, if it exists. + * + * These are the cases that have array values at the leaf levels. + */ $properties = array(); $properties[] = array( 'color', 'palette' ); $properties[] = array( 'color', 'gradients' ); @@ -277,6 +293,8 @@ class WP_Theme_JSON { /** * Returns the raw data. * + * @since 5.8.0 + * * @return array Raw data. */ public function get_raw_data() { @@ -284,12 +302,12 @@ class WP_Theme_JSON { } /** - * * Transforms the given editor settings according the * add_theme_support format to the theme.json format. * - * @param array $settings Existing editor settings. + * @since 5.8.0 * + * @param array $settings Existing editor settings. * @return array Config that adheres to the theme.json schema. */ public static function get_from_editor_settings( $settings ) { @@ -364,10 +382,12 @@ class WP_Theme_JSON { $theme_settings['settings']['typography']['fontSizes'] = $font_sizes; } - // This allows to make the plugin work with WordPress 5.7 beta - // as well as lower versions. The second check can be removed - // as soon as the minimum WordPress version for the plugin - // is bumped to 5.7. + /* + * This allows to make the plugin work with WordPress 5.8 beta + * as well as lower versions. The second check can be removed + * as soon as the minimum WordPress version for the plugin + * is bumped to 5.8. + */ if ( isset( $settings['enableCustomSpacing'] ) ) { if ( ! isset( $theme_settings['settings']['spacing'] ) ) { $theme_settings['settings']['spacing'] = array(); diff --git a/wp-includes/version.php b/wp-includes/version.php index 5d89dd1349..99060dbb45 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @global string $wp_version */ -$wp_version = '5.8-alpha-50966'; +$wp_version = '5.8-alpha-50967'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.