[wp-trac] [WordPress Trac] #55645: Docs: Improve the documentation for `plugins_api()`.

[WordPress Trac]

#55645: Docs: Improve the documentation for `plugins_api()`.
----------------------------+-----------------------------
 Reporter:  costdev         |       Owner:  (none)
     Type:  task (blessed)  |      Status:  new
 Priority:  normal          |   Milestone:  Future Release
Component:  Plugins         |     Version:  2.7
 Severity:  normal          |  Resolution:
 Keywords:  has-patch       |     Focuses:  docs
----------------------------+-----------------------------

Comment (by 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.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/55645#comment:8>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform