Docs: Replace void with null in union return types in various core files#11012
Docs: Replace void with null in union return types in various core files#11012apermo wants to merge 11 commits intoWordPress:trunkfrom
Conversation
Fixes #64704. See #64694. Co-Authored-By: xateman
|
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 Core Committers: Use this line as a base for the props when committing in SVN: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Test using WordPress PlaygroundThe 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
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
There was a problem hiding this comment.
Pull request overview
This PR updates PHPDoc return type documentation across various WordPress core files to replace void with null in union return types, aligning with PHP documentation standards where void cannot be part of a union type. The changes also update corresponding code to use explicit return null; statements instead of bare return; statements for consistency.
Changes:
- Updated PHPDoc
@returnannotations fromtype|voidtotype|nullor removed|voidwhere functions always return a value - Changed bare
return;statements to explicitreturn null;to match updated documentation - Improved documentation accuracy by correctly reflecting actual return types
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| src/wp-includes/widgets.php | Updated return types for wp_widget_description() and wp_sidebar_description() from `string |
| src/wp-includes/theme.php | Changed unregister_default_headers() from `bool |
| src/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php | Updated get_store() and add_rule() methods from returning `type |
| src/wp-includes/script-loader.php | Changed print_late_styles() return type from `string[] |
| src/wp-includes/revision.php | Updated wp_save_post_revision() from `int |
| src/wp-includes/post.php | Updated return types for get_post_custom_keys(), wp_trash_post_comments(), wp_untrash_post_comments() from various union types with void to null |
| src/wp-includes/ms-functions.php | Changed get_active_blog_for_user() and add_existing_user_to_blog() return documentation from including void to null |
| src/wp-includes/media.php | Updated shortcode functions and wp_prepare_attachment_for_js() from `type |
| src/wp-includes/functions.php | Changed wp_ext2type() and wp_update_php_annotation() return types from `string |
| src/wp-includes/formatting.php | Updated sanitize_hex_color() from `string |
| src/wp-includes/comment.php | Changed wp_update_comment_count() and trackback() return types to use null instead of void |
| src/wp-includes/class-wp-xmlrpc-server.php | Updated escape() method from `string |
| src/wp-includes/class-wp-widget.php | Changed form() method from `string |
| src/wp-includes/class-wp-theme-json.php | Updated set_spacing_sizes() from `null |
| src/wp-includes/class-wp-scripts.php | Changed print_scripts_l10n() and print_extra_script() from `bool |
| src/wp-includes/class-wp-roles.php | Updated add_role() from `WP_Role |
| src/wp-includes/class-wp-recovery-mode.php | Changed handle_error() from `true |
| src/wp-includes/class-wp-plugin-dependencies.php | Updated get_dependency_api_data() from `array |
| src/wp-includes/class-wp-block-type.php | Changed __get() method documentation from `string |
| src/wp-includes/capabilities.php | Updated add_role() from `WP_Role |
| src/wp-includes/canonical.php | Changed redirect_canonical() from `string |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Weston Ruter <westonruter@gmail.com>
|
@apermo Please double-check my additions. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.
Comments suppressed due to low confidence (1)
src/wp-includes/class-wp-xmlrpc-server.php:357
- The
@returndescription inwp_xmlrpc_server::escape()is ungrammatical: "Returns with string is passed" reads like a typo. Since this line was touched, consider rewording to something like "Returns a string when a string is passed; alters by-reference when an array is passed" for clarity.
* @return string|null Returns with string is passed, alters by-reference
* when array is passed.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
No code path returns null. The implicit return after redirect_protected() is unreachable since that method is annotated as @return never.
- Fix WP_Block_Type variations type to array of arrays - Change set_spacing_sizes() to @return void with bare return statements - Add null to WP_Widget::form() return type for subclasses - Add @return descriptions for sanitize_hex_color() and wp_update_php_annotation() - Fix typo in wp_xmlrpc_server::escape() description
|
@westonruter all checked, ran your stricter |
Co-Authored-By: xateman
Trac ticket: https://core.trac.wordpress.org/ticket/64704
Use of AI Tools
Used AI for research, documentation and for the replacements. Everything was reviewed by myself and @xateman before opening this PR.
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.