From ebf33057229fc1687e362e52c7f1a60e757db250 Mon Sep 17 00:00:00 2001
From: Drew Jaynes <drewapicture@git.wordpress.org>
Date: Fri, 20 Sep 2013 02:21:44 +0000
Subject: [PATCH] Inline documentation for hooks in
 wp-admin/includes/plugin-install.php.

Props naomicbush.
See #25229.


git-svn-id: https://develop.svn.wordpress.org/trunk@25511 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/plugin-install.php | 40 ++++++++++++++++++++----
 1 file changed, 34 insertions(+), 6 deletions(-)

diff --git a/src/wp-admin/includes/plugin-install.php b/src/wp-admin/includes/plugin-install.php
index e1c1ec059d..105be01b31 100644
--- a/src/wp-admin/includes/plugin-install.php
+++ b/src/wp-admin/includes/plugin-install.php
@@ -34,11 +34,30 @@ function plugins_api($action, $args = null) {
 	if ( !isset($args->per_page) )
 		$args->per_page = 24;
 
-	// Allows a plugin to override the WordPress.org API entirely.
-	// Use the filter 'plugins_api_result' to merely add results.
-	// Please ensure that a object is returned from the following filters.
-	$args = apply_filters('plugins_api_args', $args, $action);
-	$res = apply_filters('plugins_api', false, $action, $args);
+	/**
+	 * Override the Plugin Install API arguments.
+	 *
+	 * Please ensure that an object is returned.
+	 *
+	 * @since 2.7.0
+	 *
+	 * @param object $args   Plugin API arguments.
+	 * @param string $action The type of information being requested from the Plugin Install API.
+	 */
+	$args = apply_filters( 'plugins_api_args', $args, $action );
+
+	/**
+	 * Allows a plugin to override the WordPress.org Plugin Install API entirely.
+	 *
+	 * Please ensure that an object is returned.
+	 *
+	 * @since 2.7.0
+	 *
+	 * @param bool|object         The result object. Default is 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 );
 
 	if ( false === $res ) {
 		$url = 'http://api.wordpress.org/plugins/info/1.0/';
@@ -64,7 +83,16 @@ function plugins_api($action, $args = null) {
 		$res->external = true;
 	}
 
-	return apply_filters('plugins_api_result', $res, $action, $args);
+	/**
+	 * Filter the Plugin Install API response results.
+	 *
+	 * @since 2.7.0
+	 *
+	 * @param object|WP_Error $res    Response object or WP_Error.
+	 * @param string          $action The type of information being requested from the Plugin Install API.
+	 * @param object          $args   Plugin API arguments.
+	 */
+	return apply_filters( 'plugins_api_result', $res, $action, $args );
 }
 
 /**