WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

See #57840

Built from https://develop.svn.wordpress.org/trunk@55711


git-svn-id: http://core.svn.wordpress.org/trunk@55223 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
John Blackbourn 2023-05-03 18:48:22 +00:00
parent 27c4548f19
commit c83f4cb97a
4 changed files with 48 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
wp-includes/class-wp-theme-json.php
View File

@ -974,14 +974,15 @@ class WP_Theme_JSON {
* @since 5.8.0 * @since 5.8.0
* @since 5.9.0 Removed the `$type` parameter`, added the `$types` and `$origins` parameters. * @since 5.9.0 Removed the `$type` parameter`, added the `$types` and `$origins` parameters.
* *
* @param array $types Types of styles to load. Will load all by default. It accepts: * @param string[] $types Types of styles to load. Will load all by default. It accepts:
* - `variables`: only the CSS Custom Properties for presets & custom ones. * - `variables`: only the CSS Custom Properties for presets & custom ones.
* - `styles`: only the styles section in theme.json. * - `styles`: only the styles section in theme.json.
* - `presets`: only the classes for the presets. * - `presets`: only the classes for the presets.
* @param array $origins A list of origins to include. By default it includes VALID_ORIGINS. * @param string[] $origins A list of origins to include. By default it includes VALID_ORIGINS.
* @param array $options An array of options for now used for internal purposes only (may change without notice). * @param array $options An array of options for now used for internal purposes only (may change without notice).
* The options currently supported are 'scope' that makes sure all style are scoped to a given selector, * The options currently supported are 'scope' that makes sure all style are scoped to a
* and root_selector which overwrites and forces a given selector to be used on the root node. * given selector, and root_selector which overwrites and forces a given selector to be
* used on the root node.
* @return string The resulting stylesheet. * @return string The resulting stylesheet.
*/ */
public function get_stylesheet( $types = array( 'variables', 'styles', 'presets' ), $origins = null, $options = array() ) { public function get_stylesheet( $types = array( 'variables', 'styles', 'presets' ), $origins = null, $options = array() ) {
@ -1096,7 +1097,7 @@ class WP_Theme_JSON {
} }
/** /**
* Returns the global styles custom css. * Returns the global styles custom CSS.
* *
* @since 6.2.0 * @since 6.2.0
* *
@ -1410,8 +1411,8 @@ class WP_Theme_JSON {
* *
* @since 5.9.0 * @since 5.9.0
* *
* @param array $setting_nodes Nodes with settings. * @param array $setting_nodes Nodes with settings.
* @param array $origins List of origins to process presets from. * @param string[] $origins List of origins to process presets from.
* @return string The new stylesheet. * @return string The new stylesheet.
*/ */
protected function get_preset_classes( $setting_nodes, $origins ) { protected function get_preset_classes( $setting_nodes, $origins ) {
@ -1447,8 +1448,8 @@ class WP_Theme_JSON {
* @since 5.8.0 * @since 5.8.0
* @since 5.9.0 Added the `$origins` parameter. * @since 5.9.0 Added the `$origins` parameter.
* *
* @param array $nodes Nodes with settings. * @param array $nodes Nodes with settings.
* @param array $origins List of origins to process. * @param string[] $origins List of origins to process.
* @return string The new stylesheet. * @return string The new stylesheet.
*/ */
protected function get_css_variables( $nodes, $origins ) { protected function get_css_variables( $nodes, $origins ) {
@ -1505,9 +1506,9 @@ class WP_Theme_JSON {
* @since 5.8.0 * @since 5.8.0
* @since 5.9.0 Added the `$origins` parameter. * @since 5.9.0 Added the `$origins` parameter.
* *
* @param array $settings Settings to process. * @param array $settings Settings to process.
* @param string $selector Selector wrapping the classes. * @param string $selector Selector wrapping the classes.
* @param array $origins List of origins to process. * @param string[] $origins List of origins to process.
* @return string The result of processing the presets. * @return string The result of processing the presets.
*/ */
protected static function compute_preset_classes( $settings, $selector, $origins ) { protected static function compute_preset_classes( $settings, $selector, $origins ) {
@ -1611,9 +1612,9 @@ class WP_Theme_JSON {
* *
* @since 5.9.0 * @since 5.9.0
* *
* @param array $settings Settings to process. * @param array $settings Settings to process.
* @param array $preset_metadata One of the PRESETS_METADATA values. * @param array $preset_metadata One of the PRESETS_METADATA values.
* @param array $origins List of origins to process. * @param string[] $origins List of origins to process.
* @return array Array of presets where each key is a slug and each value is the preset value. * @return array Array of presets where each key is a slug and each value is the preset value.
*/ */
protected static function get_settings_values_by_slug( $settings, $preset_metadata, $origins ) { protected static function get_settings_values_by_slug( $settings, $preset_metadata, $origins ) {
@ -1653,9 +1654,9 @@ class WP_Theme_JSON {
* *
* @since 5.9.0 * @since 5.9.0
* *
* @param array $settings Settings to process. * @param array $settings Settings to process.
* @param array $preset_metadata One of the PRESETS_METADATA values. * @param array $preset_metadata One of the PRESETS_METADATA values.
* @param array $origins List of origins to process. * @param string[] $origins List of origins to process.
* @return array Array of presets where the key and value are both the slug. * @return array Array of presets where the key and value are both the slug.
*/ */
protected static function get_settings_slugs( $settings, $preset_metadata, $origins = null ) { protected static function get_settings_slugs( $settings, $preset_metadata, $origins = null ) {
@ -1706,8 +1707,8 @@ class WP_Theme_JSON {
* @since 5.8.0 * @since 5.8.0
* @since 5.9.0 Added the `$origins` parameter. * @since 5.9.0 Added the `$origins` parameter.
* *
* @param array $settings Settings to process. * @param array $settings Settings to process.
* @param array $origins List of origins to process. * @param string[] $origins List of origins to process.
* @return array The modified $declarations. * @return array The modified $declarations.
*/ */
protected static function compute_preset_vars( $settings, $origins ) { protected static function compute_preset_vars( $settings, $origins ) {

8
wp-includes/global-styles-and-settings.php
View File

@ -21,7 +21,7 @@
* Valid values are 'all' (core, theme, and user) or 'base' (core and theme). * Valid values are 'all' (core, theme, and user) or 'base' (core and theme).
* If empty or unknown, 'all' is used. * If empty or unknown, 'all' is used.
* } * }
* @return array The settings to retrieve. * @return mixed The settings array or individual setting value to retrieve.
*/ */
function wp_get_global_settings( $path = array(), $context = array() ) { function wp_get_global_settings( $path = array(), $context = array() ) {
if ( ! empty( $context['block_name'] ) ) { if ( ! empty( $context['block_name'] ) ) {
@ -104,7 +104,7 @@ function wp_get_global_settings( $path = array(), $context = array() ) {
* Valid values are 'all' (core, theme, and user) or 'base' (core and theme). * Valid values are 'all' (core, theme, and user) or 'base' (core and theme).
* If empty or unknown, 'all' is used. * If empty or unknown, 'all' is used.
* } * }
* @return array The styles to retrieve. * @return mixed The styles array or individual style value to retrieve.
*/ */
function wp_get_global_styles( $path = array(), $context = array() ) { function wp_get_global_styles( $path = array(), $context = array() ) {
if ( ! empty( $context['block_name'] ) ) { if ( ! empty( $context['block_name'] ) ) {
@ -226,11 +226,11 @@ function wp_get_global_stylesheet( $types = array() ) {
} }
/** /**
* Gets the global styles custom css from theme.json. * Gets the global styles custom CSS from theme.json.
* *
* @since 6.2.0 * @since 6.2.0
* *
* @return string Stylesheet. * @return string The global styles custom CSS.
*/ */
function wp_get_global_styles_custom_css() { function wp_get_global_styles_custom_css() {
if ( ! wp_theme_has_theme_json() ) { if ( ! wp_theme_has_theme_json() ) {

27
wp-includes/shortcodes.php
View File

@ -308,8 +308,18 @@ function get_shortcode_regex( $tagnames = null ) {
* *
* @global array $shortcode_tags * @global array $shortcode_tags
* *
* @param array $m Regular expression match array. * @param array $m {
* @return string|false Shortcode output on success, false on failure. * Regular expression match array.
*
* @type string $0 Entire matched shortcode text.
* @type string $1 Optional second opening bracket for escaping shortcodes.
* @type string $2 Shortcode name.
* @type string $3 Shortcode arguments list.
* @type string $4 Optional self closing slash.
* @type string $5 Content of a shortcode when it wraps some content.
* @type string $6 Optional second closing brocket for escaping shortcodes.
* }
* @return string Shortcode output.
*/ */
function do_shortcode_tag( $m ) { function do_shortcode_tag( $m ) {
global $shortcode_tags; global $shortcode_tags;
@ -342,7 +352,7 @@ function do_shortcode_tag( $m ) {
* *
* @param false|string $output Short-circuit return value. Either false or the value to replace the shortcode with. * @param false|string $output Short-circuit return value. Either false or the value to replace the shortcode with.
* @param string $tag Shortcode name. * @param string $tag Shortcode name.
* @param array|string $attr Shortcode attributes array or empty string. * @param array|string $attr Shortcode attributes array or the original arguments string if it cannot be parsed.
* @param array $m Regular expression match array. * @param array $m Regular expression match array.
*/ */
$return = apply_filters( 'pre_do_shortcode_tag', false, $tag, $attr, $m ); $return = apply_filters( 'pre_do_shortcode_tag', false, $tag, $attr, $m );
@ -361,7 +371,7 @@ function do_shortcode_tag( $m ) {
* *
* @param string $output Shortcode output. * @param string $output Shortcode output.
* @param string $tag Shortcode name. * @param string $tag Shortcode name.
* @param array|string $attr Shortcode attributes array or empty string. * @param array|string $attr Shortcode attributes array or the original arguments string if it cannot be parsed.
* @param array $m Regular expression match array. * @param array $m Regular expression match array.
*/ */
return apply_filters( 'do_shortcode_tag', $output, $tag, $attr, $m ); return apply_filters( 'do_shortcode_tag', $output, $tag, $attr, $m );
@ -521,11 +531,10 @@ function get_shortcode_atts_regex() {
* *
* @since 2.5.0 * @since 2.5.0
* *
* @param string $text * @param string $text Shortcode arguments list.
* @return array|string List of attribute values. * @return array|string Array of attribute values keyed by attribute name.
* Returns empty array if '""' === trim( $text ). * Returns empty array if there are no attributes.
* Returns empty string if '' === trim( $text ). * Returns the original arguments string if it cannot be parsed.
* All other matches are checked for not empty().
*/ */
function shortcode_parse_atts( $text ) { function shortcode_parse_atts( $text ) {
$atts = array(); $atts = array();

2
wp-includes/version.php
View File

@ -16,7 +16,7 @@
* *
* @global string $wp_version * @global string $wp_version
*/ */
$wp_version = '6.3-alpha-55710'; $wp_version = '6.3-alpha-55711';
/** /**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.