Changeset 25961

Timestamp:

10/27/2013 10:45:32 PM (11 years ago)

Author:

DrewAPicture

Message:

Inline documentation for hooks in wp-admin/includes/theme.php.

Props l10n for the initial patch.
Fixes #25732.

File:

• trunk/src/wp-admin/includes/theme.php (modified) (3 diffs)

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

@@ -267 +267 @@
  * @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) )
@@ -278 +279 @@
     if ( !isset($args->per_page) )
         $args->per_page = 24;
-
-    $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.
+    /**
+     * 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 used 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 used to query for installer pages from the Themes API.
+     */
+    $res = apply_filters( 'themes_api', false, $action, $args );
 
     if ( ! $res ) {
@@ -309 +334 @@
     }
 
-    return apply_filters('themes_api_result', $res, $action, $args);
-}
+    /**
+     * Filter the returned WordPress.org Themes API response.
+     *
+     * @since 2.8.0
+     *
+     * @param array|object $res    WordPress.org Themes API response.
+     * @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 WordPress.org Themes API.
+     */
+    return apply_filters( 'themes_api_result', $res, $action, $args );
+}