WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 4 years ago

#34035 closed defect (bug) (fixed)

Document $args parameter for plugins_api()

Reported by: ocean90 Owned by: ocean90
Milestone: 4.4 Priority: normal
Severity: normal Version:
Component: Plugins Keywords: has-patch
Focuses: docs Cc:
PR Number:

Description

The $args parameter in plugins_api() needs some docs.

Attachments (6)

34035.patch (2.7 KB) - added by ocean90 4 years ago.
34035.2.patch (3.3 KB) - added by ocean90 4 years ago.
34035.3.patch (5.2 KB) - added by DrewAPicture 4 years ago.
34035.4.patch (5.2 KB) - added by DrewAPicture 4 years ago.
couple typos
34035.5.patch (2.0 KB) - added by ocean90 4 years ago.
34035.6.patch (2.5 KB) - added by ocean90 4 years ago.

Download all attachments as: .zip

Change History (23)

@ocean90
4 years ago

#1 @DrewAPicture
4 years ago

34035.patch is a really great start. All we need now are descriptions for all of the values in the $fields array.

#2 @ocean90
4 years ago

I think we should also switch the default value of $args. It should be an empty array otherwise plugins_api( 'hot_tags' ); is producing a warning: "Warning: Creating default object from empty value in /src/wp-admin/includes/plugin-install.php on line 71".

@ocean90
4 years ago

#3 @DrewAPicture
4 years ago

  • Owner set to DrewAPicture
  • Status changed from new to reviewing

34035.2.patch looks a lot better. The keyword we typically use with booleans is "whether", so "Whether to return _. Default true", for instance. I can fix that on commit.

After some discussion with @ocean90, I think our best course of action is to provide supplementary information on success object structs as an "Explanation" on the function reference page. This would be instead of trying to jam all of that into the inline docs. The major upside is that we generally have a lot more control over formatting, external linking, etc. in the WordPress editor on DevHub than we do in hash notations currently.

@DrewAPicture
4 years ago

couple typos

#4 @DrewAPicture
4 years ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 34596:

Docs: Add much-needed (and awesome) hash-notation-style documentation for the $args parameter in the plugins_api() DocBlock.

Also fixes up some formatting in the DocBlock summary and description, and adds a link to the function reference, where supplementary information on return object structs and formatting will live.

Props ocean90.
Fixes #34035.

#5 @ocean90
4 years ago

  • Keywords needs-patch added; has-patch removed
  • Resolution fixed deleted
  • Status changed from closed to reopened

I've missed some: $browse, $user, $search, $author, $tag, $installed_plugins, $page.

@ocean90
4 years ago

#6 @DrewAPicture
4 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

In 34631:

Docs: Add documentation for the $browse, $user, $search, $author, $tag, $installed_plugins, and $page parameters in plugins_api().

Props ocean90.
Fixes #34035.

@ocean90
4 years ago

#7 @ocean90
4 years ago

  • Keywords has-patch added; needs-patch removed
  • Resolution fixed deleted
  • Status changed from closed to reopened

34035.6.patch:

  • The function returns an array for hot_tags' and 'hot_categories'.
  • Add a matrix for which arguments are availablefor each of the actions.

#8 @ocean90
4 years ago

  • Status changed from reopened to reviewing

#9 @DrewAPicture
4 years ago

In 34641:

Docs: Further improve documentation for plugins_api().

  • Adds a matrix-like data table demonstrating which arguments are available for the different $action types
  • Adjusts the return types to accommodate an array for the 'hot_tags' $action choice

Props ocean90.
See #34035.

#10 @DrewAPicture
4 years ago

In 34642:

Docs: Update the DocBlock summary for plugins_api() to reflect the "WordPress.org" Plugins API.

See #34035.

#11 @DrewAPicture
4 years ago

In 34645:

Docs: Adjust the plugins_api() DocBlock description to clarify the "second" available hook, plugins_api, and add new information for the "third" hook, plugins_api_result.

See #34035.

#12 @DrewAPicture
4 years ago

In 34647:

Docs: Improve the hook documentation for the plugins_api filter.

Standardizes the hook doc summary and expands on expected behavior when short-circuiting the request, which is dependent on the $action type.

See #34035. See #32246.

#13 @DrewAPicture
4 years ago

In 34652:

Docs: Improve the hook documentation for the plugins_api_args filter.

Standardizes the hook doc summary and expands on the expected type for the $args parameter.

See #34035. See #32246.

#14 @DrewAPicture
4 years ago

In 34763:

Docs: Clarify the expected replacement element type if replacing the object or array in plugins_api() via the plugins_api hook.

If the $action type is 'query_plugins' or 'plugin_information', the API will return an object, thus an object should be passed if replacing it. For 'hot_tags' and 'hot_categories', the same logic applies, but with arrays instead.

See #34035.

#15 @DrewAPicture
4 years ago

  • Owner changed from DrewAPicture to ocean90

@ocean90 I think we're good on the docs aspect.

If 'hot_tags' and 'hot_categories' return an array as you said, should we not either cast that response as an object regardless or handle the array case? This would be for the case where the object/array is being replaced using the plugins_api hook. I suppose handling that in a separate ticket might be best.

#16 @DrewAPicture
4 years ago

In 34764:

Docs: Also clarify the expected element types depending on the value of $action in the hook doc for the plugins_api filter.

See [34763] for context.

See #34035.

#17 @DrewAPicture
4 years ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

Disregard my comment:15, I misread the code. Calling this fixed.

Note: See TracTickets for help on using tickets.