[wp-trac] [WordPress Trac] #27098: Bundled Themes: ditch all uses of `@return void`

[WordPress Trac]

#27098: Bundled Themes: ditch all uses of `@return void`
-------------------------------+---------------------
 Reporter:  philiparthurmoore  |       Owner:
     Type:  defect (bug)       |      Status:  closed
 Priority:  normal             |   Milestone:  3.9
Component:  Bundled Theme      |     Version:  trunk
 Severity:  normal             |  Resolution:  fixed
 Keywords:  has-patch          |     Focuses:  docs
-------------------------------+---------------------

Comment (by GaryJ):

 Replying to [comment:19 jond3r]:
 > A possibly warranted use of {{{@return void}}} is in cases where a
 function may return multiple types (which is all too common).

 If a `return` tag is present, then it's never void. It's either a standard
 type, or `null`, even when the `null` is not explicit e.g. `return;`.

 > An example that I struggled with myself and which actually got committed
 in [25697]

 That was committed in June 2013, while the discussion and decision to tidy
 up on the voids was not done until September, so it's not a sound example
 of agreement. Likewise, it doesn't follow the now-agreed coding standards
 of using (previously optional) braces.

 > {{{
 > @return void|int|WP_Error
 > }}}
 > In this case {{{void}}} is returned if nothing is fixed.

 No, `null` is returned.

 "If no parameter is supplied, then the parentheses must be omitted and
 NULL will be returned." - http://www.php.net/manual/en/function.return.php

 Null is also returned when there is no `return` control structure, but
 that's a different debate.

 > A recent example where void was used in a @return, specifically as
 > * @return bool|void
 > was in [27575]. So I think we can say that void is allowed in mixed
 cases.

 It's not 100% clearcut, but I'd say that documentation is wrong. There is
 at least one `return` (so it can't be void) in the function, just not for
 a particular path - so in that case, it returns `bool|null`.

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