From c82483fcbc48b7b07ba099dc795341849cbb8aed Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Sun, 27 Sep 2015 22:28:38 +0000 Subject: [PATCH] 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. git-svn-id: https://develop.svn.wordpress.org/trunk@34647 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-admin/includes/plugin-install.php | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/wp-admin/includes/plugin-install.php b/src/wp-admin/includes/plugin-install.php index f4adbe4fdf..0a250eb5bc 100644 --- a/src/wp-admin/includes/plugin-install.php +++ b/src/wp-admin/includes/plugin-install.php @@ -125,15 +125,18 @@ function plugins_api( $action, $args = array() ) { $args = apply_filters( 'plugins_api_args', $args, $action ); /** - * Allows a plugin to override the WordPress.org Plugin Install API entirely. + * Filter the response for the current WordPress.org Plugin Install API request. * - * Please ensure that an object is returned. + * Passing a non-false value will effectively short-circuit the WordPress.org API request. + * + * If `$action` is 'query_plugins', 'plugin_information', or 'hot_categories', an object MUST + * be passed. If `$action` is 'hot_tags`, an array should be passed. * * @since 2.7.0 * - * @param bool|object $result The result object. Default false. - * @param string $action The type of information being requested from the Plugin Install API. - * @param object $args Plugin API arguments. + * @param false|object|array $result The result object or array. Default false. + * @param string $action The type of information being requested from the Plugin Install API. + * @param object $args Plugin API arguments. */ $res = apply_filters( 'plugins_api', false, $action, $args );