Add return types to docBlock instead of writing mixed and Improve docs for get_transient()

[ReneHermi]

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)

[dd32]

Hi :)

The Codex is a wiki and editable by anyone with a WordPress.org account, please feel free to make contributions there to make things clearer.

Documentation on developer.wordpress.org is managed by several teams depending on the section in question, however, for function-level documentation like this, it's auto-generated from the PHPDoc in WordPress core.

Some pages that might be of help:

• ​Documentation team handbook
• ​The Documentation team P2
• ​How to submit a Documentation fix
• ​The Core team handbook

Additionally, the above talks about SVN primarily, if GitHub is preferred, you can create a ​https://Core.Trac.WordPress.org/ ticket and then fork/PR the changes to ​https://github.com/wordpress/wordpress-develop instead.

I'm marking this ticket as invalid (we don't have a better status than that), as there's nothing actionable here for the meta team, other than to redirect you in the correct direction :)

[ReneHermi]

Hi @dd32 That was useful. Thanks for your help.
Have added it to core.trac: ​https://core.trac.wordpress.org/ticket/51278