[wp-trac] [WordPress Trac] #51278: Update return types to reflect the real return types. Remove mixed.

[WordPress Trac]

#51278: Update return types to reflect the real return types. Remove mixed.
-------------------------------------------------+-------------------------
 Reporter:  ReneHermi                            |      Owner:  (none)
     Type:  enhancement                          |     Status:  new
 Priority:  normal                               |  Milestone:  Awaiting
                                                 |  Review
Component:  General                              |    Version:  trunk
 Severity:  major                                |   Keywords:  has-patch
  Focuses:  accessibility, docs, coding-         |
  standards                                      |
-------------------------------------------------+-------------------------
 In the DocBlocks, we document return values with `mixed` only.

 That is no good practice as it does not show the real available and
 possible return types.
 A better approach is to declare and document explicitly return values
 separated by a pipe character like this `@return bool|string`

 That is much clearer because developers do not need to check the return
 values by reading the entire docBlock, reading the whole code of a method,
 or reading the (lengthy) function description under
 developer.wordpress.org.

 A simple`mixed` is outdated and makes it hard for every severe developer
 to start with coding for WordPress as he has to continually check the
 expected return values when there is a `mixed`.

 As a bonus, the documentation under developer.wordpress.org will be
 updated as well by this change automatically. It will help developers
 getting know the correct return values immediately from the docs without
 reading all the extra special explanations that we added to our docs
 whenever we use `mixed`.

 That is a huge time saver and makes it much faster for every developer to
 write solid and better code faster.

 If this is accepted for core, I will offer to work on this on all other
 methods as well.

 That will be a long-lasting process due to the number of functions, but
 it's definitely worth the effort. We should make this change to all
 methods where we use`mixed` and make it to our daily little take-care
 moment when we add new methods to WordPress.

 Sample Patch by using `get_option()` as an example for all methods that
 use `mixed`:
 https://github.com/WordPress/wordpress-develop/pull/523

 `get_option()` is a special case, though as it automatically unserializes.
 So it supports all non-scalar types. Most other methods in WordPress uses
 `mixed` with only two return types like `bool|string` representation,
 which makes the updates easier.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/51278>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform