[wp-trac] [WordPress Trac] #30989: Additional audit for recent documentation changes

[WordPress Trac]

#30989: Additional audit for recent documentation changes
----------------------------+---------------------------
 Reporter:  SergeyBiryukov  |       Owner:  DrewAPicture
     Type:  task (blessed)  |      Status:  accepted
 Priority:  normal          |   Milestone:  4.4
Component:  General         |     Version:  4.1
 Severity:  normal          |  Resolution:
 Keywords:  dev-feedback    |     Focuses:  docs
----------------------------+---------------------------

Comment (by DrewAPicture):

 Replying to [comment:1 SergeyBiryukov]:
 > If a function returns a string on success and false on failure, does it
 make a difference if `string` comes first in the `@return` value? I
 thought `string|bool` is preferred, but was confused by some of the
 changes in [30674].

 The first type in the list should always be the expected type, followed by
 any outliers. Beyond a certain number (usually 3 or 4) we just `mixed`
 then explain all possibles in the description.

 So a common pattern in core is something like `* @return int|WP_Error
 Description.`. `int` is the expected type, `WP_Error` is the outlier.

 > Looks like some of the recent changes attempted to clarify `bool` and
 changed it to `false`.
 >
 > Should we standardize on `string|false` in that case?

 I think so, yes, because I assume `string` is the expected type.

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