Coding Standards: Fix improper @return tag documentation across core files

[huzaifaalmesbah]

Fixes @return tag documentation violations in WordPress core to comply with ​PHP Documentation Standards.

Changes:

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

Files Modified: 10 files, 29 functions total

• wp-includes: class-wp-theme-json-resolver.php, block-supports/elements.php, class-json.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.

## 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, class-json.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:

• [x] Documentation-only changes
• [x] No functional code modifications
• [x] Complies with WordPress Coding Standards

[noruzzaman]

Thanks for the patch, @huzaifaalmesbah! I’ve reviewed the changes and they look good to me. The @return tags are now using bool/int and include clear descriptions in accordance with the WordPress PHP Documentation Standards. I’ve also confirmed this is documentation-only with no functional code changes. Nice improvement to consistency across the affected core files.

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.

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

[westonruter]

In 61270:

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

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