Docs: Improve the documentation for `plugins_api()`.

[costdev]

The docblock for ​plugins_api() needs some improvement, including:

• it does not document the make-up of possible return values.
• it has a self-reference in the @return annotation.

Related ticket: #55480

[audrasjb]

Related: #55480

Follow-up to [53328]

[hellofromTonya]

6.0 RC1 is minutes away. Moving this one to 6.1.

[desrosj]

Related: #51126.

[audrasjb]

With WP 6.1 RC 1 scheduled tomorrow (Oct 10, 2022), there is not much time left to address this ticket. Given it still needs a patch, let's move this ticket to Future Release.

Ps: if you were about to send a patch and if you feel it is realistic to commit it in the next few hours, please feel free to move this ticket back to milestone 6.1.

Removes the unsupported value hot_categories for the action parameter from the docblock of plugins_api().

Trac ticket: https://core.trac.wordpress.org/ticket/55645

[lopo]

I had a look at this during the Contributor Day of WordCamp Torino 2023.

These same problems happen with theme_api():

it does not document the make-up of possible return values.
it has a self-reference in the @return annotation.

Moreover, documentation for plugins_api() mentions hot_categories as an accepted value for the action parameter, but it's not supported anymore by the v1.2 API ​https://api.wordpress.org/plugins/info/1.2/?action=hot_categories.

Ideally, we should probably point to ​https://codex.wordpress.org/WordPress.org_API#Plugins and ​https://codex.wordpress.org/WordPress.org_API#Themes if that page was up to date and contained the structures of the responses.

Speaking with @milana_cap, she also suggested simplifying the PHPDoc to move more complex info directly into the documentation project.

So we have 3 paths here:

1. improve the @return in the code
2. Improve the WordPress.org API page and link that one
3. Add the relevant missing info in the documentation project (and maybe move something else there too).

In the meantime, I've created a PR to fix the hot_categories issue.

[chaion07]

Thanks @costdev for reporting this. We reviewed this ticket once during a recent bug-scrub session and based on the feedback we are keeping the milestone intact since this is a docs-only ticket. Cheers!

Props to @costdev & @oglekler

[audrasjb]

As per today's bug scrub and since 6.3 RC2 is planned tomorrow, let's move it to 6.4.
Feel free to move it back to 6.3 if you feel it can be committed in the next few hours.