Upstream
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues 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.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:
* - `variables`: only the CSS Custom Properties for presets & custom ones.
* - `styles`: only the styles section in theme.json.
* - `presets`: only the classes for the presets.
* @param array $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).
* The options currently supported are 'scope' that makes sure all style are scoped to a given selector,
* and root_selector which overwrites and forces a given selector to be used on the root node.
* @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.
* - `styles`: only the styles section in theme.json.
* - `presets`: only the classes for the presets.
* @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).
* The options currently supported are 'scope' that makes sure all style are scoped to a
* given selector, and root_selector which overwrites and forces a given selector to be
* used on the root node.
* @return string The resulting stylesheet.
*/
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
*
@ -1410,8 +1411,8 @@ class WP_Theme_JSON {
*
* @since 5.9.0
*
* @param array $setting_nodes Nodes with settings.
* @param array $origins List of origins to process presets from.
* @param array $setting_nodes Nodes with settings.
* @param string[] $origins List of origins to process presets from.
* @return string The new stylesheet.
*/
protected function get_preset_classes( $setting_nodes, $origins ) {
@ -1447,8 +1448,8 @@ class WP_Theme_JSON {
* @since 5.8.0
* @since 5.9.0 Added the `$origins` parameter.
*
* @param array $nodes Nodes with settings.
* @param array $origins List of origins to process.
* @param array $nodes Nodes with settings.
* @param string[] $origins List of origins to process.
* @return string The new stylesheet.
*/
protected function get_css_variables( $nodes, $origins ) {
@ -1505,9 +1506,9 @@ class WP_Theme_JSON {
* @since 5.8.0
* @since 5.9.0 Added the `$origins` parameter.
*
* @param array $settings Settings to process.
* @param string $selector Selector wrapping the classes.
* @param array $origins List of origins to process.
* @param array $settings Settings to process.
* @param string $selector Selector wrapping the classes.
* @param string[] $origins List of origins to process.
* @return string The result of processing the presets.
*/
protected static function compute_preset_classes( $settings, $selector, $origins ) {
@ -1611,9 +1612,9 @@ class WP_Theme_JSON {
*
* @since 5.9.0
*
* @param array $settings Settings to process.
* @param array $preset_metadata One of the PRESETS_METADATA values.
* @param array $origins List of origins to process.
* @param array $settings Settings to process.
* @param array $preset_metadata One of the PRESETS_METADATA values.
* @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.
*/
protected static function get_settings_values_by_slug( $settings, $preset_metadata, $origins ) {
@ -1653,9 +1654,9 @@ class WP_Theme_JSON {
*
* @since 5.9.0
*
* @param array $settings Settings to process.
* @param array $preset_metadata One of the PRESETS_METADATA values.
* @param array $origins List of origins to process.
* @param array $settings Settings to process.
* @param array $preset_metadata One of the PRESETS_METADATA values.
* @param string[] $origins List of origins to process.
* @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 ) {
@ -1706,8 +1707,8 @@ class WP_Theme_JSON {
* @since 5.8.0
* @since 5.9.0 Added the `$origins` parameter.
*
* @param array $settings Settings to process.
* @param array $origins List of origins to process.
* @param array $settings Settings to process.
* @param string[] $origins List of origins to process.
* @return array The modified $declarations.
*/
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).
* 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() ) {
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).
* 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() ) {
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
*
* @return string Stylesheet.
* @return string The global styles custom CSS.
*/
function wp_get_global_styles_custom_css() {
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
*
* @param array $m Regular expression match array.
* @return string|false Shortcode output on success, false on failure.
* @param array $m {
* 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 ) {
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 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.
*/
$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 $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.
*/
return apply_filters( 'do_shortcode_tag', $output, $tag, $attr, $m );
@ -521,11 +531,10 @@ function get_shortcode_atts_regex() {
*
* @since 2.5.0
*
* @param string $text
* @return array|string List of attribute values.
* Returns empty array if '""' === trim( $text ).
* Returns empty string if '' === trim( $text ).
* All other matches are checked for not empty().
* @param string $text Shortcode arguments list.
* @return array|string Array of attribute values keyed by attribute name.
* Returns empty array if there are no attributes.
* Returns the original arguments string if it cannot be parsed.
*/
function shortcode_parse_atts( $text ) {
$atts = array();

2
wp-includes/version.php
View File

@ -16,7 +16,7 @@
*
* @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.