Commit 4617455730 for wordpress.org
commit 46174557309b22831d3a11672ec4a1b6dbda75c6
Author: Weston Ruter <weston@xwp.co>
Date: Tue Nov 25 05:02:32 2025 +0000
Bundled Themes: Add missing `@return` tags and descriptions.
Developed in https://github.com/WordPress/wordpress-develop/pull/10533
Props huzaifaalmesbah, sabernhardt, palak678, westonruter.
See #64224.
Fixes #64277.
Built from https://develop.svn.wordpress.org/trunk@61302
git-svn-id: http://core.svn.wordpress.org/trunk@60614 1a063a9b-81f0-0310-95a4-ce76da25c4cd
diff --git a/wp-content/themes/twentyeleven/functions.php b/wp-content/themes/twentyeleven/functions.php
index d1656fd2c1..c52da6e1f1 100644
--- a/wp-content/themes/twentyeleven/functions.php
+++ b/wp-content/themes/twentyeleven/functions.php
@@ -988,7 +988,9 @@ if ( ! function_exists( 'wp_get_list_item_separator' ) ) :
*
* Added for backward compatibility to support pre-6.0.0 WordPress versions.
*
- * @since 6.0.0
+ * @since Twenty Eleven 4.1
+ *
+ * @return string Locale-specific list item separator.
*/
function wp_get_list_item_separator() {
/* translators: Used between list items, there is a space after the comma. */
diff --git a/wp-content/themes/twentyfifteen/functions.php b/wp-content/themes/twentyfifteen/functions.php
index a78aa5fb2f..883e7d78f3 100644
--- a/wp-content/themes/twentyfifteen/functions.php
+++ b/wp-content/themes/twentyfifteen/functions.php
@@ -366,7 +366,7 @@ if ( ! function_exists( 'twentyfifteen_fonts_url' ) ) :
* @since Twenty Fifteen 1.0
* @since Twenty Fifteen 3.4 Replaced Google URL with self-hosted fonts.
*
- * @return string Fonts URL for the theme.
+ * @return string Font stylesheet URL or empty string if disabled.
*/
function twentyfifteen_fonts_url() {
$fonts_url = '';
diff --git a/wp-content/themes/twentyfourteen/functions.php b/wp-content/themes/twentyfourteen/functions.php
index ba4d9e1c11..27b6190bb4 100644
--- a/wp-content/themes/twentyfourteen/functions.php
+++ b/wp-content/themes/twentyfourteen/functions.php
@@ -315,7 +315,7 @@ if ( ! function_exists( 'twentyfourteen_font_url' ) ) :
* @since Twenty Fourteen 1.0
* @since Twenty Fourteen 3.6 Replaced Google URL with self-hosted fonts.
*
- * @return string
+ * @return string Font stylesheet URL or empty string if disabled.
*/
function twentyfourteen_font_url() {
$font_url = '';
@@ -755,6 +755,8 @@ if ( ! class_exists( 'Featured_Content' ) && 'plugins.php' !== $GLOBALS['pagenow
* `is_customize_preview` function was introduced.
*
* @global WP_Customize_Manager $wp_customize Customizer object.
+ *
+ * @return bool Whether the site is being previewed in the Customizer.
*/
if ( ! function_exists( 'is_customize_preview' ) ) :
function is_customize_preview() {
diff --git a/wp-content/themes/twentyfourteen/inc/widgets.php b/wp-content/themes/twentyfourteen/inc/widgets.php
index 3a5cb958bc..7c4f237294 100644
--- a/wp-content/themes/twentyfourteen/inc/widgets.php
+++ b/wp-content/themes/twentyfourteen/inc/widgets.php
@@ -26,7 +26,7 @@ class Twenty_Fourteen_Ephemera_Widget extends WP_Widget {
*
* @since Twenty Fourteen 1.0
*
- * @return Twenty_Fourteen_Ephemera_Widget
+ * @return Twenty_Fourteen_Ephemera_Widget Widget instance.
*/
public function __construct() {
parent::__construct(
diff --git a/wp-content/themes/twentynineteen/classes/class-twentynineteen-svg-icons.php b/wp-content/themes/twentynineteen/classes/class-twentynineteen-svg-icons.php
index eaca9fb414..e150d1b037 100644
--- a/wp-content/themes/twentynineteen/classes/class-twentynineteen-svg-icons.php
+++ b/wp-content/themes/twentynineteen/classes/class-twentynineteen-svg-icons.php
@@ -27,6 +27,7 @@ class TwentyNineteen_SVG_Icons {
* @param string $group The group of icons ('ui' or 'social').
* @param string $icon The specific icon to retrieve.
* @param int $size The desired width and height for the SVG icon.
+ * @return string|null SVG code for the icon, or null if not found.
*/
public static function get_svg( $group, $icon, $size ) {
if ( 'ui' === $group ) {
@@ -51,6 +52,7 @@ class TwentyNineteen_SVG_Icons {
*
* @param string $uri The URL of the social network link.
* @param int $size The desired width and height for the SVG icon.
+ * @return string|null SVG code for the social link icon, or null if not found.
*/
public static function get_social_link_svg( $uri, $size ) {
static $regex_map; // Only compute regex map once, for performance.
diff --git a/wp-content/themes/twentynineteen/functions.php b/wp-content/themes/twentynineteen/functions.php
index 75525a2bd5..bf9dd0253c 100644
--- a/wp-content/themes/twentynineteen/functions.php
+++ b/wp-content/themes/twentynineteen/functions.php
@@ -181,7 +181,9 @@ if ( ! function_exists( 'wp_get_list_item_separator' ) ) :
*
* Added for backward compatibility to support pre-6.0.0 WordPress versions.
*
- * @since 6.0.0
+ * @since Twenty Nineteen 2.3
+ *
+ * @return string Locale-specific list item separator.
*/
function wp_get_list_item_separator() {
/* translators: Used between list items, there is a space after the comma. */
diff --git a/wp-content/themes/twentynineteen/inc/customizer.php b/wp-content/themes/twentynineteen/inc/customizer.php
index d45bcd0d51..568eb342d3 100644
--- a/wp-content/themes/twentynineteen/inc/customizer.php
+++ b/wp-content/themes/twentynineteen/inc/customizer.php
@@ -142,7 +142,7 @@ add_action( 'customize_controls_enqueue_scripts', 'twentynineteen_panels_js' );
* Sanitizes custom color choice.
*
* @param string $choice Whether image filter is active.
- * @return string
+ * @return string Sanitized color option.
*/
function twentynineteen_sanitize_color_option( $choice ) {
$valid = array(
diff --git a/wp-content/themes/twentynineteen/inc/template-functions.php b/wp-content/themes/twentynineteen/inc/template-functions.php
index 7225105677..8e9a732f61 100644
--- a/wp-content/themes/twentynineteen/inc/template-functions.php
+++ b/wp-content/themes/twentynineteen/inc/template-functions.php
@@ -11,7 +11,7 @@
* Adds custom classes to the array of body classes.
*
* @param array $classes Classes for the body element.
- * @return array
+ * @return string[] The filtered body class list.
*/
function twentynineteen_body_classes( $classes ) {
diff --git a/wp-content/themes/twentyseventeen/functions.php b/wp-content/themes/twentyseventeen/functions.php
index 0b2005d50c..9e322b0ef9 100644
--- a/wp-content/themes/twentyseventeen/functions.php
+++ b/wp-content/themes/twentyseventeen/functions.php
@@ -289,7 +289,7 @@ if ( ! function_exists( 'twentyseventeen_fonts_url' ) ) :
* @since Twenty Seventeen 1.0
* @since Twenty Seventeen 3.2 Replaced Google URL with self-hosted fonts.
*
- * @return string Fonts URL for the theme.
+ * @return string Font stylesheet URL or empty string if disabled.
*/
function twentyseventeen_fonts_url() {
$fonts_url = '';
@@ -681,7 +681,9 @@ if ( ! function_exists( 'wp_get_list_item_separator' ) ) :
*
* Added for backward compatibility to support pre-6.0.0 WordPress versions.
*
- * @since 6.0.0
+ * @since Twenty Seventeen 3.0
+ *
+ * @return string Locale-specific list item separator.
*/
function wp_get_list_item_separator() {
/* translators: Used between list items, there is a space after the comma. */
diff --git a/wp-content/themes/twentyseventeen/inc/template-functions.php b/wp-content/themes/twentyseventeen/inc/template-functions.php
index 6b61eae85b..8962bca3d2 100644
--- a/wp-content/themes/twentyseventeen/inc/template-functions.php
+++ b/wp-content/themes/twentyseventeen/inc/template-functions.php
@@ -11,7 +11,7 @@
* Adds custom classes to the array of body classes.
*
* @param array $classes Classes for the body element.
- * @return array
+ * @return string[] Filtered body classes with theme-specific additions.
*/
function twentyseventeen_body_classes( $classes ) {
// Add class of group-blog to blogs with more than 1 published author.
diff --git a/wp-content/themes/twentyseventeen/inc/template-tags.php b/wp-content/themes/twentyseventeen/inc/template-tags.php
index a8bdac3d7c..6cdb6c6be5 100644
--- a/wp-content/themes/twentyseventeen/inc/template-tags.php
+++ b/wp-content/themes/twentyseventeen/inc/template-tags.php
@@ -184,7 +184,7 @@ function twentyseventeen_front_page_section( $partial = null, $id = 0 ) {
/**
* Returns true if a blog has more than 1 category.
*
- * @return bool
+ * @return bool Whether the blog has more than 1 category.
*/
function twentyseventeen_categorized_blog() {
$category_count = get_transient( 'twentyseventeen_categories' );
diff --git a/wp-content/themes/twentysixteen/functions.php b/wp-content/themes/twentysixteen/functions.php
index 8572194b87..f1cc981d18 100644
--- a/wp-content/themes/twentysixteen/functions.php
+++ b/wp-content/themes/twentysixteen/functions.php
@@ -334,7 +334,7 @@ if ( ! function_exists( 'twentysixteen_fonts_url' ) ) :
* @since Twenty Sixteen 1.0
* @since Twenty Sixteen 2.9 Replaced Google URL with self-hosted fonts.
*
- * @return string Fonts URL for the theme.
+ * @return string Font stylesheet URL or empty string if disabled.
*/
function twentysixteen_fonts_url() {
$fonts_url = '';
diff --git a/wp-content/themes/twentythirteen/functions.php b/wp-content/themes/twentythirteen/functions.php
index 1283ed267a..34a1facb8b 100644
--- a/wp-content/themes/twentythirteen/functions.php
+++ b/wp-content/themes/twentythirteen/functions.php
@@ -270,7 +270,7 @@ if ( ! function_exists( 'twentythirteen_fonts_url' ) ) :
* @since Twenty Thirteen 1.0
* @since Twenty Thirteen 3.8 Replaced Google URL with self-hosted fonts.
*
- * @return string Font stylesheet or empty string if disabled.
+ * @return string Font stylesheet URL or empty string if disabled.
*/
function twentythirteen_fonts_url() {
$fonts_url = '';
@@ -473,7 +473,9 @@ if ( ! function_exists( 'wp_get_list_item_separator' ) ) :
*
* Added for backward compatibility to support pre-6.0.0 WordPress versions.
*
- * @since 6.0.0
+ * @since Twenty Thirteen 3.7
+ *
+ * @return string Locale-specific list item separator.
*/
function wp_get_list_item_separator() {
/* translators: Used between list items, there is a space after the comma. */
diff --git a/wp-content/themes/twentytwelve/functions.php b/wp-content/themes/twentytwelve/functions.php
index c3d5043c3a..ce98c577b3 100644
--- a/wp-content/themes/twentytwelve/functions.php
+++ b/wp-content/themes/twentytwelve/functions.php
@@ -160,7 +160,7 @@ if ( ! function_exists( 'twentytwelve_get_font_url' ) ) :
* @since Twenty Twelve 1.2
* @since Twenty Twelve 3.9 Replaced Google URL with self-hosted font.
*
- * @return string Font stylesheet or empty string if disabled.
+ * @return string Font stylesheet URL or empty string if disabled.
*/
function twentytwelve_get_font_url() {
$font_url = '';
@@ -396,7 +396,9 @@ if ( ! function_exists( 'wp_get_list_item_separator' ) ) :
*
* Added for backward compatibility to support pre-6.0.0 WordPress versions.
*
- * @since 6.0.0
+ * @since Twenty Twelve 3.7
+ *
+ * @return string Locale-specific list item separator.
*/
function wp_get_list_item_separator() {
/* translators: Used between list items, there is a space after the comma. */
diff --git a/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php b/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php
index 6cdd2d0017..1ae2858bdc 100644
--- a/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php
+++ b/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php
@@ -459,7 +459,7 @@ if ( ! class_exists( 'TwentyTwenty_Customize' ) ) {
* @since Twenty Twenty 1.0
*
* @param bool $checked Whether or not a box is checked.
- * @return bool
+ * @return bool Whether the checkbox is checked.
*/
public static function sanitize_checkbox( $checked ) {
return ( ( isset( $checked ) && true === $checked ) ? true : false );
diff --git a/wp-content/themes/twentytwenty/functions.php b/wp-content/themes/twentytwenty/functions.php
index 1a5c512f8b..754516009c 100644
--- a/wp-content/themes/twentytwenty/functions.php
+++ b/wp-content/themes/twentytwenty/functions.php
@@ -304,7 +304,7 @@ add_action( 'init', 'twentytwenty_menus' );
* @since Twenty Twenty 1.0
*
* @param string $html The HTML output from get_custom_logo() (core function).
- * @return string
+ * @return string Custom logo HTML with "retina" resolution applied if enabled.
*/
function twentytwenty_get_custom_logo( $html ) {
@@ -635,7 +635,7 @@ add_action( 'after_setup_theme', 'twentytwenty_block_editor_settings' );
* Overwrite default more tag with styling and screen reader markup.
*
* @param string $html The default output HTML for the more tag.
- * @return string
+ * @return string The the read more link wrapped in a `div`.
*/
function twentytwenty_read_more_tag( $html ) {
return preg_replace( '/<a(.*)>(.*)<\/a>/iU', sprintf( '<div class="read-more-button-wrap"><a$1><span class="faux-button">$2</span> <span class="screen-reader-text">"%1$s"</span></a></div>', get_the_title( get_the_ID() ) ), $html );
@@ -736,7 +736,7 @@ function twentytwenty_get_color_for_area( $area = 'content', $context = 'text' )
*
* @since Twenty Twenty 1.0
*
- * @return array
+ * @return array Customizer color variables for the preview.
*/
function twentytwenty_get_customizer_color_vars() {
$colors = array(
@@ -755,7 +755,7 @@ function twentytwenty_get_customizer_color_vars() {
*
* @since Twenty Twenty 1.0
*
- * @return array
+ * @return array Elements to apply custom colors to.
*/
function twentytwenty_get_elements_array() {
diff --git a/wp-content/themes/twentytwenty/inc/custom-css.php b/wp-content/themes/twentytwenty/inc/custom-css.php
index 9f08898c3c..7817b08dfd 100644
--- a/wp-content/themes/twentytwenty/inc/custom-css.php
+++ b/wp-content/themes/twentytwenty/inc/custom-css.php
@@ -20,6 +20,7 @@ if ( ! function_exists( 'twentytwenty_generate_css' ) ) {
* @param string $prefix The CSS prefix.
* @param string $suffix The CSS suffix.
* @param bool $display Print the styles.
+ * @return string Generated CSS.
*/
function twentytwenty_generate_css( $selector, $style, $value, $prefix = '', $suffix = '', $display = true ) {
@@ -54,6 +55,7 @@ if ( ! function_exists( 'twentytwenty_get_customizer_css' ) ) {
* @since Twenty Twenty 1.0
*
* @param string $type Whether to return CSS for the "front-end", "block-editor", or "classic-editor".
+ * @return string CSS styles built from Customizer options.
*/
function twentytwenty_get_customizer_css( $type = 'front-end' ) {
diff --git a/wp-content/themes/twentytwenty/inc/template-tags.php b/wp-content/themes/twentytwenty/inc/template-tags.php
index 23f30df802..f348747c82 100644
--- a/wp-content/themes/twentytwenty/inc/template-tags.php
+++ b/wp-content/themes/twentytwenty/inc/template-tags.php
@@ -148,7 +148,7 @@ function twentytwenty_site_description( $display = true ) {
* @since Twenty Twenty 1.0
*
* @param object $comment Comment data.
- * @return bool
+ * @return bool Whether the comment is by the post author.
*/
function twentytwenty_is_comment_by_post_author( $comment = null ) {
@@ -249,6 +249,7 @@ add_filter( 'edit_post_link', 'twentytwenty_edit_post_link', 10, 3 );
*
* @param int $post_id The ID of the post.
* @param string $location The location where the meta is shown.
+ * @return string Post meta HTML.
*/
function twentytwenty_get_post_meta( $post_id = null, $location = 'single-top' ) {
diff --git a/wp-content/themes/twentytwentyone/functions.php b/wp-content/themes/twentytwentyone/functions.php
index 02d2a1dc9b..301aefca5c 100644
--- a/wp-content/themes/twentytwentyone/functions.php
+++ b/wp-content/themes/twentytwentyone/functions.php
@@ -655,7 +655,9 @@ if ( ! function_exists( 'wp_get_list_item_separator' ) ) :
*
* Added for backward compatibility to support pre-6.0.0 WordPress versions.
*
- * @since 6.0.0
+ * @since Twenty Twenty-One 1.6
+ *
+ * @return string Locale-specific list item separator.
*/
function wp_get_list_item_separator() {
/* translators: Used between list items, there is a space after the comma. */
diff --git a/wp-content/themes/twentytwentyone/inc/custom-css.php b/wp-content/themes/twentytwentyone/inc/custom-css.php
index 02445bdfac..e212cfd606 100644
--- a/wp-content/themes/twentytwentyone/inc/custom-css.php
+++ b/wp-content/themes/twentytwentyone/inc/custom-css.php
@@ -18,7 +18,7 @@
* @param string $prefix The CSS prefix.
* @param string $suffix The CSS suffix.
* @param bool $display Print the styles.
- * @return string
+ * @return string Generated CSS.
*/
function twenty_twenty_one_generate_css( $selector, $style, $value, $prefix = '', $suffix = '', $display = true ) {
diff --git a/wp-content/themes/twentytwentyone/inc/template-functions.php b/wp-content/themes/twentytwentyone/inc/template-functions.php
index d7284de961..689b1e22c9 100644
--- a/wp-content/themes/twentytwentyone/inc/template-functions.php
+++ b/wp-content/themes/twentytwentyone/inc/template-functions.php
@@ -13,7 +13,7 @@
* @since Twenty Twenty-One 1.0
*
* @param array $classes Classes for the body element.
- * @return array
+ * @return string[] Body classes with theme-specific additions.
*/
function twenty_twenty_one_body_classes( $classes ) {
@@ -43,7 +43,7 @@ add_filter( 'body_class', 'twenty_twenty_one_body_classes' );
* @since Twenty Twenty-One 1.0
*
* @param array $classes An array of CSS classes.
- * @return array
+ * @return string[] Post classes with 'entry' class added.
*/
function twenty_twenty_one_post_classes( $classes ) {
$classes[] = 'entry';
@@ -91,7 +91,7 @@ add_action( 'wp_footer', 'twenty_twenty_one_supports_js' );
* @since Twenty Twenty-One 1.0
*
* @param array $defaults The form defaults.
- * @return array
+ * @return array Comment form defaults with adjusted textarea height.
*/
function twenty_twenty_one_comment_form_defaults( $defaults ) {
@@ -200,7 +200,7 @@ add_filter( 'the_title', 'twenty_twenty_one_post_title' );
* @param string $group The icon group.
* @param string $icon The icon.
* @param int $size The icon size in pixels.
- * @return string
+ * @return string SVG code for the requested icon.
*/
function twenty_twenty_one_get_icon_svg( $group, $icon, $size = 24 ) {
return Twenty_Twenty_One_SVG_Icons::get_svg( $group, $icon, $size );
@@ -212,7 +212,7 @@ function twenty_twenty_one_get_icon_svg( $group, $icon, $size = 24 ) {
* @since Twenty Twenty-One 1.0
*
* @param string $calendar_output The generated HTML of the calendar.
- * @return string
+ * @return string Calendar HTML with SVG navigation arrows.
*/
function twenty_twenty_one_change_calendar_nav_arrows( $calendar_output ) {
$calendar_output = str_replace( '« ', is_rtl() ? twenty_twenty_one_get_icon_svg( 'ui', 'arrow_right' ) : twenty_twenty_one_get_icon_svg( 'ui', 'arrow_left' ), $calendar_output );
@@ -229,7 +229,7 @@ add_filter( 'get_calendar', 'twenty_twenty_one_change_calendar_nav_arrows' );
* @since Twenty Twenty-One 1.0
*
* @param string $type Whether to return CSS for the "front-end", "block-editor", or "classic-editor".
- * @return string
+ * @return string CSS styles for non-Latin languages based on the site locale.
*/
function twenty_twenty_one_get_non_latin_css( $type = 'front-end' ) {
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 7e669e1f9f..c0f35c19c7 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
-$wp_version = '7.0-alpha-61301';
+$wp_version = '7.0-alpha-61302';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.