Make WordPress Core

Opened 17 months ago

Last modified 2 months ago

#55645 new task (blessed)

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

Reported by: costdev's profile costdev Owned by:
Milestone: 6.4 Priority: normal
Severity: normal Version: 2.7
Component: Plugins Keywords: has-patch
Focuses: docs Cc:

Description (last modified by 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

Change History (13)

#1 @costdev
17 months ago

  • Keywords needs-patch added

#2 @costdev
17 months ago

  • Description modified (diff)

#3 @audrasjb
17 months ago

Related: #55480

Follow-up to [53328]

#4 @hellofromTonya
17 months ago

  • Milestone changed from 6.0 to 6.1

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

#5 @desrosj
12 months ago

Related: #51126.

#6 @audrasjb
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 @lopo
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:

  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.

#9 @SergeyBiryukov
6 months ago

  • Milestone changed from Future Release to 6.3

This ticket was mentioned in Slack in #core by chaion07. View the logs.


2 months ago

#11 @chaion07
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

This ticket was mentioned in Slack in #core by audrasjb. View the logs.


2 months ago

#13 @audrasjb
2 months ago

  • Milestone changed from 6.3 to 6.4

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.

Note: See TracTickets for help on using tickets.