WordPress.org
Get WordPress

Make WordPress Core

Changeset 55711


Ignore:
Timestamp:
05/03/2023 06:46:44 PM (3 years ago)
Author:
johnbillion
Message:

Docs: Corrections and improvements to docblocks for global styles, global settings, theme.json parsing, and shortcodes.

See #57840

Location:
trunk
Files:
4 edited

Legend:

Unmodified
Added
Removed

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

    r55349 r55711  
    975975         * @since 5.9.0 Removed the `$type` parameter`, added the `$types` and `$origins` parameters.
    976976         *
    977          * @param array $types   Types of styles to load. Will load all by default. It accepts:
    978          *                       - `variables`: only the CSS Custom Properties for presets & custom ones.
    979          *                       - `styles`: only the styles section in theme.json.
    980          *                       - `presets`: only the classes for the presets.
    981          * @param array $origins A list of origins to include. By default it includes VALID_ORIGINS.
    982          * @param array $options An array of options for now used for internal purposes only (may change without notice).
    983          *                       The options currently supported are 'scope' that makes sure all style are scoped to a given selector,
    984          *                       and root_selector which overwrites and forces a given selector to be used on the root node.
     977         * @param string[] $types   Types of styles to load. Will load all by default. It accepts:
     978         *                          - `variables`: only the CSS Custom Properties for presets & custom ones.
     979         *                          - `styles`: only the styles section in theme.json.
     980         *                          - `presets`: only the classes for the presets.
     981         * @param string[] $origins A list of origins to include. By default it includes VALID_ORIGINS.
     982         * @param array    $options An array of options for now used for internal purposes only (may change without notice).
     983         *                          The options currently supported are 'scope' that makes sure all style are scoped to a
     984         *                          given selector, and root_selector which overwrites and forces a given selector to be
     985         *                          used on the root node.
    985986         * @return string The resulting stylesheet.
    986987         */
    … …  
    10971098
    10981099        /**
    1099          * Returns the global styles custom css.
     1100         * Returns the global styles custom CSS.
    11001101         *
    11011102         * @since 6.2.0
    … …  
    14111412         * @since 5.9.0
    14121413         *
    1413          * @param array $setting_nodes Nodes with settings.
    1414          * @param array $origins       List of origins to process presets from.
     1414         * @param array    $setting_nodes Nodes with settings.
     1415         * @param string[] $origins       List of origins to process presets from.
    14151416         * @return string The new stylesheet.
    14161417         */
    … …  
    14481449         * @since 5.9.0 Added the `$origins` parameter.
    14491450         *
    1450          * @param array $nodes   Nodes with settings.
    1451          * @param array $origins List of origins to process.
     1451         * @param array    $nodes   Nodes with settings.
     1452         * @param string[] $origins List of origins to process.
    14521453         * @return string The new stylesheet.
    14531454         */
    … …  
    15061507         * @since 5.9.0 Added the `$origins` parameter.
    15071508         *
    1508          * @param array  $settings Settings to process.
    1509          * @param string $selector Selector wrapping the classes.
    1510          * @param array $origins  List of origins to process.
     1509         * @param array    $settings Settings to process.
     1510         * @param string   $selector Selector wrapping the classes.
     1511         * @param string[] $origins  List of origins to process.
    15111512         * @return string The result of processing the presets.
    15121513         */
    … …  
    16121613         * @since 5.9.0
    16131614         *
    1614          * @param array $settings        Settings to process.
    1615          * @param array $preset_metadata One of the PRESETS_METADATA values.
    1616          * @param array $origins         List of origins to process.
     1615         * @param array    $settings        Settings to process.
     1616         * @param array    $preset_metadata One of the PRESETS_METADATA values.
     1617         * @param string[] $origins         List of origins to process.
    16171618         * @return array Array of presets where each key is a slug and each value is the preset value.
    16181619         */
    … …  
    16541655         * @since 5.9.0
    16551656         *
    1656          * @param array $settings        Settings to process.
    1657          * @param array $preset_metadata One of the PRESETS_METADATA values.
    1658          * @param array $origins         List of origins to process.
     1657         * @param array    $settings        Settings to process.
     1658         * @param array    $preset_metadata One of the PRESETS_METADATA values.
     1659         * @param string[] $origins         List of origins to process.
    16591660         * @return array Array of presets where the key and value are both the slug.
    16601661         */
    … …  
    17071708         * @since 5.9.0 Added the `$origins` parameter.
    17081709         *
    1709          * @param array $settings Settings to process.
    1710          * @param array $origins  List of origins to process.
     1710         * @param array    $settings Settings to process.
     1711         * @param string[] $origins  List of origins to process.
    17111712         * @return array The modified $declarations.
    17121713         */

  • trunk/src/wp-includes/global-styles-and-settings.php

    r55192 r55711  
    2222 *                              If empty or unknown, 'all' is used.
    2323 * }
    24  * @return array The settings to retrieve.
     24 * @return mixed The settings array or individual setting value to retrieve.
    2525 */
    2626function wp_get_global_settings( $path = array(), $context = array() ) {
    … …  
    105105 *                              If empty or unknown, 'all' is used.
    106106 * }
    107  * @return array The styles to retrieve.
     107 * @return mixed The styles array or individual style value to retrieve.
    108108 */
    109109function wp_get_global_styles( $path = array(), $context = array() ) {
    … …  
    227227
    228228/**
    229  * Gets the global styles custom css from theme.json.
     229 * Gets the global styles custom CSS from theme.json.
    230230 *
    231231 * @since 6.2.0
    232232 *
    233  * @return string Stylesheet.
     233 * @return string The global styles custom CSS.
    234234 */
    235235function wp_get_global_styles_custom_css() {

  • trunk/src/wp-includes/shortcodes.php

    r55119 r55711  
    309309 * @global array $shortcode_tags
    310310 *
    311  * @param array $m Regular expression match array.
    312  * @return string|false Shortcode output on success, false on failure.
     311 * @param array $m {
     312 *     Regular expression match array.
     313 *
     314 *     @type string $0 Entire matched shortcode text.
     315 *     @type string $1 Optional second opening bracket for escaping shortcodes.
     316 *     @type string $2 Shortcode name.
     317 *     @type string $3 Shortcode arguments list.
     318 *     @type string $4 Optional self closing slash.
     319 *     @type string $5 Content of a shortcode when it wraps some content.
     320 *     @type string $6 Optional second closing brocket for escaping shortcodes.
     321 * }
     322 * @return string Shortcode output.
    313323 */
    314324function do_shortcode_tag( $m ) {
    … …  
    343353         * @param false|string $output Short-circuit return value. Either false or the value to replace the shortcode with.
    344354         * @param string       $tag    Shortcode name.
    345          * @param array|string $attr   Shortcode attributes array or empty string.
     355         * @param array|string $attr   Shortcode attributes array or the original arguments string if it cannot be parsed.
    346356         * @param array        $m      Regular expression match array.
    347357         */
    … …  
    362372         * @param string       $output Shortcode output.
    363373         * @param string       $tag    Shortcode name.
    364          * @param array|string $attr   Shortcode attributes array or empty string.
     374         * @param array|string $attr   Shortcode attributes array or the original arguments string if it cannot be parsed.
    365375         * @param array        $m      Regular expression match array.
    366376         */
    … …  
    522532 * @since 2.5.0
    523533 *
    524  * @param string $text
    525  * @return array|string List of attribute values.
    526  *                      Returns empty array if '""' === trim( $text ).
    527  *                      Returns empty string if '' === trim( $text ).
    528  *                      All other matches are checked for not empty().
     534 * @param string $text Shortcode arguments list.
     535 * @return array|string Array of attribute values keyed by attribute name.
     536 *                      Returns empty array if there are no attributes.
     537 *                      Returns the original arguments string if it cannot be parsed.
    529538 */
    530539function shortcode_parse_atts( $text ) {

  • trunk/tests/phpunit/tests/functions.php

    r55562 r55711  
    17821782         *
    17831783         * @return array {
    1784          *     @type array $0... {
     1784         *     @type array ...$0 {
    17851785         *         @type string $0 File path.
    17861786         *         @type array  $1 List of allowed files.
    … …  
    19281928         *
    19291929         * @return array {
    1930          *     @type array $0... {
     1930         *     @type array ...$0 {
    19311931         *         @type string $0 The resource path or URL.
    19321932         *         @type bool   $1 Expected result.
Note: See TracChangeset for help on using the changeset viewer.