Docs: Add missing @return descriptions in bundled themes. #10533

huzaifaalmesbah · 2025-11-20T00:37:31Z

This PR addresses missing or incomplete @return tag documentation in several bundled themes.

Changes include:

Adding descriptions to @return tags in functions.php and other include files for Twenty Twenty, Twenty Seventeen, and Twenty Twenty-One.
Adding missing @return tags and descriptions in Twenty Fourteen and Twenty Nineteen.

Trac ticket: https://core.trac.wordpress.org/ticket/64277

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.

github-actions · 2025-11-20T00:37:42Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props huzaifaalmesbah, sabernhardt, westonruter.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2025-11-20T00:56:32Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

sabernhardt · 2025-11-20T01:12:08Z

src/wp-content/themes/twentyfourteen/functions.php

 	 * @since Twenty Fourteen 3.6 Replaced Google URL with self-hosted fonts.
 	 *
-	 * @return string
+	 * @return string Fonts URL for the theme.


Good catch that the description was missing in Twenty Fourteen, but I think the description in twentytwelve_get_font_url() and twentythirteen_fonts_url() would fit better.

Suggested change

* @return string Fonts URL for the theme.

* @return string Font stylesheet or empty string if disabled.

How about “Font stylesheet URL”?

Then I would want "Font stylesheet URL" for T12, T13 and T14 :)

I noticed that Twenty Fourteen, Twenty Fifteen, Twenty Sixteen, and Twenty Seventeen all use the @return string Fonts URL for the theme. description. Should I update: @return string Font stylesheet or empty string if disabled. for consistency?

Maybe it should be the same for all six themes from Twenty Twelve to Twenty Seventeen:
Font stylesheet URL or empty string if disabled.

I wanted to say something like "if all fonts are disabled" for Twenty Fifteen and Twenty Sixteen because locales can turn off fonts individually, but the same would fit for Twenty Thirteen and that was not any different than the themes with only one hosted font.

Thanks for the clarification! I agree using “Font stylesheet URL or empty string if disabled” consistently across Twenty Twelve to Twenty Seventeen makes sense. I’ll update all six themes accordingly.

src/wp-content/themes/twentyfourteen/functions.php

src/wp-content/themes/twentynineteen/inc/template-functions.php

src/wp-content/themes/twentyseventeen/inc/template-functions.php

src/wp-content/themes/twentyseventeen/inc/template-tags.php

src/wp-content/themes/twentytwenty/functions.php

src/wp-content/themes/twentytwentyone/inc/template-functions.php

westonruter · 2025-11-20T01:11:50Z

src/wp-content/themes/twentytwentyone/inc/template-functions.php

- * @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' ) {


This function is calling twenty_twenty_one_generate_css() which also lacks a @return description.

Okay, I will update it. Thanks for pointing that out!

Co-authored-by: Weston Ruter <westonruter@gmail.com>

sabernhardt · 2025-11-20T01:57:14Z

src/wp-content/themes/twentynineteen/functions.php

 	 * @since 6.0.0
+	 *
+	 * @return string List item separator.


The core wp_get_list_item_separator() function describes the return value as "Locale-specific list item separator." I think the same is accurate within the themes, though these only have the fallback translatable string instead of using the PHP class.

Five other themes also include the function for backward compatibility: T11, T12, T13, T17, and T21. See r52929.

I think the since annotations should reflect the theme versions, not the WordPress version (as r45256 did for wp_body_open() "shims").

Twenty Eleven 4.1

Twenty Twelve 3.7

Twenty Thirteen 3.7

Twenty Seventeen 3.0

Twenty Nineteen 2.3

Twenty Twenty-One 1.6

Okay, I will update it. Thanks for pointing that out!

…y and Twenty Twenty-One

…urn` description for `wp_get_list_item_separator()` in various themes.

…iple themes.

src/wp-content/themes/twentytwenty/functions.php

Co-authored-by: Weston Ruter <westonruter@gmail.com>

Developed in #10533 Props huzaifaalmesbah, sabernhardt, palak678, westonruter. See #64224. Fixes #64277. git-svn-id: https://develop.svn.wordpress.org/trunk@61302 602fd350-edb4-49c9-b593-d223f7449a82

github-actions · 2025-11-25T05:01:15Z

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 61302
GitHub commit: 985692b

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.

Developed in WordPress/wordpress-develop#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

Developed in WordPress/wordpress-develop#10533 Props huzaifaalmesbah, sabernhardt, palak678, westonruter. See #64224. Fixes #64277. Built from https://develop.svn.wordpress.org/trunk@61302 git-svn-id: https://core.svn.wordpress.org/trunk@60614 1a063a9b-81f0-0310-95a4-ce76da25c4cd

Docs: Add missing @return descriptions in bundled themes.

5b1a821

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.

sabernhardt reviewed Nov 20, 2025

View reviewed changes

westonruter reviewed Nov 20, 2025

View reviewed changes

Apply suggestions from code review

b697495

Co-authored-by: Weston Ruter <westonruter@gmail.com>

sabernhardt reviewed Nov 20, 2025

View reviewed changes

huzaifaalmesbah added 4 commits November 20, 2025 08:13

Add missing @return tags to CSS generation functions for Twenty Twent…

dc1c000

…y and Twenty Twenty-One

docs: Update @since tag to theme-specific version and clarify `@ret…

e9a2d8a

…urn` description for `wp_get_list_item_separator()` in various themes.

docs: Update @return description for font URL functions across mult…

9b55c15

…iple themes.

docs: Clarify font stylesheet return type in docblocks by adding "URL".

c17462b

westonruter reviewed Nov 21, 2025

View reviewed changes

src/wp-content/themes/twentytwenty/functions.php Outdated Show resolved Hide resolved

Fix docblock return type for custom logo filter.

3011bf8

Co-authored-by: Weston Ruter <westonruter@gmail.com>

westonruter requested a review from sabernhardt November 22, 2025 06:34

westonruter approved these changes Nov 22, 2025

View reviewed changes

github-actions bot closed this Nov 25, 2025

	* @return string Fonts URL for the theme.
	* @return string Font stylesheet or empty string if disabled.

Docs: Add missing @return descriptions in bundled themes. #10533

Docs: Add missing @return descriptions in bundled themes. #10533

Uh oh!

Conversation

huzaifaalmesbah commented Nov 20, 2025

Uh oh!

github-actions bot commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Nov 20, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Nov 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Nov 20, 2025 •

edited

Loading