[wp-trac] [WordPress Trac] #64700: Code Modernization: Replace void in PHPDoc union return types with null in general-template.php

[WordPress Trac]

#64700: Code Modernization: Replace void in PHPDoc union return types with null in
general-template.php
--------------------------+--------------------------
 Reporter:  apermo        |       Owner:  westonruter
     Type:  defect (bug)  |      Status:  reviewing
 Priority:  normal        |   Milestone:  7.0
Component:  General       |     Version:  4.3
 Severity:  normal        |  Resolution:
 Keywords:  has-patch     |     Focuses:
--------------------------+--------------------------
Description changed by westonruter:

Old description:

> Following up on [#64694] which fixed `paginate_links()`, this ticket
> addresses 10 instances in `general-template.php` where `@return`
> annotations incorrectly use `void` as part of a union type (e.g.,
> `@return string|void`).
>
> The `|void` pattern in this file was introduced in two waves:
> * WordPress 4.3 (8 functions) via [32598] — "Cleanup doc blocks in
> `general-template.php`"
> * WordPress 6.0 (2 functions) via [53300] — "Docs: Various docblock
> corrections"
>
> === Why this matters ===
>
> In PHP's type system, `void` means "the function does not return a value"
> and '''cannot''' be part of a union type (this is a compile error in PHP
> 8.0+). When a function uses bare `return;` or falls off the end without
> returning, the actual runtime value is `null`. Therefore `@return
> Type|void` should be `@return Type|null`.
>
> This affects:
> * Static analysis tools (PHPStan, Psalm)
> * IDE autocompletion and type inference
> * Developer expectations about return values
>
> === Backward Compatibility ===
>
> This is a safe, non-breaking change. As demonstrated by @westonruter in
> the [https://github.com/WordPress/wordpress-
> develop/pull/10999#pullrequestreview-3839142928 #64694 PR review],
> `return;` and `return null;` are identical at runtime across every PHP
> version from 4.3.0 through 8.5.3: https://3v4l.org/3KQC8
>
> === Proposed Changes ===
>
> For each instance:
> 1. Update the `@return` annotation to replace `void` with `null`
> 2. Change bare `return;` statements to `return null;`
> 3. Update description text to say "null" instead of "void" / "nothing"
>
> === Affected Functions ===
>
> ||= Function =||= Line =||= Current =||= Recommendation =||= Since =||
> || `wp_title()` || 1341 || `string|void` || `string|null` || 6.0 ||
> || `single_post_title()` || 1492 || `string|void` || `string|null` || 4.3
> ||
> || `post_type_archive_title()` || 1527 || `string|false|void` ||
> `string|null` (also remove `false`) || 4.3 ||
> || `single_cat_title()` || 1569 || `string|void` || `string|null` || 4.3
> ||
> || `single_tag_title()` || 1586 || `string|void` || `string|null` || 4.3
> ||
> || `single_term_title()` || 1603 || `string|void` || `string|null` || 4.3
> ||
> || `single_month_title()` || 1668 || `string|false|void` ||
> `string|false|null` || 6.0 ||
> || `the_date()` || 2684 || `string|void` || `string|null` || 4.3 ||
> || `the_modified_date()` || 2759 || `string|void` || `string|null` || 4.3
> ||
> || `get_the_generator()` || 5169 || `string|void` || `string|null` || 4.3
> ||
>
> See [#64694] for prior art.

New description:

 Following up on [#64694] which fixed `paginate_links()`, this ticket
 addresses 10 instances in `general-template.php` where `@return`
 annotations incorrectly use `void` as part of a union type (e.g., `@return
 string|void`).

 The `|void` pattern in this file was introduced in two waves:
 * WordPress 4.3 (8 functions) via [32598] — "Cleanup doc blocks in
 `general-template.php`"
 * WordPress 6.0 (2 functions) via [53300] — "Docs: Various docblock
 corrections"

 === Why this matters ===

 In PHP's type system, `void` means "the function does not return a value"
 and '''cannot''' be part of a union type (this is a compile error in PHP
 8.0+). When a function uses bare `return;` or falls off the end without
 returning, the actual runtime value is `null`. Therefore `@return
 Type|void` should be `@return Type|null`.

 This affects:
 * Static analysis tools (PHPStan, Psalm)
 * IDE autocompletion and type inference
 * Developer expectations about return values

 === Backward Compatibility ===

 This is a safe, non-breaking change. As demonstrated by @westonruter in
 the [https://github.com/WordPress/wordpress-
 develop/pull/10999#pullrequestreview-3839142928 #64694 PR review],
 `return;` and `return null;` are identical at runtime across every PHP
 version from 4.3.0 through 8.5.3: https://3v4l.org/3KQC8

 === Proposed Changes ===

 For each instance:
 1. Update the `@return` annotation to replace `void` with `null`
 2. Change bare `return;` statements to `return null;`
 3. Update description text to say "null" instead of "void" / "nothing"

 === Affected Functions ===

 ||= Function =||= Line =||= Current =||= Recommendation =||= Since =||
 || `wp_title()` || 1341 || `string|void` || `string|null` || 6.0 ||
 || `single_post_title()` || 1492 || `string|void` || `string|null` || 4.3
 ||
 || `post_type_archive_title()` || 1527 || `string|false|void` ||
 `string|null` (also remove `false`) || 4.3 ||
 || `single_cat_title()` || 1569 || `string|void` || `string|null` || 4.3
 ||
 || `single_tag_title()` || 1586 || `string|void` || `string|null` || 4.3
 ||
 || `single_term_title()` || 1603 || `string|void` || `string|null` || 4.3
 ||
 || `single_month_title()` || 1668 || `string|false|void` ||
 `string|false|null` || 6.0 ||
 || `the_date()` || 2684 || `string|void` || `string|null` || 4.3 ||
 || `the_modified_date()` || 2759 || `string|void` || `string|null` || 4.3
 ||
 || `get_the_generator()` || 5169 || `string|void` || `string|null` || 4.3
 ||

 See #64694 for prior art.

--

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64700#comment:6>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform