Docs: Improve the hook documentation for the `themes_api` filter.

Standardizes the hook doc summary and expands on expected behavior when short-circuiting the request, which is dependent on the `$action` type.

Also updates the expected types on the `$override` parameter.

See #34036. See #32246.

Built from https://develop.svn.wordpress.org/trunk@34651


git-svn-id: http://core.svn.wordpress.org/trunk@34615 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/includes/theme.php

@@ -406,15 +406,17 @@ function themes_api( $action, $args = array() ) {
 	/**
 	 * 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.
+	 * Passing a non-false value will effectively short-circuit the WordPress.org API request.
+	 *
+	 * If `$action` is 'query_themes', 'theme_information', or 'feature_list', an object MUST
+	 * be passed. If `$action` is 'hot_tags`, an array should be passed.
 	 *
 	 * @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 used to query for installer pages from the Themes API.
+	 * @param false|object|array $override 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 used to query for installer pages from the Themes API.
 	 */
 	$res = apply_filters( 'themes_api', false, $action, $args );
 

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.4-alpha-34650';
+$wp_version = '4.4-alpha-34651';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.