Document $args parameter for plugins_api()

[ocean90]

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

[DrewAPicture]

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

[ocean90]

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".

[DrewAPicture]

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]

couple typos

[DrewAPicture]

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.

[ocean90]

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

[DrewAPicture]

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]

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.

[DrewAPicture]

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.

[DrewAPicture]

In 34642:

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

See #34035.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

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.

[DrewAPicture]

@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.

[DrewAPicture]

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.

[DrewAPicture]

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