Ticket #25229: wp-admin-includes-plugin-install.25229.diff

wp-admin/includes/plugin-install.php

@@ -22 +22 @@
  *
  * @since 2.7.0
  *
- * @param string $action
- * @param array|object $args Optional. Arguments to serialize for the Plugin Info API.
+ * @param string       $action Requested information.
+ * @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) {
@@ -34 +34 @@
         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.
+        /**
+         * Override the Plugin API arguments.
+         *
+         * Please ensure that an object is returned.
+         *
+         * @since 2.7.0
+         *
+         * @param object $args   Plugin API arguments.
+         * @param string $action Requested information.
+         */
         $args = apply_filters('plugins_api_args', $args, $action);
+
+        /**
+         * Allows a plugin to override the WordPress.org 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 Requested information.
+         * @param object      $args   Plugin API arguments.
+         */
         $res = apply_filters('plugins_api', false, $action, $args);
 
         if ( false === $res ) {
@@ -64 +83 @@
                 $res->external = true;
         }
 
+        /**
+         * Merely add a result.
+         *
+         * @since 2.7.0
+         *
+         * @param object $res    Response object or WP_Error.
+         * @param string $action Requested information.
+         * @param object $args   Plugin API arguments.
+         */
         return apply_filters('plugins_api_result', $res, $action, $args);
 }
 
@@ -73 +101 @@
  * @since 2.7.0
  *
  * @param array $args
- * @return array
+ * @return array Popular tags.
  */
 function install_popular_tags( $args = array() ) {
         $key = md5(serialize($args));
@@ -90 +118 @@
         return $tags;
 }
 
+/**
+ * Display dashboard for the 'Install Plugins' page.
+ *
+ * @since 2.7.0
+ *
+ */
 function install_dashboard() {
         ?>
         <p><?php printf( __( 'Plugins extend and expand the functionality of WordPress. You may automatically install plugins from the <a href="%1$s">WordPress Plugin Directory</a> or upload a plugin in .zip format via <a href="%2$s">this page</a>.' ), 'http://wordpress.org/plugins/', self_admin_url( 'plugin-install.php?tab=upload' ) ); ?></p>
@@ -125 +159 @@
  * Display search form for searching plugins.
  *
  * @since 2.7.0
+ *
+ * @param bool $type_selector Choose a search type. Default is true.
  */
 function install_search_form( $type_selector = true ) {
         $type = isset($_REQUEST['type']) ? wp_unslash( $_REQUEST['type'] ) : 'term';
@@ -147 +183 @@
 
 /**
  * Upload from zip
+ *
  * @since 2.8.0
  *
- * @param string $page
+ * @param string $page Currently unused.
  */
 function install_plugins_upload( $page = 1 ) {
 ?>
@@ -167 +204 @@
 
 /**
  * Show a username form for the favorites page
+ *
  * @since 3.5.0
  *
  */
@@ -188 +226 @@
 /**
  * Display plugin content based on plugin list.
  *
+ * @global WP_Plugin_Install_List_Table $wp_list_table List of items to display.
+ *
  * @since 2.7.0
+ *
  */
 function display_plugins_table() {
         global $wp_list_table;
@@ -207 +248 @@
 /**
  * Determine the status we can perform on a plugin.
  *
+ * This function is called recursively, $loop prevents further loops.
+ *
  * @since 3.0.0
+ *
+ * @param array|object $api  Plugin API response object.
+ * @param bool         $loop Prevents further loops. Default is false.
+ * @return array Plugin status, install URL, and version.
  */
 function install_plugin_install_status($api, $loop = false) {
-        // this function is called recursively, $loop prevents further loops.
         if ( is_array($api) )
                 $api = (object) $api;
 
@@ -271 +317 @@
 /**
  * Display plugin information in dialog box form.
  *
+ * @global string $tab Requested information.
+ *
  * @since 2.7.0
+ *
  */
 function install_plugin_information() {
         global $tab;