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.

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.