Changeset 34596

Timestamp:

09/26/2015 03:12:51 PM (9 years ago)

Author:

DrewAPicture

Message:

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.

File:

• trunk/src/wp-admin/includes/plugin-install.php (modified) (1 diff)

trunk/src/wp-admin/includes/plugin-install.php

@@ -8 +8 @@
 
 /**
- * Retrieve plugin installer pages from WordPress Plugins API.
+ * Retrieves plugin installer pages from WordPress Plugins API.
  *
  * It is possible for a plugin to override the Plugin API result with three
  * filters. Assume this is for plugins, which can extend on the Plugin Info to
- * offer more choices. This is very powerful and must be used with care, when
+ * offer more choices. This is very powerful and must be used with care when
  * overriding the filters.
  *
- * The first filter, 'plugins_api_args', is for the args and gives the action as
- * the second parameter. The hook for 'plugins_api_args' must ensure that an
- * object is returned.
- *
- * The second filter, 'plugins_api', is the result that would be returned.
+ * The first filter, {@see 'plugins_api_args'}, is for the args and gives the action
+ * as the second parameter. The hook for {@see 'plugins_api_args'} must ensure that
+ * an object is returned.
+ *
+ * The second filter, {@see 'plugins_api'}, is the result that would be returned.
  *
  * @since 2.7.0
  *
- * @param string $action
- * @param array|object $args Optional. Arguments to serialize for the Plugin Info API.
- * @return object plugins_api response object on success, WP_Error on failure.
- */
-function plugins_api($action, $args = null) {
+ * @param string       $action API action to perform: 'query_plugins', 'plugin_information',
+ *                             'hot_tags' or 'hot_categories'.
+ * @param array|object $args   {
+ *     Optional. Array or object of arguments to serialize for the Plugin Info API.
+ *
+ *     @type string  $slug     The plugin slug.
+ *     @type int     $per_page Number of plugins per page. Default 24.
+ *     @type int     $number   Number of tags or categories to be queried.
+ *     @type string  $locale   Locale to provide context-sensitive results. Default is the value of get_locale().
+ *     @type bool    $is_ssl   Whether links should be returned with https or not. Default false.
+ *     @type array   $fields   {
+ *         Array of fields which should or should not be returned.
+ *
+ *         @type bool $short_description Whether to return the plugin short description. Default true.
+ *         @type bool $description       Whether to return the plugin full description. Default false.
+ *         @type bool $sections          Whether to return the plugin readme sections: description, installation,
+ *                                       FAQ, screenshots, other notes, and changelog. Default false.
+ *         @type bool $tested            Whether to return the 'Compatible up to' value. Default true.
+ *         @type bool $requires          Whether to return the required WordPress version. Default true.
+ *         @type bool $rating            Whether to return the rating in percent and total number of ratings.
+ *                                       Default true.
+ *         @type bool $ratings           Whether to return the number of rating for each star (1-5). Default true.
+ *         @type bool $downloaded        Whether to return the download count. Default true.
+ *         @type bool $downloadlink      Whether to return the download link for the package. Default true.
+ *         @type bool $last_updated      Whether to return the date of the last update. Default true.
+ *         @type bool $added             Whether to return the date when the plugin was added to the wordpress.org
+ *                                       repository. Default true.
+ *         @type bool $tags              Whether to return the assigned tags. Default true.
+ *         @type bool $compatibility     Whether to return the WordPress compatibility list. Default true.
+ *         @type bool $homepage          Whether to return the plugin homepage link. Default true.
+ *         @type bool $versions          Whether to return the list of all available versions. Default false.
+ *         @type bool $donate_link       Whether to return the donation link. Default true.
+ *         @type bool $reviews           Whether to return the plugin reviews. Default false.
+ *         @type bool $banners           Whether to return the banner images links. Default false.
+ *         @type bool $icons             Whether to return the icon links. Default false.
+ *         @type bool $active_installs   Whether to return the number of active installs. Default false.
+ *         @type bool $group             Whether to return the assigned group. Default false.
+ *         @type bool $contributors      Whether to return the list of contributors. Default false.
+ *     }
+ * }
+ * @return object|WP_Error Response object on success, WP_Error on failure. See the
+ *         {@link https://developer.wordpress.org/reference/functions/plugins_api/ function reference article}
+ *         for more information on the make-up of possible return objects depending on the value of `$action`.
+ */
+function plugins_api( $action, $args = array() ) {
 
     if ( is_array( $args ) ) {