Opened 17 months ago
Last modified 2 months ago
#55645 new task (blessed)
Docs: Improve the documentation for `plugins_api()`.
Reported by: |
|
Owned by: | |
---|---|---|---|
Milestone: | 6.4 | Priority: | normal |
Severity: | normal | Version: | 2.7 |
Component: | Plugins | Keywords: | has-patch |
Focuses: | docs | Cc: |
Description (last modified by )
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
Change History (13)
#4
@
17 months ago
- Milestone changed from 6.0 to 6.1
6.0 RC1 is minutes away. Moving this one to 6.1.
#6
@
12 months ago
- Milestone changed from 6.1 to Future Release
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.
This ticket was mentioned in PR #4329 on WordPress/wordpress-develop by @lopo.
6 months ago
#7
- Keywords has-patch added; needs-patch removed
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
#8
@
6 months ago
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:
- improve the
@return
in the code - Improve the WordPress.org API page and link that one
- 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.
This ticket was mentioned in Slack in #core by chaion07. View the logs.
2 months ago
#11
@
2 months ago
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
Related: #55480
Follow-up to [53328]