WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
05/03/2023 11:55:50 PM (2 years ago)
Author:
johnbillion
Message:

Docs: Correct and improve inline docs relating to the style engine.

See #57840

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r55175 r55719  
    1717 * This class is final and should not be extended.
    1818 * This class is for internal Core usage and is not supposed to be used by extenders (plugins and/or themes).
    19  * This is a low-level API that may need to do breaking changes. Please, use wp_style_engine_get_styles instead.
     19 * This is a low-level API that may need to do breaking changes. Please, use wp_style_engine_get_styles() instead.
    2020 *
    2121 * @access private
    … …  
    230230
    231231    /**
    232      * Util: Extracts the slug in kebab case from a preset string, e.g., "heavenly-blue" from 'var:preset|color|heavenlyBlue'.
     232     * Util: Extracts the slug in kebab case from a preset string, e.g., `heavenly-blue` from `var:preset|color|heavenlyBlue`.
    233233     *
    234234     * @since 6.1.0
    … …  
    236236     * @param string $style_value  A single CSS preset value.
    237237     * @param string $property_key The CSS property that is the second element of the preset string. Used for matching.
    238      *
    239238     * @return string The slug, or empty string if not found.
    240239     */
    … …  
    248247
    249248    /**
    250      * Util: Generates a CSS var string, e.g., var(--wp--preset--color--background) from a preset string such as `var:preset|space|50`.
    251      *
    252      * @since 6.1.0
    253      *
    254      * @param string   $style_value  A single css preset value.
    255      * @param string[] $css_vars     An associate array of css var patterns used to generate the var string.
    256      *
    257      * @return string The css var, or an empty string if no match for slug found.
     249     * Util: Generates a CSS var string, e.g., `var(--wp--preset--color--background)` from a preset string such as `var:preset|space|50`.
     250     *
     251     * @since 6.1.0
     252     *
     253     * @param string   $style_value  A single CSS preset value.
     254     * @param string[] $css_vars     An associate array of CSS var patterns used to generate the var string.
     255     * @return string The CSS var, or an empty string if no match for slug found.
    258256     */
    259257    protected static function get_css_var_value( $style_value, $css_vars ) {
    260         foreach ( $css_vars as  $property_key => $css_var_pattern ) {
     258        foreach ( $css_vars as $property_key => $css_var_pattern ) {
    261259            $slug = static::get_slug_from_preset_value( $style_value, $property_key );
    262260            if ( static::is_valid_style_value( $slug ) ) {
    … …  
    277275     *
    278276     * @param string $style_value A single CSS preset value.
    279      *
    280277     * @return bool
    281278     */
    … …  
    291288     * @param string   $store_name       A valid store key.
    292289     * @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.
    293      * @param string[] $css_declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
    294      *
    295      * @return void.
     290     * @param string[] $css_declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
     291     * @return void
    296292     */
    297293    public static function store_css_rule( $store_name, $css_selector, $css_declarations ) {
    … …  
    308304     *
    309305     * @param string $store_name A store key.
    310      *
    311      * @return WP_Style_Engine_CSS_Rules_Store
     306     * @return WP_Style_Engine_CSS_Rules_Store|null
    312307     */
    313308    public static function get_store( $store_name ) {
    … …  
    325320     *     Optional. An array of options. Default empty array.
    326321     *
    327      *     @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`.
     322     *     @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.
    328323     *     @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 }`,
    329324     *                                                   otherwise, the value will be a concatenated string of CSS declarations.
    330325     * }
    331      *
    332326     * @return array {
    333      *     @type string   $classnames   Classnames separated by a space.
    334      *     @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
     327     *     @type string[] $classnames   Array of class names.
     328     *     @type string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
    335329     * }
    336330     */
    … …  
    365359
    366360    /**
    367      * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., '`var:preset|<PRESET_TYPE>|<PRESET_SLUG>`'.
    368      *
    369      * @since 6.1.0
    370      *
    371      * @param array $style_value      A single raw style value or css preset property from the $block_styles array.
    372      * @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
    373      *
    374      * @return array|string[] An array of CSS classnames, or empty array.
     361     * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`.
     362     *
     363     * @since 6.1.0
     364     *
     365     * @param string $style_value      A single raw style value or CSS preset property from the `$block_styles` array.
     366     * @param array  $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
     367     * @return string[] An array of CSS classnames, or empty array if there are none.
    375368     */
    376369    protected static function get_classnames( $style_value, $style_definition ) {
    … …  
    408401     * @since 6.1.0
    409402     *
    410      * @param array $style_value      A single raw style value from $block_styles array.
     403     * @param mixed $style_value      A single raw style value from $block_styles array.
    411404     * @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
    412405     * @param array $options          {
    413406     *     Optional. An array of options. Default empty array.
    414407     *
    415      *     @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`.
     408     *     @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g.,
     409     *                                            `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to `var( --wp--preset--* )` values.
     410     *                                            Default false.
    416411     * }
    417      *
    418      * @return string[] An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
     412     * @return string[] An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
    419413     */
    420414    protected static function get_css_declarations( $style_value, $style_definition, $options = array() ) {
    … …  
    474468     * Style value parser that returns a CSS definition array comprising style properties
    475469     * that have keys representing individual style properties, otherwise known as longhand CSS properties.
    476      * e.g., "$style_property-$individual_feature: $value;", which could represent the following:
    477      * "border-{top|right|bottom|left}-{color|width|style}: {value};" or,
    478      * "border-image-{outset|source|width|repeat|slice}: {value};"
    479      *
    480      * @since 6.1.0
    481      *
    482      * @param array $style_value                    A single raw style value from $block_styles array.
     470     *
     471     * Example:
     472     *
     473     *     "$style_property-$individual_feature: $value;"
     474     *
     475     * Which could represent the following:
     476     *
     477     *     "border-{top|right|bottom|left}-{color|width|style}: {value};"
     478     *
     479     * or:
     480     *
     481     *     "border-image-{outset|source|width|repeat|slice}: {value};"
     482     *
     483     * @since 6.1.0
     484     *
     485     * @param array $style_value                    A single raw style value from `$block_styles` array.
    483486     * @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'.
    484487     * @param array $options                        {
    485488     *     Optional. An array of options. Default empty array.
    486489     *
    487      *     @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`.
     490     *     @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.
    488491     * }
    489      *
    490      * @return string[] An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
     492     * @return string[] An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
    491493     */
    492494    protected static function get_individual_property_css_declarations( $style_value, $individual_property_definition, $options = array() ) {
    … …  
    527529
    528530    /**
    529      * Returns compiled CSS from css_declarations.
    530      *
    531      * @since 6.1.0
    532      *
    533      * @param string[] $css_declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
     531     * Returns compiled CSS from CSS declarations.
     532     *
     533     * @since 6.1.0
     534     *
     535     * @param string[] $css_declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
    534536     * @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.
    535      *
    536537     * @return string A compiled CSS string.
    537538     */
    … …  
    560561     *     Optional. An array of options. Default empty array.
    561562     *
    562      *     @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
    563      *     @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.
     563     *     @type string|null $context  An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
     564     *                                 When set, the style engine will attempt to store the CSS rules.
     565     *     @type bool        $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
     566     *     @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.
    564567     * }
    565      *
    566568     * @return string A compiled stylesheet from stored CSS rules.
    567569     */
Note: See TracChangeset for help on using the changeset viewer.