WordPress.org

Making WordPress.org

Opened 7 weeks ago

Closed 7 weeks ago

Last modified 6 weeks ago

#5428 closed task (invalid)

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

Reported by: ReneHermi Owned by:
Milestone: Priority: high
Component: Codex Keywords:
Cc:

Description

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)

Change History (2)

#1 @dd32
7 weeks ago

  • Resolution set to invalid
  • Status changed from new to closed

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:

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

#2 @ReneHermi
6 weeks ago

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

Note: See TracTickets for help on using tickets.