From 5b1a82112ca80ee405191518d3531087a4351060 Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Thu, 20 Nov 2025 06:34:51 +0600 Subject: [PATCH 1/7] Docs: Add missing @return descriptions in bundled themes. Adds missing descriptions to tags and adds missing tags in various files across Twenty Fourteen, Twenty Seventeen, Twenty Nineteen, Twenty Twenty, and Twenty Twenty-One to comply with WordPress PHP Documentation Standards. --- src/wp-content/themes/twentyfourteen/functions.php | 4 +++- src/wp-content/themes/twentyfourteen/inc/widgets.php | 2 +- .../classes/class-twentynineteen-svg-icons.php | 2 ++ src/wp-content/themes/twentynineteen/functions.php | 2 ++ .../themes/twentynineteen/inc/customizer.php | 2 +- .../themes/twentynineteen/inc/template-functions.php | 2 +- .../twentyseventeen/inc/template-functions.php | 2 +- .../themes/twentyseventeen/inc/template-tags.php | 2 +- .../classes/class-twentytwenty-customize.php | 2 +- src/wp-content/themes/twentytwenty/functions.php | 8 ++++---- .../themes/twentytwenty/inc/template-tags.php | 3 ++- .../twentytwentyone/inc/template-functions.php | 12 ++++++------ 12 files changed, 25 insertions(+), 18 deletions(-) diff --git a/src/wp-content/themes/twentyfourteen/functions.php b/src/wp-content/themes/twentyfourteen/functions.php index ba4d9e1c1199c..8cbdc437dc327 100644 --- a/src/wp-content/themes/twentyfourteen/functions.php +++ b/src/wp-content/themes/twentyfourteen/functions.php @@ -315,7 +315,7 @@ function twentyfourteen_widgets_init() { * @since Twenty Fourteen 1.0 * @since Twenty Fourteen 3.6 Replaced Google URL with self-hosted fonts. * - * @return string + * @return string Fonts URL for the theme. */ function twentyfourteen_font_url() { $font_url = ''; @@ -755,6 +755,8 @@ function twentyfourteen_register_block_patterns() { * `is_customize_preview` function was introduced. * * @global WP_Customize_Manager $wp_customize Customizer object. + * + * @return bool True if the site is being previewed in the Customizer, false otherwise. */ if ( ! function_exists( 'is_customize_preview' ) ) : function is_customize_preview() { diff --git a/src/wp-content/themes/twentyfourteen/inc/widgets.php b/src/wp-content/themes/twentyfourteen/inc/widgets.php index 3a5cb958bc6a2..7c4f237294b3a 100644 --- a/src/wp-content/themes/twentyfourteen/inc/widgets.php +++ b/src/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/src/wp-content/themes/twentynineteen/classes/class-twentynineteen-svg-icons.php b/src/wp-content/themes/twentynineteen/classes/class-twentynineteen-svg-icons.php index eaca9fb414eef..e150d1b037630 100644 --- a/src/wp-content/themes/twentynineteen/classes/class-twentynineteen-svg-icons.php +++ b/src/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 @@ public static function get_svg( $group, $icon, $size ) { * * @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/src/wp-content/themes/twentynineteen/functions.php b/src/wp-content/themes/twentynineteen/functions.php index 75525a2bd5062..e59e531ab6f37 100644 --- a/src/wp-content/themes/twentynineteen/functions.php +++ b/src/wp-content/themes/twentynineteen/functions.php @@ -182,6 +182,8 @@ function twentynineteen_setup() { * Added for backward compatibility to support pre-6.0.0 WordPress versions. * * @since 6.0.0 + * + * @return string List item separator. */ function wp_get_list_item_separator() { /* translators: Used between list items, there is a space after the comma. */ diff --git a/src/wp-content/themes/twentynineteen/inc/customizer.php b/src/wp-content/themes/twentynineteen/inc/customizer.php index d45bcd0d515b1..568eb342d3dd0 100644 --- a/src/wp-content/themes/twentynineteen/inc/customizer.php +++ b/src/wp-content/themes/twentynineteen/inc/customizer.php @@ -142,7 +142,7 @@ function 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/src/wp-content/themes/twentynineteen/inc/template-functions.php b/src/wp-content/themes/twentynineteen/inc/template-functions.php index 72251056770b0..d07b8dc639174 100644 --- a/src/wp-content/themes/twentynineteen/inc/template-functions.php +++ b/src/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 array The filtered body class list. */ function twentynineteen_body_classes( $classes ) { diff --git a/src/wp-content/themes/twentyseventeen/inc/template-functions.php b/src/wp-content/themes/twentyseventeen/inc/template-functions.php index 6b61eae85b239..32c813187b074 100644 --- a/src/wp-content/themes/twentyseventeen/inc/template-functions.php +++ b/src/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 array 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/src/wp-content/themes/twentyseventeen/inc/template-tags.php b/src/wp-content/themes/twentyseventeen/inc/template-tags.php index a8bdac3d7c34f..18e2bca29c35e 100644 --- a/src/wp-content/themes/twentyseventeen/inc/template-tags.php +++ b/src/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 True if the blog has more than 1 category, false otherwise. */ function twentyseventeen_categorized_blog() { $category_count = get_transient( 'twentyseventeen_categories' ); diff --git a/src/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php b/src/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php index 6cdd2d0017a69..63dbb988aad78 100644 --- a/src/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php +++ b/src/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php @@ -459,7 +459,7 @@ public static function sanitize_select( $input, $setting ) { * @since Twenty Twenty 1.0 * * @param bool $checked Whether or not a box is checked. - * @return bool + * @return bool True if the checkbox is checked, false otherwise. */ public static function sanitize_checkbox( $checked ) { return ( ( isset( $checked ) && true === $checked ) ? true : false ); diff --git a/src/wp-content/themes/twentytwenty/functions.php b/src/wp-content/themes/twentytwenty/functions.php index 1a5c512f8b177..f9b970a06210c 100644 --- a/src/wp-content/themes/twentytwenty/functions.php +++ b/src/wp-content/themes/twentytwenty/functions.php @@ -304,7 +304,7 @@ function 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 support. */ function twentytwenty_get_custom_logo( $html ) { @@ -635,7 +635,7 @@ function 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 filtered HTML of the more tag, wrapped in a wrapper div. */ function twentytwenty_read_more_tag( $html ) { return preg_replace( '/(.*)<\/a>/iU', sprintf( '
$2 "%1$s"
', 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/src/wp-content/themes/twentytwenty/inc/template-tags.php b/src/wp-content/themes/twentytwenty/inc/template-tags.php index 23f30df80272a..12c8fa5b09f2c 100644 --- a/src/wp-content/themes/twentytwenty/inc/template-tags.php +++ b/src/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 True if the comment is by the post author, false otherwise. */ function twentytwenty_is_comment_by_post_author( $comment = null ) { @@ -249,6 +249,7 @@ function twentytwenty_edit_post_link( $link, $post_id, $text ) { * * @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/src/wp-content/themes/twentytwentyone/inc/template-functions.php b/src/wp-content/themes/twentytwentyone/inc/template-functions.php index d7284de961ed1..56b03a28003ac 100644 --- a/src/wp-content/themes/twentytwentyone/inc/template-functions.php +++ b/src/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 array Filtered body classes with theme-specific additions. */ function twenty_twenty_one_body_classes( $classes ) { @@ -43,7 +43,7 @@ function twenty_twenty_one_body_classes( $classes ) { * @since Twenty Twenty-One 1.0 * * @param array $classes An array of CSS classes. - * @return array + * @return array Filtered post classes with 'entry' class added. */ function twenty_twenty_one_post_classes( $classes ) { $classes[] = 'entry'; @@ -91,7 +91,7 @@ function 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 @@ function twenty_twenty_one_post_title( $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 @@ function twenty_twenty_one_change_calendar_nav_arrows( $calendar_output ) { * @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' ) { From b697495615fab6d89cbbefe8fcd769aacc865c6e Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Thu, 20 Nov 2025 07:40:06 +0600 Subject: [PATCH 2/7] Apply suggestions from code review Co-authored-by: Weston Ruter --- src/wp-content/themes/twentyfourteen/functions.php | 2 +- .../themes/twentynineteen/inc/template-functions.php | 2 +- .../themes/twentyseventeen/inc/template-functions.php | 2 +- src/wp-content/themes/twentyseventeen/inc/template-tags.php | 2 +- .../twentytwenty/classes/class-twentytwenty-customize.php | 2 +- src/wp-content/themes/twentytwenty/functions.php | 4 ++-- src/wp-content/themes/twentytwenty/inc/template-tags.php | 2 +- .../themes/twentytwentyone/inc/template-functions.php | 4 ++-- 8 files changed, 10 insertions(+), 10 deletions(-) diff --git a/src/wp-content/themes/twentyfourteen/functions.php b/src/wp-content/themes/twentyfourteen/functions.php index 8cbdc437dc327..4f179d7622523 100644 --- a/src/wp-content/themes/twentyfourteen/functions.php +++ b/src/wp-content/themes/twentyfourteen/functions.php @@ -756,7 +756,7 @@ function twentyfourteen_register_block_patterns() { * * @global WP_Customize_Manager $wp_customize Customizer object. * - * @return bool True if the site is being previewed in the Customizer, false otherwise. + * @return bool Whether the site is being previewed in the Customizer. */ if ( ! function_exists( 'is_customize_preview' ) ) : function is_customize_preview() { diff --git a/src/wp-content/themes/twentynineteen/inc/template-functions.php b/src/wp-content/themes/twentynineteen/inc/template-functions.php index d07b8dc639174..8e9a732f6116e 100644 --- a/src/wp-content/themes/twentynineteen/inc/template-functions.php +++ b/src/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 The filtered body class list. + * @return string[] The filtered body class list. */ function twentynineteen_body_classes( $classes ) { diff --git a/src/wp-content/themes/twentyseventeen/inc/template-functions.php b/src/wp-content/themes/twentyseventeen/inc/template-functions.php index 32c813187b074..8962bca3d2a50 100644 --- a/src/wp-content/themes/twentyseventeen/inc/template-functions.php +++ b/src/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 Filtered body classes with theme-specific additions. + * @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/src/wp-content/themes/twentyseventeen/inc/template-tags.php b/src/wp-content/themes/twentyseventeen/inc/template-tags.php index 18e2bca29c35e..6cdb6c6be5a53 100644 --- a/src/wp-content/themes/twentyseventeen/inc/template-tags.php +++ b/src/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 True if the blog has more than 1 category, false otherwise. + * @return bool Whether the blog has more than 1 category. */ function twentyseventeen_categorized_blog() { $category_count = get_transient( 'twentyseventeen_categories' ); diff --git a/src/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php b/src/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php index 63dbb988aad78..1ae2858bdc52b 100644 --- a/src/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php +++ b/src/wp-content/themes/twentytwenty/classes/class-twentytwenty-customize.php @@ -459,7 +459,7 @@ public static function sanitize_select( $input, $setting ) { * @since Twenty Twenty 1.0 * * @param bool $checked Whether or not a box is checked. - * @return bool True if the checkbox is checked, false otherwise. + * @return bool Whether the checkbox is checked. */ public static function sanitize_checkbox( $checked ) { return ( ( isset( $checked ) && true === $checked ) ? true : false ); diff --git a/src/wp-content/themes/twentytwenty/functions.php b/src/wp-content/themes/twentytwenty/functions.php index f9b970a06210c..74bc1efef715c 100644 --- a/src/wp-content/themes/twentytwenty/functions.php +++ b/src/wp-content/themes/twentytwenty/functions.php @@ -304,7 +304,7 @@ function twentytwenty_menus() { * @since Twenty Twenty 1.0 * * @param string $html The HTML output from get_custom_logo() (core function). - * @return string Custom logo HTML with retina support. + * @return string|false Custom logo HTML or false if not available. */ function twentytwenty_get_custom_logo( $html ) { @@ -635,7 +635,7 @@ function 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 The filtered HTML of the more tag, wrapped in a wrapper div. + * @return string The the read more link wrapped in a `div`. */ function twentytwenty_read_more_tag( $html ) { return preg_replace( '/(.*)<\/a>/iU', sprintf( '
$2 "%1$s"
', get_the_title( get_the_ID() ) ), $html ); diff --git a/src/wp-content/themes/twentytwenty/inc/template-tags.php b/src/wp-content/themes/twentytwenty/inc/template-tags.php index 12c8fa5b09f2c..f348747c82e35 100644 --- a/src/wp-content/themes/twentytwenty/inc/template-tags.php +++ b/src/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 True if the comment is by the post author, false otherwise. + * @return bool Whether the comment is by the post author. */ function twentytwenty_is_comment_by_post_author( $comment = null ) { diff --git a/src/wp-content/themes/twentytwentyone/inc/template-functions.php b/src/wp-content/themes/twentytwentyone/inc/template-functions.php index 56b03a28003ac..689b1e22c9814 100644 --- a/src/wp-content/themes/twentytwentyone/inc/template-functions.php +++ b/src/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 Filtered body classes with theme-specific additions. + * @return string[] Body classes with theme-specific additions. */ function twenty_twenty_one_body_classes( $classes ) { @@ -43,7 +43,7 @@ function twenty_twenty_one_body_classes( $classes ) { * @since Twenty Twenty-One 1.0 * * @param array $classes An array of CSS classes. - * @return array Filtered post classes with 'entry' class added. + * @return string[] Post classes with 'entry' class added. */ function twenty_twenty_one_post_classes( $classes ) { $classes[] = 'entry'; From dc1c00080664ed26acb41707b2193cbf170cee6c Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Thu, 20 Nov 2025 08:13:55 +0600 Subject: [PATCH 3/7] Add missing @return tags to CSS generation functions for Twenty Twenty and Twenty Twenty-One --- src/wp-content/themes/twentytwenty/inc/custom-css.php | 2 ++ src/wp-content/themes/twentytwentyone/inc/custom-css.php | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/src/wp-content/themes/twentytwenty/inc/custom-css.php b/src/wp-content/themes/twentytwenty/inc/custom-css.php index 9f08898c3cf7a..7817b08dfdf9a 100644 --- a/src/wp-content/themes/twentytwenty/inc/custom-css.php +++ b/src/wp-content/themes/twentytwenty/inc/custom-css.php @@ -20,6 +20,7 @@ * @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 @@ function twentytwenty_generate_css( $selector, $style, $value, $prefix = '', $su * @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/src/wp-content/themes/twentytwentyone/inc/custom-css.php b/src/wp-content/themes/twentytwentyone/inc/custom-css.php index 02445bdfacdfc..e212cfd60642b 100644 --- a/src/wp-content/themes/twentytwentyone/inc/custom-css.php +++ b/src/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 ) { From e9a2d8a4c3eaecc24637186721016a1590ff2384 Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Thu, 20 Nov 2025 08:23:15 +0600 Subject: [PATCH 4/7] docs: Update `@since` tag to theme-specific version and clarify `@return` description for `wp_get_list_item_separator()` in various themes. --- src/wp-content/themes/twentyeleven/functions.php | 4 +++- src/wp-content/themes/twentynineteen/functions.php | 4 ++-- src/wp-content/themes/twentyseventeen/functions.php | 4 +++- src/wp-content/themes/twentythirteen/functions.php | 4 +++- src/wp-content/themes/twentytwelve/functions.php | 4 +++- src/wp-content/themes/twentytwentyone/functions.php | 4 +++- 6 files changed, 17 insertions(+), 7 deletions(-) diff --git a/src/wp-content/themes/twentyeleven/functions.php b/src/wp-content/themes/twentyeleven/functions.php index d1656fd2c13b0..c52da6e1f123f 100644 --- a/src/wp-content/themes/twentyeleven/functions.php +++ b/src/wp-content/themes/twentyeleven/functions.php @@ -988,7 +988,9 @@ function twentyeleven_skip_link() { * * 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/src/wp-content/themes/twentynineteen/functions.php b/src/wp-content/themes/twentynineteen/functions.php index e59e531ab6f37..bf9dd0253c780 100644 --- a/src/wp-content/themes/twentynineteen/functions.php +++ b/src/wp-content/themes/twentynineteen/functions.php @@ -181,9 +181,9 @@ function twentynineteen_setup() { * * Added for backward compatibility to support pre-6.0.0 WordPress versions. * - * @since 6.0.0 + * @since Twenty Nineteen 2.3 * - * @return string List item separator. + * @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/src/wp-content/themes/twentyseventeen/functions.php b/src/wp-content/themes/twentyseventeen/functions.php index 0b2005d50c7df..dbafa2260b2e4 100644 --- a/src/wp-content/themes/twentyseventeen/functions.php +++ b/src/wp-content/themes/twentyseventeen/functions.php @@ -681,7 +681,9 @@ function twentyseventeen_unique_id( $prefix = '' ) { * * 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/src/wp-content/themes/twentythirteen/functions.php b/src/wp-content/themes/twentythirteen/functions.php index 1283ed267aae2..9ea432ee07ecf 100644 --- a/src/wp-content/themes/twentythirteen/functions.php +++ b/src/wp-content/themes/twentythirteen/functions.php @@ -473,7 +473,9 @@ function twentythirteen_widgets_init() { * * 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/src/wp-content/themes/twentytwelve/functions.php b/src/wp-content/themes/twentytwelve/functions.php index c3d5043c3a086..7048817ca8aaa 100644 --- a/src/wp-content/themes/twentytwelve/functions.php +++ b/src/wp-content/themes/twentytwelve/functions.php @@ -396,7 +396,9 @@ function twentytwelve_widgets_init() { * * 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/src/wp-content/themes/twentytwentyone/functions.php b/src/wp-content/themes/twentytwentyone/functions.php index 02d2a1dc9b0cf..301aefca5cd2c 100644 --- a/src/wp-content/themes/twentytwentyone/functions.php +++ b/src/wp-content/themes/twentytwentyone/functions.php @@ -655,7 +655,9 @@ function twentytwentyone_add_ie_class() { * * 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. */ From 9b55c1508cc5683aa271f270e7a54b45871dd4ce Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Thu, 20 Nov 2025 08:57:13 +0600 Subject: [PATCH 5/7] docs: Update `@return` description for font URL functions across multiple themes. --- src/wp-content/themes/twentyfifteen/functions.php | 2 +- src/wp-content/themes/twentyfourteen/functions.php | 2 +- src/wp-content/themes/twentyseventeen/functions.php | 2 +- src/wp-content/themes/twentysixteen/functions.php | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/wp-content/themes/twentyfifteen/functions.php b/src/wp-content/themes/twentyfifteen/functions.php index a78aa5fb2f847..9926fa4783eae 100644 --- a/src/wp-content/themes/twentyfifteen/functions.php +++ b/src/wp-content/themes/twentyfifteen/functions.php @@ -366,7 +366,7 @@ function twentyfifteen_widgets_init() { * @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 or empty string if disabled. */ function twentyfifteen_fonts_url() { $fonts_url = ''; diff --git a/src/wp-content/themes/twentyfourteen/functions.php b/src/wp-content/themes/twentyfourteen/functions.php index 4f179d7622523..7eb5fb8fb1cce 100644 --- a/src/wp-content/themes/twentyfourteen/functions.php +++ b/src/wp-content/themes/twentyfourteen/functions.php @@ -315,7 +315,7 @@ function twentyfourteen_widgets_init() { * @since Twenty Fourteen 1.0 * @since Twenty Fourteen 3.6 Replaced Google URL with self-hosted fonts. * - * @return string Fonts URL for the theme. + * @return string Font stylesheet or empty string if disabled. */ function twentyfourteen_font_url() { $font_url = ''; diff --git a/src/wp-content/themes/twentyseventeen/functions.php b/src/wp-content/themes/twentyseventeen/functions.php index dbafa2260b2e4..c7198f34c7a2a 100644 --- a/src/wp-content/themes/twentyseventeen/functions.php +++ b/src/wp-content/themes/twentyseventeen/functions.php @@ -289,7 +289,7 @@ function twentyseventeen_content_width() { * @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 or empty string if disabled. */ function twentyseventeen_fonts_url() { $fonts_url = ''; diff --git a/src/wp-content/themes/twentysixteen/functions.php b/src/wp-content/themes/twentysixteen/functions.php index 8572194b873b4..a83d36138d465 100644 --- a/src/wp-content/themes/twentysixteen/functions.php +++ b/src/wp-content/themes/twentysixteen/functions.php @@ -334,7 +334,7 @@ function twentysixteen_widgets_init() { * @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 or empty string if disabled. */ function twentysixteen_fonts_url() { $fonts_url = ''; From c17462b6c9f810f8453c274f0e2707cc0066caa1 Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Thu, 20 Nov 2025 22:00:14 +0600 Subject: [PATCH 6/7] docs: Clarify font stylesheet return type in docblocks by adding "URL". --- src/wp-content/themes/twentyfifteen/functions.php | 2 +- src/wp-content/themes/twentyfourteen/functions.php | 2 +- src/wp-content/themes/twentyseventeen/functions.php | 2 +- src/wp-content/themes/twentysixteen/functions.php | 2 +- src/wp-content/themes/twentythirteen/functions.php | 2 +- src/wp-content/themes/twentytwelve/functions.php | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/wp-content/themes/twentyfifteen/functions.php b/src/wp-content/themes/twentyfifteen/functions.php index 9926fa4783eae..883e7d78f3983 100644 --- a/src/wp-content/themes/twentyfifteen/functions.php +++ b/src/wp-content/themes/twentyfifteen/functions.php @@ -366,7 +366,7 @@ function twentyfifteen_widgets_init() { * @since Twenty Fifteen 1.0 * @since Twenty Fifteen 3.4 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 twentyfifteen_fonts_url() { $fonts_url = ''; diff --git a/src/wp-content/themes/twentyfourteen/functions.php b/src/wp-content/themes/twentyfourteen/functions.php index 7eb5fb8fb1cce..27b6190bb4e71 100644 --- a/src/wp-content/themes/twentyfourteen/functions.php +++ b/src/wp-content/themes/twentyfourteen/functions.php @@ -315,7 +315,7 @@ function twentyfourteen_widgets_init() { * @since Twenty Fourteen 1.0 * @since Twenty Fourteen 3.6 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 twentyfourteen_font_url() { $font_url = ''; diff --git a/src/wp-content/themes/twentyseventeen/functions.php b/src/wp-content/themes/twentyseventeen/functions.php index c7198f34c7a2a..9e322b0ef929f 100644 --- a/src/wp-content/themes/twentyseventeen/functions.php +++ b/src/wp-content/themes/twentyseventeen/functions.php @@ -289,7 +289,7 @@ function twentyseventeen_content_width() { * @since Twenty Seventeen 1.0 * @since Twenty Seventeen 3.2 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 twentyseventeen_fonts_url() { $fonts_url = ''; diff --git a/src/wp-content/themes/twentysixteen/functions.php b/src/wp-content/themes/twentysixteen/functions.php index a83d36138d465..f1cc981d1899e 100644 --- a/src/wp-content/themes/twentysixteen/functions.php +++ b/src/wp-content/themes/twentysixteen/functions.php @@ -334,7 +334,7 @@ function twentysixteen_widgets_init() { * @since Twenty Sixteen 1.0 * @since Twenty Sixteen 2.9 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 twentysixteen_fonts_url() { $fonts_url = ''; diff --git a/src/wp-content/themes/twentythirteen/functions.php b/src/wp-content/themes/twentythirteen/functions.php index 9ea432ee07ecf..34a1facb8bc79 100644 --- a/src/wp-content/themes/twentythirteen/functions.php +++ b/src/wp-content/themes/twentythirteen/functions.php @@ -270,7 +270,7 @@ function twentythirteen_setup() { * @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 = ''; diff --git a/src/wp-content/themes/twentytwelve/functions.php b/src/wp-content/themes/twentytwelve/functions.php index 7048817ca8aaa..ce98c577b3b41 100644 --- a/src/wp-content/themes/twentytwelve/functions.php +++ b/src/wp-content/themes/twentytwelve/functions.php @@ -160,7 +160,7 @@ function twentytwelve_register_block_patterns() { * @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 = ''; From 3011bf8c95337180f18c8579f9e6f03f9c75d8ef Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Sat, 22 Nov 2025 11:33:19 +0600 Subject: [PATCH 7/7] Fix docblock return type for custom logo filter. Co-authored-by: Weston Ruter --- src/wp-content/themes/twentytwenty/functions.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/wp-content/themes/twentytwenty/functions.php b/src/wp-content/themes/twentytwenty/functions.php index 74bc1efef715c..754516009c362 100644 --- a/src/wp-content/themes/twentytwenty/functions.php +++ b/src/wp-content/themes/twentytwenty/functions.php @@ -304,7 +304,7 @@ function twentytwenty_menus() { * @since Twenty Twenty 1.0 * * @param string $html The HTML output from get_custom_logo() (core function). - * @return string|false Custom logo HTML or false if not available. + * @return string Custom logo HTML with "retina" resolution applied if enabled. */ function twentytwenty_get_custom_logo( $html ) {