WordPress.org
Get WordPress

Make WordPress Core

Changeset 55711


Ignore:
Timestamp:
05/03/2023 06:46:44 PM (19 months 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.