Formatting PHP doc comments and params that describe associative arrays

Updating test function names and annotations.

Author: ramonjd

src/wp-includes/style-engine.php

@@ -25,19 +25,22 @@
  * @access public
  * @since 6.1.0
  *
- * @param array                 $block_styles The style object.
- * @param array<string|boolean> $options      array(
- *     'context' => (string|null) 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, where a selector is also passed.
- *     'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
- *     'selector'                   => (string) When a selector is passed, `generate()` will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
- * );.
- *
- * @return array<string|array> array(
- *     'css'          => (string) A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag.
- *     'declarations' => (array) An array of property/value pairs representing parsed CSS declarations.
- *     'classnames'   => (string) Classnames separated by a space.
- * );
+ * @param array $block_styles The style object.
+ * @param array $options {
+ *     Optional. An array of options. Default empty array.
+ *
+ *     @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|<PRESET_TYPE>|<PRESET_SLUG>`, 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 array<string, string> $declarations An array of property/value pairs representing parsed CSS declarations.
+ *     @type string                $classnames   Classnames separated by a space.
+ * }
  */
 function wp_style_engine_get_styles( $block_styles, $options = array() ) {
 	if ( ! class_exists( 'WP_Style_Engine' ) ) {
@@ -75,23 +78,32 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) {
 
 /**
  * Returns compiled CSS from a collection of selectors and declarations.
- * This won't add to any store, but is useful for returning a compiled style sheet from any CSS selector + declarations combos.
+ * 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}`.
  *
  * @access public
  * @since 6.1.0
  *
- * @param array<array>  $css_rules array(
- *      array(
- *          'selector'    => (string) A CSS selector.
- *          declarations' => (boolean) An array of CSS definitions, e.g., array( "$property" => "$value" ).
- *      )
- *  );.
- * @param array<string> $options array(
- *     'context' => (string|null) 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.
- *    'optimize' => (boolean) Whether to optimize the CSS output, e.g., combine rules.
- *    'prettify' => (boolean) Whether to add new lines to output.
- * );.
+ * @param array $css_rules {
+ *     Required. A collection of CSS rules.
+ *
+ *     @type array ...$0 {
+ *         @type string                $selector     A CSS selector.
+ *         @type array<string, string> $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
+ *     }
+ * }
+ * @param array $options {
+ *     Optional. An array of options. Default empty array.
+ *
+ *     @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 boolean     $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
+ *     @type boolean     $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.
  */
@@ -133,18 +145,20 @@ function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = a
  * @access public
  * @since 6.1.0
  *
- * @param string $store_name A valid store name.
- * @param array  $options    array(
- *    'optimize' => (boolean) Whether to optimize the CSS output, e.g., combine rules.
- *    'prettify' => (boolean) Whether to add new lines to output.
- * );.
+ * @param string $context A valid context name, corresponding to an existing store key.
+ * @param array  $options {
+ *     Optional. An array of options. Default empty array.
+ *
+ *     @type boolean $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
+ *     @type boolean $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( $store_name, $options = array() ) {
-	if ( ! class_exists( 'WP_Style_Engine' ) || empty( $store_name ) ) {
+function wp_style_engine_get_stylesheet_from_context( $context, $options = array() ) {
+	if ( ! class_exists( 'WP_Style_Engine' ) || empty( $context ) ) {
 		return '';
 	}
 
-	return WP_Style_Engine::compile_stylesheet_from_css_rules( WP_Style_Engine::get_store( $store_name )->get_all_rules(), $options );
+	return WP_Style_Engine::compile_stylesheet_from_css_rules( WP_Style_Engine::get_store( $context )->get_all_rules(), $options );
 }

src/wp-includes/style-engine/class-wp-style-engine-processor.php

@@ -63,6 +63,7 @@ public function add_rules( $css_rules ) {
 		if ( ! is_array( $css_rules ) ) {
 			$css_rules = array( $css_rules );
 		}
+
 		foreach ( $css_rules as $rule ) {
 			$selector = $rule->get_selector();
 			if ( isset( $this->css_rules[ $selector ] ) ) {
@@ -80,10 +81,12 @@ public function add_rules( $css_rules ) {
 	 *
 	 * @since 6.1.0
 	 *
-	 * @param array $options array(
-	 *    'optimize' => (boolean) Whether to optimize the CSS output, e.g., combine rules.
-	 *    'prettify' => (boolean) Whether to add new lines to output.
-	 * );.
+	 * @param array $options   {
+	 *     Optional. An array of options. Default empty array.
+	 *
+	 *     @type boolean $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
+	 *     @type boolean $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.
 	 */

src/wp-includes/style-engine/class-wp-style-engine.php

@@ -275,9 +275,9 @@ protected static function is_valid_style_value( $style_value ) {
 	 *
 	 * @since 6.1.0
 	 *
-	 * @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 array  $css_declarations An array of parsed CSS property => CSS value pairs.
+	 * @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 array<string, string> $css_declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
 	 *
 	 * @return void.
 	 */
@@ -308,15 +308,18 @@ public static function get_store( $store_name ) {
 	 * @since 6.1.0
 	 *
 	 * @param array $block_styles The style object.
-	 * @param array $options      array(
-	 *     'selector'                   => (string) When a selector is passed, `generate()` will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
-	 *     'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
-	 * );.
-	 *
-	 * @return array array(
-	 *     'declarations' => (array) An array of parsed CSS property => CSS value pairs.
-	 *     'classnames'   => (array) A flat array of classnames.
-	 * );
+	 * @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|<PRESET_TYPE>|<PRESET_SLUG>`, 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 array<string, string> $declarations An array of property/value pairs representing parsed CSS declarations.
+	 * }
 	 */
 	public static function parse_block_styles( $block_styles, $options ) {
 		$parsed_styles = array(
@@ -348,14 +351,14 @@ public static function parse_block_styles( $block_styles, $options ) {
 	}
 
 	/**
-	 * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., 'var:preset|color|heavenly-blue'.
+	 * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., '`var:preset|<PRESET_TYPE>|<PRESET_SLUG>`'.
 	 *
 	 * @since 6.1.0
 	 *
-	 * @param array         $style_value      A single raw style value or css preset property from the generate() $block_styles array.
-	 * @param array<string> $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
+	 * @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        An array of CSS classnames.
+	 * @return array<string> An array of CSS classnames.
 	 */
 	protected static function get_classnames( $style_value, $style_definition ) {
 		if ( empty( $style_value ) ) {
@@ -389,15 +392,17 @@ protected static function get_classnames( $style_value, $style_definition ) {
 	 *
 	 * @since 6.1.0
 	 *
-	 * @param array         $style_value          A single raw style value from the generate() $block_styles array.
-	 * @param array<string> $style_definition     A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
-	 * @param array         $options              array(
-	 *     'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
-	 * );.
+	 * @param array $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.
 	 *
-	 * @return array        An array of CSS definitions, e.g., array( "$property" => "$value" ).
+	 *     @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
+	 * }
+	 *
+	 * @return array<string, string> An array of CSS definitions, e.g., array( "$property" => "$value" ).
 	 */
-	protected static function get_css_declarations( $style_value, $style_definition, $options ) {
+	protected static function get_css_declarations( $style_value, $style_definition, $options = array() ) {
 		if ( isset( $style_definition['value_func'] ) && is_callable( $style_definition['value_func'] ) ) {
 			return call_user_func( $style_definition['value_func'], $style_value, $style_definition, $options );
 		}
@@ -406,7 +411,7 @@ protected static function get_css_declarations( $style_value, $style_definition,
 		$style_property_keys  = $style_definition['property_keys'];
 		$should_skip_css_vars = isset( $options['convert_vars_to_classnames'] ) && true === $options['convert_vars_to_classnames'];
 
-		// Build CSS var values from var:? values, e.g, `var(--wp--css--rule-slug )`
+		// Build CSS var values from `var:preset|<PRESET_TYPE>|<PRESET_SLUG>` values, e.g, `var(--wp--css--rule-slug )`.
 		// Check if the value is a CSS preset and there's a corresponding css_var pattern in the style definition.
 		if ( is_string( $style_value ) && str_contains( $style_value, 'var:' ) ) {
 			if ( ! $should_skip_css_vars && ! empty( $style_definition['css_vars'] ) ) {
@@ -455,15 +460,17 @@ protected static function get_css_declarations( $style_value, $style_definition,
 	 *
 	 * @since 6.1.0
 	 *
-	 * @param array $style_value                    A single raw Gutenberg style attributes value for a CSS property.
-	 * @param array $individual_property_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
-	 * @param array $options                        array(
-	 *     'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
-	 * );.
+	 * @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|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
+	 * }
 	 *
-	 * @return array An array of CSS definitions, e.g., array( "$property" => "$value" ).
+	 * @return array<string, 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 ) {
+	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'] ) ) {
 			return array();
 		}
@@ -502,8 +509,8 @@ protected static function get_individual_property_css_declarations( $style_value
 	 *
 	 * @since 6.1.0
 	 *
-	 * @param array  $css_declarations An array of parsed CSS property => CSS value pairs.
-	 * @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 array<string, 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.
 	 */
@@ -528,10 +535,12 @@ public static function compile_css( $css_declarations, $css_selector ) {
 	 * @since 6.1.0
 	 *
 	 * @param WP_Style_Engine_CSS_Rule[] $css_rules An array of WP_Style_Engine_CSS_Rule objects from a store or otherwise.
-	 * @param array                      $options array(
-	 *    'optimize' => (boolean) Whether to optimize the CSS output, e.g., combine rules.
-	 *    'prettify' => (boolean) Whether to add new lines to output.
-	 * );.
+	 * @param array                      $options   {
+	 *     Optional. An array of options. Default empty array.
+	 *
+	 *     @type boolean     $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
+	 *     @type boolean     $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.
 	 */