WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
12/04/2021 12:56:29 PM (3 years ago)
Author:
SergeyBiryukov
Message:

Docs: Some documentation improvements for WP_Theme_JSON and WP_Theme_JSON_Resolver classes:

  • Make the @since 5.9.0 notes more specific. When mentioning that parameters or values have been added or changed, it is generally also helpful to include their exact names and the nature of changes for future reference.
  • Update some DocBlocks per the documentation standards.

Follow-up to [52049], [52306].

See #53399, #54336.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-wp-theme-json.php

    r52275 r52320  
    8383     *                 (either value_key or value_func should be present)
    8484     * - css_vars   => template string to use in generating the CSS Custom Property.
    85      *                 Example output: "--wp--preset--duotone--blue: <value>" will generate as many CSS Custom Properties as presets defined
     85     *                 Example output: "--wp--preset--duotone--blue: <value>" will generate
     86     *                 as many CSS Custom Properties as presets defined
    8687     *                 substituting the $slug for the slug's value for each preset value.
    8788     * - classes    => array containing a structure with the classes to
    … …  
    100101     *
    101102     * @since 5.8.0
    102      * @since 5.9.0 Added new presets and simplified the metadata structure.
     103     * @since 5.9.0 Added the `color/duotone` and `typography/fontFamily` presets,
     104     *              simplified the metadata structure.
    103105     * @var array
    104106     */
    … …  
    157159     *
    158160     * @since 5.8.0
    159      * @since 5.9.0 Added new properties and simplified the metadata structure.
     161     * @since 5.9.0 Added the `border-*`, `font-family`, `font-style`, `font-weight`,
     162     *              `letter-spacing`, `margin-*`, `padding-*`, `--wp--style--block-gap`,
     163     *              `text-decoration`, `text-transform`, and `filter` properties,
     164     *              simplified the metadata structure.
    160165     * @var array
    161166     */
    … …  
    213218     *
    214219     * @since 5.8.0
    215      * @since 5.9.0 Renamed from ALLOWED_TOP_LEVEL_KEYS and added new values.
     220     * @since 5.9.0 Renamed from `ALLOWED_TOP_LEVEL_KEYS`,
     221     *              added the `customTemplates` and `templateParts` values.
    216222     * @var string[]
    217223     */
    … …  
    228234     *
    229235     * @since 5.8.0
    230      * @since 5.9.0 Renamed from ALLOWED_SETTINGS, gained new properties, and renamed others according to the new schema.
     236     * @since 5.9.0 Renamed from `ALLOWED_SETTINGS`, added new properties
     237     *              for `border`, `color`, `spacing`, and `typography`,
     238     *              and renamed others according to the new schema.
    231239     * @var array
    232240     */
    … …  
    281289     *
    282290     * @since 5.8.0
    283      * @since 5.9.0 Renamed from ALLOWED_SETTINGS, gained new properties.
     291     * @since 5.9.0 Renamed from `ALLOWED_SETTINGS`, added new properties
     292     *              for `border`, `filter`, `spacing`, and `typography`.
    284293     * @var array
    285294     */
    … …  
    336345     *
    337346     * @since 5.8.0
    338      * @since 5.9.0 Changed value.
     347     * @since 5.9.0 Changed value from 1 to 2.
    339348     * @var int
    340349     */
    … …  
    436445     *
    437446     * @since 5.8.0
    438      * @since 5.9.0 Has new parameters.
    439      *
    440      * @param array $input Structure to sanitize.
    441      * @param array $valid_block_names List of valid block names.
     447     * @since 5.9.0 Added the `$valid_block_names` and `$valid_element_name` parameters.
     448     *
     449     * @param array $input               Structure to sanitize.
     450     * @param array $valid_block_names   List of valid block names.
    442451     * @param array $valid_element_names List of valid element names.
    443452     * @return array The sanitized output.
    … …  
    519528     *
    520529     * @since 5.8.0
    521      * @since 5.9.0 Added duotone key with CSS selector.
     530     * @since 5.9.0 Added `duotone` key with CSS selector.
    522531     *
    523532     * @return array Block metadata.
    … …  
    633642     *
    634643     * @since 5.8.0
    635      * @since 5.9.0 Changed the arguments passed to the function.
    636      *
    637      * @param array $types    Types of styles to load. Will load all by default. It accepts:
    638      *                         'variables': only the CSS Custom Properties for presets & custom ones.
    639      *                         'styles': only the styles section in theme.json.
    640      *                         'presets': only the classes for the presets.
    641      * @param array $origins A list of origins to include. By default it includes self::VALID_ORIGINS.
     644     * @since 5.9.0 Removed the `$type` parameter`, added the `$types` and `$origins` parameters.
     645     *
     646     * @param array $types   Types of styles to load. Will load all by default. It accepts:
     647     *                       - `variables`: only the CSS Custom Properties for presets & custom ones.
     648     *                       - `styles`: only the styles section in theme.json.
     649     *                       - `presets`: only the classes for the presets.
     650     * @param array $origins A list of origins to include. By default it includes `self::VALID_ORIGINS`.
    642651     * @return string Stylesheet.
    643652     */
    … …  
    645654        if ( is_string( $types ) ) {
    646655            // Dispatch error and map old arguments to new ones.
    647             _deprecated_argument( __FUNCTION__, '5.9' );
     656            _deprecated_argument( __FUNCTION__, '5.9.0' );
    648657            if ( 'block_styles' === $types ) {
    649658                $types = array( 'styles', 'presets' );
    … …  
    737746     *
    738747     * @since 5.8.0
    739      * @since 5.9.0 Renamed to get_block_classes and no longer returns preset classes.
     748     * @since 5.9.0 Renamed from `get_block_styles()` to `get_block_classes()`
     749     *              and no longer returns preset classes.
    740750     *
    741751     * @param array $style_nodes Nodes with styles.
    … …  
    851861     *
    852862     * @since 5.8.0
    853      * @since 5.9.0 Added origins parameter.
    854      *
    855      * @param array $nodes Nodes with settings.
     863     * @since 5.9.0 Added the `$origins` parameter.
     864     *
     865     * @param array $nodes   Nodes with settings.
    856866     * @param array $origins List of origins to process.
    857867     * @return string The new stylesheet.
    … …  
    928938     *
    929939     * @since 5.8.0
    930      * @since 5.9.0 Added origins parameter.
     940     * @since 5.9.0 Added the `$origins` parameter.
    931941     *
    932942     * @param array  $settings Settings to process.
    … …  
    980990     * @param string $scope    Selector to scope to.
    981991     * @param string $selector Original selector.
    982      *
    983992     * @return string Scoped selector.
    984993     */
    … …  
    10281037     * @since 5.9.0
    10291038     *
    1030      * @param array $settings Settings to process.
     1039     * @param array $settings        Settings to process.
    10311040     * @param array $preset_metadata One of the PRESETS_METADATA values.
    1032      * @param array $origins List of origins to process.
     1041     * @param array $origins         List of origins to process.
    10331042     * @return array Array of presets where each key is a slug and each value is the preset value.
    10341043     */
    … …  
    10701079     * @since 5.9.0
    10711080     *
    1072      * @param array $settings Settings to process.
     1081     * @param array $settings        Settings to process.
    10731082     * @param array $preset_metadata One of the PRESETS_METADATA values.
    1074      * @param array $origins List of origins to process.
     1083     * @param array $origins         List of origins to process.
    10751084     * @return array Array of presets where the key and value are both the slug.
    10761085     */
    … …  
    10991108     *
    11001109     * @param string $input String to replace.
    1101      * @param string $slug The slug value to use to generate the custom property.
    1102      * @return string The CSS Custom Property. Something along the lines of --wp--preset--color--black.
     1110     * @param string $slug  The slug value to use to generate the custom property.
     1111     * @return string The CSS Custom Property. Something along the lines of `--wp--preset--color--black`.
    11031112     */
    11041113    private static function replace_slug_in_string( $input, $slug ) {
    … …  
    11171126     *
    11181127     * @since 5.8.0
     1128     * @since 5.9.0 Added the `$origins` parameter.
    11191129     *
    11201130     * @param array $settings Settings to process.
    … …  
    12351245     *
    12361246     * @since 5.8.0
    1237      * @since 5.9.0 Added theme setting and properties parameters.
    1238      *
    1239      * @param array $styles Styles to process.
    1240      * @param array $settings Theme settings.
     1247     * @since 5.9.0 Added the `$settings` and `$properties` parameters.
     1248     *
     1249     * @param array $styles    Styles to process.
     1250     * @param array $settings  Theme settings.
    12411251     * @param array $properties Properties metadata.
    12421252     * @return array Returns the modified $declarations.
    … …  
    12861296     *
    12871297     * @since 5.8.0
    1288      * @since 5.9.0 Consider $value that are arrays as well.
     1298     * @since 5.9.0 Added support for values of array type, which are returned as is.
    12891299     *
    12901300     * @param array $styles Styles subtree.
    12911301     * @param array $path   Which property to process.
    1292      * @return string Style property value.
     1302     * @return string|array Style property value.
    12931303     */
    12941304    private static function get_property_value( $styles, $path ) {
    … …  
    15331543     * @since 5.9.0
    15341544     *
    1535      * @param array $data A theme.json like structure to inspect.
    1536      * @param array $node_path The path to inspect. It's 'settings' by default.
    1537      *
     1545     * @param array $data      A theme.json like structure to inspect.
     1546     * @param array $node_path The path to inspect. Default is 'settings'.
    15381547     * @return array An associative array containing the slugs for the given path.
    15391548     */
    … …  
    15691578     * @since 5.9.0
    15701579     *
    1571      * @param array $node The node with the presets to validate.
    1572      * @param array $path The path to the preset type to inspect.
     1580     * @param array $node  The node with the presets to validate.
     1581     * @param array $path  The path to the preset type to inspect.
    15731582     * @param array $slugs The slugs that should not be overriden.
    1574      *
    1575      * @return array The new node
     1583     * @return array The new node.
    15761584     */
    15771585    private static function filter_slugs( $node, $path, $slugs ) {
    … …  
    17401748     * @since 5.9.0
    17411749     *
    1742      * @param string $property_name Property name in a CSS declaration, i.e. the `color` in `color: red`.
     1750     * @param string $property_name  Property name in a CSS declaration, i.e. the `color` in `color: red`.
    17431751     * @param string $property_value Value in a CSS declaration, i.e. the `red` in `color: red`.
    1744      * @return boolean
     1752     * @return bool
    17451753     */
    17461754    private static function is_safe_css_declaration( $property_name, $property_value ) {
Note: See TracChangeset for help on using the changeset viewer.