From 7a343e478e12d78bb47e13c831c67446253de494 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Wed, 3 May 2023 23:57:18 +0000 Subject: [PATCH] Docs: Correct and improve inline docs relating to the style engine. See #57840 Built from https://develop.svn.wordpress.org/trunk@55719 git-svn-id: http://core.svn.wordpress.org/trunk@55231 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/style-engine.php | 29 ++++--- ...class-wp-style-engine-css-declarations.php | 21 ++--- .../class-wp-style-engine-css-rule.php | 9 +- .../class-wp-style-engine-css-rules-store.php | 6 +- .../class-wp-style-engine-processor.php | 3 - .../style-engine/class-wp-style-engine.php | 84 ++++++++++--------- wp-includes/version.php | 2 +- 7 files changed, 71 insertions(+), 83 deletions(-) diff --git a/wp-includes/style-engine.php b/wp-includes/style-engine.php index 1a572e4583..377f1a1b68 100644 --- a/wp-includes/style-engine.php +++ b/wp-includes/style-engine.php @@ -10,7 +10,6 @@ * @since 6.1.0 */ - /** * Global public interface method to generate styles from a single style object, e.g., * the value of a block's attributes.style object or the top level styles in theme.json. @@ -19,8 +18,11 @@ * * Example usage: * - * $styles = wp_style_engine_get_styles( array( 'color' => array( 'text' => '#cccccc' ) ) ); - * // Returns `array( 'css' => 'color: #cccccc', 'declarations' => array( 'color' => '#cccccc' ), 'classnames' => 'has-color' )`. + * $styles = wp_style_engine_get_styles( array( 'color' => array( 'text' => '#cccccc' ) ) ); + * + * Returns: + * + * array( 'css' => 'color: #cccccc', 'declarations' => array( 'color' => '#cccccc' ), 'classnames' => 'has-color' ) * * @access public * @since 6.1.0 @@ -31,14 +33,13 @@ * * @type string|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is `null`. * When set, the style engine will attempt to store the CSS rules, where a selector is also passed. - * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset||`, to var( --wp--preset--* ) values. Default `false`. + * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset||`, to `var( --wp--preset--* )` values. Default `false`. * @type string $selector Optional. When a selector is passed, the value of `$css` in the return value will comprise a full CSS rule `$selector { ...$css_declarations }`, * otherwise, the value will be a concatenated string of CSS declarations. * } - * * @return array { * @type string $css A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag. - * @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ). + * @type string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. * @type string $classnames Classnames separated by a space. * } */ @@ -74,12 +75,16 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) { /** * Returns compiled CSS from a collection of selectors and declarations. - * Useful for returning a compiled stylesheet from any collection of CSS selector + declarations. + * Useful for returning a compiled stylesheet from any collection of CSS selector + declarations. * * Example usage: - * $css_rules = array( array( 'selector' => '.elephant-are-cool', 'declarations' => array( 'color' => 'gray', 'width' => '3em' ) ) ); - * $css = wp_style_engine_get_stylesheet_from_css_rules( $css_rules ); - * // Returns `.elephant-are-cool{color:gray;width:3em}`. + * + * $css_rules = array( array( 'selector' => '.elephant-are-cool', 'declarations' => array( 'color' => 'gray', 'width' => '3em' ) ) ); + * $css = wp_style_engine_get_stylesheet_from_css_rules( $css_rules ); + * + * Returns: + * + * .elephant-are-cool{color:gray;width:3em} * * @since 6.1.0 * @@ -88,7 +93,7 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) { * * @type array ...$0 { * @type string $selector A CSS selector. - * @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ). + * @type string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. * } * } * @param array $options { @@ -99,7 +104,6 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) { * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`. * @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined. * } - * * @return string A string of compiled CSS declarations, or empty string. */ function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = array() ) { @@ -146,7 +150,6 @@ function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = a * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`. * @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined. * } - * * @return string A compiled CSS string. */ function wp_style_engine_get_stylesheet_from_context( $context, $options = array() ) { diff --git a/wp-includes/style-engine/class-wp-style-engine-css-declarations.php b/wp-includes/style-engine/class-wp-style-engine-css-declarations.php index 23efd6a40c..7352f10219 100644 --- a/wp-includes/style-engine/class-wp-style-engine-css-declarations.php +++ b/wp-includes/style-engine/class-wp-style-engine-css-declarations.php @@ -24,7 +24,7 @@ class WP_Style_Engine_CSS_Declarations { * * @since 6.1.0 * - * @var array + * @var string[] */ protected $declarations = array(); @@ -36,7 +36,7 @@ class WP_Style_Engine_CSS_Declarations { * * @since 6.1.0 * - * @param string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ). + * @param string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. */ public function __construct( $declarations = array() ) { $this->add_declarations( $declarations ); @@ -49,7 +49,6 @@ class WP_Style_Engine_CSS_Declarations { * * @param string $property The CSS property. * @param string $value The CSS value. - * * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods. */ public function add_declaration( $property, $value ) { @@ -78,7 +77,6 @@ class WP_Style_Engine_CSS_Declarations { * @since 6.1.0 * * @param string $property The CSS property. - * * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods. */ public function remove_declaration( $property ) { @@ -91,8 +89,7 @@ class WP_Style_Engine_CSS_Declarations { * * @since 6.1.0 * - * @param array $declarations An array of declarations. - * + * @param string[] $declarations An array of declarations. * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods. */ public function add_declarations( $declarations ) { @@ -107,8 +104,7 @@ class WP_Style_Engine_CSS_Declarations { * * @since 6.1.0 * - * @param array $properties An array of properties. - * + * @param string[] $properties An array of properties. * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods. */ public function remove_declarations( $properties = array() ) { @@ -123,7 +119,7 @@ class WP_Style_Engine_CSS_Declarations { * * @since 6.1.0 * - * @return array + * @return string[] The declarations array. */ public function get_declarations() { return $this->declarations; @@ -137,7 +133,6 @@ class WP_Style_Engine_CSS_Declarations { * @param string $property The CSS property. * @param string $value The value to be filtered. * @param string $spacer The spacer between the colon and the value. Defaults to an empty string. - * * @return string The filtered declaration or an empty string. */ protected static function filter_declaration( $property, $value, $spacer = '' ) { @@ -153,9 +148,8 @@ class WP_Style_Engine_CSS_Declarations { * * @since 6.1.0 * - * @param bool $should_prettify Whether to add spacing, new lines and indents. - * @param number $indent_count The number of tab indents to apply to the rule. Applies if `prettify` is `true`. - * + * @param bool $should_prettify Whether to add spacing, new lines and indents. + * @param int $indent_count The number of tab indents to apply to the rule. Applies if `prettify` is `true`. * @return string The CSS declarations. */ public function get_declarations_string( $should_prettify = false, $indent_count = 0 ) { @@ -181,7 +175,6 @@ class WP_Style_Engine_CSS_Declarations { * @since 6.1.0 * * @param string $property The CSS property. - * * @return string The sanitized property name. */ protected function sanitize_property( $property ) { diff --git a/wp-includes/style-engine/class-wp-style-engine-css-rule.php b/wp-includes/style-engine/class-wp-style-engine-css-rule.php index 53225d7d65..bec1170bb9 100644 --- a/wp-includes/style-engine/class-wp-style-engine-css-rule.php +++ b/wp-includes/style-engine/class-wp-style-engine-css-rule.php @@ -43,7 +43,7 @@ class WP_Style_Engine_CSS_Rule { * @since 6.1.0 * * @param string $selector The CSS selector. - * @param string[]|WP_Style_Engine_CSS_Declarations $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ), + * @param string[]|WP_Style_Engine_CSS_Declarations $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`, * or a WP_Style_Engine_CSS_Declarations object. */ public function __construct( $selector = '', $declarations = array() ) { @@ -57,7 +57,6 @@ class WP_Style_Engine_CSS_Rule { * @since 6.1.0 * * @param string $selector The CSS selector. - * * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods. */ public function set_selector( $selector ) { @@ -72,7 +71,6 @@ class WP_Style_Engine_CSS_Rule { * * @param array|WP_Style_Engine_CSS_Declarations $declarations An array of declarations (property => value pairs), * or a WP_Style_Engine_CSS_Declarations object. - * * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods. */ public function add_declarations( $declarations ) { @@ -118,9 +116,8 @@ class WP_Style_Engine_CSS_Rule { * * @since 6.1.0 * - * @param bool $should_prettify Whether to add spacing, new lines and indents. - * @param number $indent_count The number of tab indents to apply to the rule. Applies if `prettify` is `true`. - * + * @param bool $should_prettify Whether to add spacing, new lines and indents. + * @param int $indent_count The number of tab indents to apply to the rule. Applies if `prettify` is `true`. * @return string */ public function get_css( $should_prettify = false, $indent_count = 0 ) { diff --git a/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php b/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php index 235fe53e92..55141977a1 100644 --- a/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php +++ b/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php @@ -51,7 +51,6 @@ class WP_Style_Engine_CSS_Rules_Store { * @since 6.1.0 * * @param string $store_name The name of the store. - * * @return WP_Style_Engine_CSS_Rules_Store|void */ public static function get_store( $store_name = 'default' ) { @@ -94,7 +93,6 @@ class WP_Style_Engine_CSS_Rules_Store { * @since 6.1.0 * * @param string $name The store name. - * * @return void */ public function set_name( $name ) { @@ -130,8 +128,7 @@ class WP_Style_Engine_CSS_Rules_Store { * @since 6.1.0 * * @param string $selector The CSS selector. - * - * @return WP_Style_Engine_CSS_Rule|void Returns a WP_Style_Engine_CSS_Rule object, or null if the selector is empty. + * @return WP_Style_Engine_CSS_Rule|void Returns a WP_Style_Engine_CSS_Rule object, or void if the selector is empty. */ public function add_rule( $selector ) { $selector = trim( $selector ); @@ -155,7 +152,6 @@ class WP_Style_Engine_CSS_Rules_Store { * @since 6.1.0 * * @param string $selector The CSS selector. - * * @return void */ public function remove_rule( $selector ) { diff --git a/wp-includes/style-engine/class-wp-style-engine-processor.php b/wp-includes/style-engine/class-wp-style-engine-processor.php index 241437b204..5274648fc3 100644 --- a/wp-includes/style-engine/class-wp-style-engine-processor.php +++ b/wp-includes/style-engine/class-wp-style-engine-processor.php @@ -41,7 +41,6 @@ class WP_Style_Engine_Processor { * @since 6.1.0 * * @param WP_Style_Engine_CSS_Rules_Store $store The store to add. - * * @return WP_Style_Engine_Processor Returns the object to allow chaining methods. */ public function add_store( $store ) { @@ -65,7 +64,6 @@ class WP_Style_Engine_Processor { * @since 6.1.0 * * @param WP_Style_Engine_CSS_Rule|WP_Style_Engine_CSS_Rule[] $css_rules A single, or an array of, WP_Style_Engine_CSS_Rule objects from a store or otherwise. - * * @return WP_Style_Engine_Processor Returns the object to allow chaining methods. */ public function add_rules( $css_rules ) { @@ -96,7 +94,6 @@ class WP_Style_Engine_Processor { * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`. * @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined. * } - * * @return string The computed CSS. */ public function get_css( $options = array() ) { diff --git a/wp-includes/style-engine/class-wp-style-engine.php b/wp-includes/style-engine/class-wp-style-engine.php index e24ad63a0e..57dbd97a90 100644 --- a/wp-includes/style-engine/class-wp-style-engine.php +++ b/wp-includes/style-engine/class-wp-style-engine.php @@ -16,7 +16,7 @@ * * This class is final and should not be extended. * This class is for internal Core usage and is not supposed to be used by extenders (plugins and/or themes). - * This is a low-level API that may need to do breaking changes. Please, use wp_style_engine_get_styles instead. + * This is a low-level API that may need to do breaking changes. Please, use wp_style_engine_get_styles() instead. * * @access private * @since 6.1.0 @@ -229,13 +229,12 @@ final class WP_Style_Engine { ); /** - * Util: Extracts the slug in kebab case from a preset string, e.g., "heavenly-blue" from 'var:preset|color|heavenlyBlue'. + * Util: Extracts the slug in kebab case from a preset string, e.g., `heavenly-blue` from `var:preset|color|heavenlyBlue`. * * @since 6.1.0 * * @param string $style_value A single CSS preset value. * @param string $property_key The CSS property that is the second element of the preset string. Used for matching. - * * @return string The slug, or empty string if not found. */ protected static function get_slug_from_preset_value( $style_value, $property_key ) { @@ -247,17 +246,16 @@ final class WP_Style_Engine { } /** - * Util: Generates a CSS var string, e.g., var(--wp--preset--color--background) from a preset string such as `var:preset|space|50`. + * Util: Generates a CSS var string, e.g., `var(--wp--preset--color--background)` from a preset string such as `var:preset|space|50`. * * @since 6.1.0 * - * @param string $style_value A single css preset value. - * @param string[] $css_vars An associate array of css var patterns used to generate the var string. - * - * @return string The css var, or an empty string if no match for slug found. + * @param string $style_value A single CSS preset value. + * @param string[] $css_vars An associate array of CSS var patterns used to generate the var string. + * @return string The CSS var, or an empty string if no match for slug found. */ protected static function get_css_var_value( $style_value, $css_vars ) { - foreach ( $css_vars as $property_key => $css_var_pattern ) { + foreach ( $css_vars as $property_key => $css_var_pattern ) { $slug = static::get_slug_from_preset_value( $style_value, $property_key ); if ( static::is_valid_style_value( $slug ) ) { $var = strtr( @@ -276,7 +274,6 @@ final class WP_Style_Engine { * @since 6.1.0 * * @param string $style_value A single CSS preset value. - * * @return bool */ protected static function is_valid_style_value( $style_value ) { @@ -290,9 +287,8 @@ final class WP_Style_Engine { * * @param string $store_name A valid store key. * @param string $css_selector When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values. - * @param string[] $css_declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ). - * - * @return void. + * @param string[] $css_declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. + * @return void */ public static function store_css_rule( $store_name, $css_selector, $css_declarations ) { if ( empty( $store_name ) || empty( $css_selector ) || empty( $css_declarations ) ) { @@ -307,8 +303,7 @@ final class WP_Style_Engine { * @since 6.1.0 * * @param string $store_name A store key. - * - * @return WP_Style_Engine_CSS_Rules_Store + * @return WP_Style_Engine_CSS_Rules_Store|null */ public static function get_store( $store_name ) { return WP_Style_Engine_CSS_Rules_Store::get_store( $store_name ); @@ -324,14 +319,13 @@ final class WP_Style_Engine { * @param array $options { * Optional. An array of options. Default empty array. * - * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset||`, to var( --wp--preset--* ) values. Default `false`. + * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset||`, to `var( --wp--preset--* )` values. Default false. * @type string $selector Optional. When a selector is passed, the value of `$css` in the return value will comprise a full CSS rule `$selector { ...$css_declarations }`, * otherwise, the value will be a concatenated string of CSS declarations. * } - * * @return array { - * @type string $classnames Classnames separated by a space. - * @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ). + * @type string[] $classnames Array of class names. + * @type string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. * } */ public static function parse_block_styles( $block_styles, $options ) { @@ -364,14 +358,13 @@ final class WP_Style_Engine { } /** - * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., '`var:preset||`'. + * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., `var:preset||`. * * @since 6.1.0 * - * @param array $style_value A single raw style value or css preset property from the $block_styles array. - * @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA. - * - * @return array|string[] An array of CSS classnames, or empty array. + * @param string $style_value A single raw style value or CSS preset property from the `$block_styles` array. + * @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA. + * @return string[] An array of CSS classnames, or empty array if there are none. */ protected static function get_classnames( $style_value, $style_definition ) { if ( empty( $style_value ) ) { @@ -407,15 +400,16 @@ final class WP_Style_Engine { * * @since 6.1.0 * - * @param array $style_value A single raw style value from $block_styles array. + * @param mixed $style_value A single raw style value from $block_styles array. * @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA. * @param array $options { * Optional. An array of options. Default empty array. * - * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset||`, to var( --wp--preset--* ) values. Default `false`. + * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., + * `var:preset||`, to `var( --wp--preset--* )` values. + * Default false. * } - * - * @return string[] An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ). + * @return string[] An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. */ protected static function get_css_declarations( $style_value, $style_definition, $options = array() ) { if ( isset( $style_definition['value_func'] ) && is_callable( $style_definition['value_func'] ) ) { @@ -473,21 +467,29 @@ final class WP_Style_Engine { /** * Style value parser that returns a CSS definition array comprising style properties * that have keys representing individual style properties, otherwise known as longhand CSS properties. - * e.g., "$style_property-$individual_feature: $value;", which could represent the following: - * "border-{top|right|bottom|left}-{color|width|style}: {value};" or, - * "border-image-{outset|source|width|repeat|slice}: {value};" + * + * Example: + * + * "$style_property-$individual_feature: $value;" + * + * Which could represent the following: + * + * "border-{top|right|bottom|left}-{color|width|style}: {value};" + * + * or: + * + * "border-image-{outset|source|width|repeat|slice}: {value};" * * @since 6.1.0 * - * @param array $style_value A single raw style value from $block_styles array. + * @param array $style_value A single raw style value from `$block_styles` array. * @param array $individual_property_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA representing an individual property of a CSS property, e.g., 'top' in 'border-top'. * @param array $options { * Optional. An array of options. Default empty array. * - * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset||`, to var( --wp--preset--* ) values. Default `false`. + * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset||`, to `var( --wp--preset--* )` values. Default false. * } - * - * @return string[] An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ). + * @return string[] An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. */ protected static function get_individual_property_css_declarations( $style_value, $individual_property_definition, $options = array() ) { if ( ! is_array( $style_value ) || empty( $style_value ) || empty( $individual_property_definition['path'] ) ) { @@ -526,13 +528,12 @@ final class WP_Style_Engine { } /** - * Returns compiled CSS from css_declarations. + * Returns compiled CSS from CSS declarations. * * @since 6.1.0 * - * @param string[] $css_declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ). + * @param string[] $css_declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. * @param string $css_selector When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values. - * * @return string A compiled CSS string. */ public static function compile_css( $css_declarations, $css_selector ) { @@ -559,10 +560,11 @@ final class WP_Style_Engine { * @param array $options { * Optional. An array of options. Default empty array. * - * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`. - * @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined. + * @type string|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'. + * When set, the style engine will attempt to store the CSS rules. + * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`. + * @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined. * } - * * @return string A compiled stylesheet from stored CSS rules. */ public static function compile_stylesheet_from_css_rules( $css_rules, $options = array() ) { diff --git a/wp-includes/version.php b/wp-includes/version.php index 4a586d5ed8..4ad7cada78 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.3-alpha-55718'; +$wp_version = '6.3-alpha-55719'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.