Changeset 34647

Timestamp:

09/27/2015 10:28:38 PM (10 years ago)

Author:

DrewAPicture

Message:

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.

File:

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

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

@@ -126 +126 @@
 
     /**
-     * Allows a plugin to override the WordPress.org Plugin Install API entirely.
-     *
-     * Please ensure that an object is returned.
+     * Filter the response for the current WordPress.org Plugin Install API request.
+     *
+     * 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 );