Changeset 34651 for trunk/src/wp-admin/includes/theme.php

Timestamp:

09/27/2015 11:00:08 PM (9 years ago)

Author:

DrewAPicture

Message:

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.

File:

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

trunk/src/wp-admin/includes/theme.php

@@ -407 +407 @@
      * 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 );