[wp-meta] [Making WordPress.org] #5428: Add return types to docBlock instead of writing mixed and Improve docs for get_transient()

[Making WordPress.org]

#5428: Add return types to docBlock instead of writing mixed and Improve docs for
get_transient()
-----------------------+--------------------
 Reporter:  ReneHermi  |      Owner:  (none)
     Type:  task       |     Status:  new
 Priority:  high       |  Milestone:
Component:  Codex      |   Keywords:
-----------------------+--------------------
 In the codex and even in the source PHP DocBlock, we document return
 values only as
 {{{
 mixed
 }}}

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

 That is much clearer, and developers do not need to check the return
 values by reading the code or reading the (lengthy) description.

 It would be better if the description of a method in the codex explains
 what the method does, not it's return values if there are mixed return
 values.

 If I could get write access to the function reference, I'd offer to update
 this over time.

 It will take some time, but the core docs are used by me every day, and I
 think this would be a vast improvement.

 Another issue:

 I've found some more issues in the docs like not explaining the misleading
 naming convention and the difference between
 {{{
 get_transient()
 }}}
  and
 {{{
 get_site_transient()
 }}}

 We do not explain why/that  get_site_transient is related to the entire
 network and not to the single network site.

 The description only says: "Retrieves the value of a site transient."

 This doesn't seem right because get_site_transient() gets the entire
 network's transient, global accessible for all network sites, including
 the main site.

 It does not apply to a particular sub-network site only, which is
 implicated by that description.

 For instance, this is so misleading that we wrote an extensive explanation
 for
 {{{
 get_option()
 }}}
  and
 {{{
 get_site_option()
 }}}

 We should do the same for get_transient().

 I often stumble over more or less inconsistent or unclear function
 references and would like to get permission to correct such small issues
 when I find them the next time.

 Who can I contact to get permission to write to the docs?
 If that's not possible, what is the official way to get such changes into
 the docs?

 Sources:
 https://developer.wordpress.org/reference/functions/get_transient/
 https://developer.wordpress.org/reference/functions/get_site_transient/
 https://developer.wordpress.org/reference/functions/get_option/#source
 (edited)

-- 
Ticket URL: <https://meta.trac.wordpress.org/ticket/5428>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org