[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 jond3r):

 A possibly warranted use of {{{@return void}}} is in cases where a
 function may return multiple types (which is all too common).

 An example that I struggled with myself and which actually got committed
 in [25697] (for the function {{{_fix_attachment_links()}}}) uses
 {{{
 @return void|int|WP_Error
 }}}
 In this case {{{void}}} is returned if nothing is fixed, 0 or WP_Error on
 update failure, and the post ID on update success. (One could argue that
 this is poor design, but thankfully the function is not meant for public
 access).

 I we cannot use {{{void}}} in this example, we are left with {{{@return
 mixed}}}, which is much less descriptive.

 When the only return is {{{void}}} (i.e. "nothing") there is not much hurt
 in omitting {{{@return void}}}, but maybe we can officially allow it in
 "mixed" situations?

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