Make WordPress Core

Opened 2 years 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: Future Release 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 (17)

#1 @costdev
2 years ago

  • Keywords needs-patch added

#2 @costdev
2 years ago

  • Description modified (diff)

#3 @audrasjb
2 years ago

Related: #55480

Follow-up to [53328]

#4 @hellofromTonya
2 years ago

  • Milestone changed from 6.0 to 6.1

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

#5 @desrosj
19 months ago

Related: #51126.

#6 @audrasjb
19 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.


12 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
12 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
12 months ago

  • Milestone changed from Future Release to 6.3

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


9 months ago

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


9 months ago

#13 @audrasjb
9 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.

#14 @huzaifaalmesbah
6 months ago

It looks like it needs to be moved to 6.5.

#15 @jorbin
6 months ago

  • Milestone changed from 6.4 to 6.5

Moving to 6.5 due to forward momentum

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


2 months ago

#17 @audrasjb
2 months ago

  • Milestone changed from 6.5 to Future Release

As per today's bug scrub: since this ticket didn't get its momentum back in cycle 6.5, let's move it to Future release.

Note: See TracTickets for help on using tickets.