Ticket #25732: 25732.diff

src/wp-admin/includes/theme.php

@@ -266 +266 @@
  *
  * @since 2.8.0
  *
- * @param string $action
- * @param array|object $args Optional. Arguments to serialize for the Theme Info API.
+ * @param string       $action The requested action. Likely values are 'theme_information',
+ *                             'feature_list', or 'query_themes'.
+ * @param array|object $args   Optional. Arguments to serialize for the Theme Info API.
  * @return mixed
  */
-function themes_api($action, $args = null) {
+function themes_api( $action, $args = null ) {
 
         if ( is_array($args) )
                 $args = (object)$args;
 
         if ( !isset($args->per_page) )
                 $args->per_page = 24;
+        /**
+         * Filter arguments used to query for installer pages from the WordPress.org Themes API.
+         *
+         * Important: An object MUST be returned to this filter.
+         * 
+         * @since 2.8.0
+         * 
+         * @param object $args   Arguments to query for installer pages from the WordPress.org Themes API.
+         * @param string $action Requested action. Likely values are 'theme_information',
+         *                       'feature_list', or 'query_themes'.
+        */
+        $args = apply_filters( 'themes_api_args', $args, $action );
+        
+        /**
+         * Filter whether to override the WordPress.org Themes API.
+         *
+         * Returning a value of true to this filter allows a theme to completely
+         * override the built-in WordPress.org API.
+         * 
+         * @since 2.8.0
+         *
+         * @param bool   $bool   Whether to override the WordPress.org Themes API. Default false.
+         * @param string $action Requested action. Likely values are 'theme_information',
+         *                       'feature_list', or 'query_themes'.
+         * @param object $args   Arguments to query for installer pages from the Themes API.
+         */
+        $res = apply_filters( 'themes_api', false, $action, $args );
 
-        $args = apply_filters('themes_api_args', $args, $action); //NOTE: Ensure that an object is returned via this filter.
-        $res = apply_filters('themes_api', false, $action, $args); //NOTE: Allows a theme to completely override the builtin WordPress.org API.
-
         if ( ! $res ) {
                 $url = $http_url = 'http://api.wordpress.org/themes/info/1.0/';
                 if ( $ssl = wp_http_supports( array( 'ssl' ) ) )
@@ -308 +333 @@
                 }
         }
 
-        return apply_filters('themes_api_result', $res, $action, $args);
+        /**
+         * Filter the WordPress.org Themes API installer pages result.
+         *
+         * @since 2.8.0
+         *
+         * @param array|object $res    Response array or object.
+         * @param string       $action Requested action. Likely values are 'theme_information',
+         *                             'feature_list', or 'query_themes'.
+         * @param object       $args   Arguments used to query for installer pages from the Themes API.
+         */
+        return apply_filters( 'themes_api_result', $res, $action, $args );
 }