Docs: Fix improper @return tag documentation to comply with WordPress standards #10522

huzaifaalmesbah · 2025-11-17T10:21:43Z

Description

Fixes https://core.trac.wordpress.org/ticket/64262

Updates @return tag documentation to comply with WordPress PHP Documentation Standards.

Changes:

Replace boolean/Boolean with bool
Replace integer/Integer with int
Add descriptions to @return tags (type + description required)

Files: 10 files, 29 functions

wp-includes: class-wp-theme-json-resolver.php, block-supports/elements.php, formatting.php, comment.php, functions.php
wp-admin/includes: plugin.php, widgets.php, user.php, upgrade.php

Example:

// Before
@return integer|null

// After
@return int|null

// Before
@return string

// After  
@return string The base name of the given path.

Testing:

Documentation-only changes
No functional code modifications
Complies with WordPress Coding Standards

Drafted commit message

Docs: Add missing descriptions and fix types for some @return tags.

Props huzaifaalmesbah, sabernhardt, westonruter.
See #64224.
Fixes #64262.

@return

Updates @return tag documentation across WordPress core to comply with the WordPress PHP Documentation Standards. Changes: - Replace boolean/Boolean with bool - Replace integer/Integer with int - Add descriptions to @return tags missing them Fixes #64262

github-actions · 2025-11-17T10:21:52Z

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, westonruter, sabernhardt.

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

github-actions · 2025-11-17T10:37:43Z

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.

westonruter · 2025-11-17T19:43:51Z

src/wp-includes/class-json.php

This is a third-party library so I don't think it should have its coding standards updated. It will complicate future patches. Nevertheless, the file itself is deprecated, so I think it should be ignored.

src/wp-includes/class-wp-theme-json-resolver.php

src/wp-includes/functions.php

Co-authored-by: Weston Ruter <[email protected]> Co-authored-by: Stephen A. Bernhardt <[email protected]>

…-standards

huzaifaalmesbah · 2025-11-18T01:49:58Z

Thanks @westonruter and @sabernhardt for your detailed reviews and helpful suggestions. I've applied all the recommended changes, and I’ve ignored updates to src/wp-includes/class-json.php as advised since it's a third-party library and deprecated.

westonruter · 2025-11-19T04:58:59Z

src/wp-admin/includes/user.php

 *
 * @param int $user_id User ID.
- * @return array
+ * @return array Array of the user's draft posts.


When/if we adopt PHPStan types, it would be nice if this were typed as array<object{ ID: int, post_title: string }>. Right now it is not clear what the return value is supposed to be.

Nevertheless, this function is not even used in core anymore, so it might as well be moved to be deprecated.

I'm updating this to:

@return object[] The user's draft posts, with 'ID' and 'post_title' keys.

westonruter · 2025-11-19T05:07:30Z

src/wp-admin/includes/user.php

 *
 * @param string $text
- * @return string
+ * @return string Modified email text.


I'm changing this to "User site invitation email message."

westonruter · 2025-11-19T05:09:30Z

src/wp-admin/includes/widgets.php

 *
 * @param array $params
- * @return array
+ * @return array Modified params array.


I'll change this to "Widget control arguments." as the function's description is "Retrieves the widget control arguments."

westonruter · 2025-11-19T05:12:04Z

src/wp-admin/includes/widgets.php

 *
 * @param array $sidebar_args
- * @return array
+ * @return array Updated sidebar args array.


This doesn't look right. The supplied $sidebar_args is not modified in any way. It is just passed straight through. I'll change this to "Passed through value of $sidebar_args param."

The return value is never read in core either. So it seems like it doesn't really need to have returned anything.

westonruter · 2025-11-19T05:20:15Z

src/wp-includes/formatting.php

 *
 * @param string $tag_name
- * @return string
+ * @return string Escaped tag name.


Technically “escaped” is incorrect here. It is actually sanitized. I'll update.

westonruter

I made some tweaks. Take a look.

huzaifaalmesbah · 2025-11-19T06:05:21Z

Thanks for the updates @westonruter The docs feel a lot clearer and more helpful now.

github-actions · 2025-11-19T06:16:14Z

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

SVN changeset: 61270
GitHub commit: 33c8d7e

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

westonruter requested changes Nov 17, 2025

View reviewed changes

sabernhardt reviewed Nov 17, 2025

View reviewed changes

src/wp-includes/functions.php Outdated Show resolved Hide resolved

sabernhardt reviewed Nov 17, 2025

View reviewed changes

src/wp-includes/functions.php Outdated Show resolved Hide resolved

huzaifaalmesbah and others added 3 commits November 18, 2025 07:35

Suggestion commit

9dd3d1b

Co-authored-by: Weston Ruter <[email protected]> Co-authored-by: Stephen A. Bernhardt <[email protected]>

Merge branch 'WordPress:trunk' into docs/fix-return-tag-documentation…

7246056

…-standards

Revert class-json.php

3e911eb

Merge branch 'trunk' into docs/fix-return-tag-documentation-standards

0ea24f8

westonruter reviewed Nov 19, 2025

View reviewed changes

westonruter added 2 commits November 18, 2025 21:04

Remove redundant array from return description

38e92a6

Give explicit array type for get_users_drafts() return value

1e2e88b

westonruter reviewed Nov 19, 2025

View reviewed changes

Clarify admin_created_user_email() return description

712faa5

westonruter reviewed Nov 19, 2025

View reviewed changes

westonruter added 6 commits November 18, 2025 21:13

Update return description for wp_list_widget_controls_dynamic_sidebar()

ebf6ff8

Update return description for wp_widget_control()

c00f3e0

Clarify value for get_user_global_styles_post_id() return description

10e9d44

Clarify return description for theme_has_support()

3b4defb

Remove redundant array from get_style_variations() return description

300ed7f

Clarify return description for wp_defer_comment_counting()

a7c801c

westonruter reviewed Nov 19, 2025

View reviewed changes

westonruter added 2 commits November 18, 2025 21:20

Tweak return description for _autop_newline_preservation_helper()

b2cbd97

Clarify that tag_escape() returns santiized value not escaped value

7c015b4

westonruter approved these changes Nov 19, 2025

View reviewed changes

github-actions bot closed this Nov 19, 2025

Docs: Fix improper @return tag documentation to comply with WordPress standards #10522

Docs: Fix improper @return tag documentation to comply with WordPress standards #10522

Uh oh!

Conversation

huzaifaalmesbah commented Nov 17, 2025 • edited by westonruter Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Drafted commit message

Uh oh!

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

Uh oh!

Uh oh!

github-actions bot commented Nov 17, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

huzaifaalmesbah commented Nov 18, 2025

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!

Choose a reason for hiding this comment

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

huzaifaalmesbah commented Nov 19, 2025

Uh oh!

github-actions bot commented Nov 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

huzaifaalmesbah commented Nov 17, 2025 •

edited by westonruter

Loading

github-actions bot commented Nov 17, 2025 •

edited

Loading