Docs: Replace void with null in union return types in wp-includes

[sanketio]

Summary

Follows up on #64704 and r62178.

In PHP's type system, void means a function does not return a value and cannot be part of a union type. Many functions in wp-includes were documented as returning e.g. string|void while actually returning null implicitly via bare return; statements or falling off the end of the function.

This PR replaces void with null in union @return annotations across 18 files in wp-includes, adds explicit return null; statements where appropriate, and updates @return description text to say "Null" instead of "Void".

Changes

void|string → string|null (19 instances)

Echo/display functions that return a string when $display/$echo is false and null when printing directly.

• general-template.php — get_search_form(), wp_loginout(), wp_login_form(), wp_register(), wp_get_archives(), get_calendar()
• post-template.php — the_title(), the_title_attribute(), wp_list_pages(), wp_page_menu()
• comment-template.php — comment_class(), trackback_url(), wp_list_comments()
• author-template.php — wp_list_authors()
• bookmark-template.php — wp_list_bookmarks()
• link-template.php — paginate_comments_links()
• category-template.php — wp_list_categories(), wp_tag_cloud()
• nav-menu-template.php — wp_nav_menu()

void|false → false|null (11 instances)

Functions that return false on failure and null (implicitly) on success.

• general-template.php — get_header(), get_footer(), get_sidebar(), get_template_part()
• functions.php — do_enclose()
• taxonomy.php — update_object_term_cache()
• theme.php — add_theme_support()
• category-template.php — the_terms()
• comment.php — do_trackbacks()
• user.php — update_user_caches()
• class-wp-customize-setting.php — WP_Customize_Setting::save()

void|WP_Error / void|IXR_Error → WP_Error|null (5 instances)

Functions that return an error object on failure and null on success.

• class-wp-metadata-lazyloader.php — queue_objects(), reset_queue()
• class-wp-image-editor-imagick.php — thumbnail_image()
• class-wp-xmlrpc-server.php — _toggle_sticky()
• rest-api/endpoints/class-wp-rest-edit-site-export-controller.php — export()

Backward Compatibility

No behavior change. In PHP, a bare return; and return null; are identical at runtime across all PHP versions. This is a documentation-only fix.

Test Case

No test case updates needed. Existing tests using assertNull() on the success paths of these functions were already written correctly, as null was always the actual runtime return value.

---

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

---

Use of AI Tools

AI assistance: Yes
Tool(s): GitHub Copilot
Model(s): Claude Sonnet 4.6
Used for: Identifying all void union return instances, generating replacements, and drafting the PR description; all changes were reviewed and verified by me before submission.

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[github-actions]

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 sanketparmar, wildworks.

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

[github-actions]

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

• 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.

[Copilot]

Pull request overview

This PR updates WordPress core inline documentation (and a few early-return statements) to replace invalid void union return types with null in @return annotations across multiple wp-includes APIs, aligning documented types with actual runtime behavior.

Changes:

• Replaces void|... union PHPDoc return types with ...|null in wp-includes functions/methods.
• Adds explicit return null; in a few early-exit branches where functions previously used a bare return;.
• Updates return descriptions from “Void” to “Null” where applicable.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/wp-includes/user.php	Updates update_user_caches() return PHPDoc to `false
src/wp-includes/theme.php	Updates add_theme_support() return PHPDoc and adds an explicit return null; in an early-return branch.
src/wp-includes/taxonomy.php	Updates update_object_term_cache() return PHPDoc and adds return null; for empty input.
src/wp-includes/rest-api/endpoints/class-wp-rest-edit-site-export-controller.php	Adjusts export() return PHPDoc (but currently becomes inaccurate vs behavior).
src/wp-includes/post-template.php	Updates the_title() / the_title_attribute() PHPDoc and explicit return null; for empty titles.
src/wp-includes/nav-menu-template.php	Updates wp_nav_menu() return PHPDoc and explicit return null; for echoing the pre-filtered menu.
src/wp-includes/link-template.php	Updates paginate_comments_links() return PHPDoc and explicit return null; when not singular.
src/wp-includes/general-template.php	Updates multiple template function return PHPDocs and adds explicit return null; in a few echo/display paths.
src/wp-includes/functions.php	Updates do_enclose() return PHPDoc to `false
src/wp-includes/comment.php	Updates do_trackbacks() return PHPDoc and adds return null; for an early-success path.
src/wp-includes/comment-template.php	Updates return PHPDocs and explicit return null; in some early-bail paths.
src/wp-includes/class-wp-xmlrpc-server.php	Updates _toggle_sticky() return PHPDoc to `IXR_Error
src/wp-includes/class-wp-metadata-lazyloader.php	Updates PHPDoc for queue_objects() / reset_queue() to `WP_Error
src/wp-includes/class-wp-image-editor-imagick.php	Updates thumbnail_image() PHPDoc to `WP_Error
src/wp-includes/class-wp-customize-setting.php	Updates WP_Customize_Setting::save() return PHPDoc to `false
src/wp-includes/category-template.php	Updates return PHPDocs and adds return null; for early failures in wp_tag_cloud().
src/wp-includes/bookmark-template.php	Updates wp_list_bookmarks() return PHPDoc to `string
src/wp-includes/author-template.php	Updates wp_list_authors() return PHPDoc to `string

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.