WordPress.org

Make WordPress Core

Changeset 34640


Ignore:
Timestamp:
09/27/2015 09:51:18 PM (5 years ago)
Author:
DrewAPicture
Message:

Docs: Vastly improve documentation for themes_api().

Adds:

  • A hash notation with descriptions for all accepted arguments
  • A matrix-like data table demonstrating which arguments are available for the different $action types
  • A better summary and description with linked hooks
  • An improved return description with a link to external information

Props ocean90.
See #34036.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/theme.php

    r33820 r34640  
    297297
    298298/**
    299  * Retrieve theme installer pages from WordPress Themes API.
     299 * Retrieves theme installer pages from the WordPress.org Themes API.
    300300 *
    301301 * It is possible for a theme to override the Themes API result with three
     
    304304 * overriding the filters.
    305305 *
    306  * The first filter, 'themes_api_args', is for the args and gives the action as
    307  * the second parameter. The hook for 'themes_api_args' must ensure that an
    308  * object is returned.
    309  *
    310  * The second filter, 'themes_api', is the result that would be returned.
     306 * The first filter, {@see 'themes_api_args'}, is for the args and gives the action
     307 * as the second parameter. The hook for {@see 'themes_api_args'} must ensure that
     308 * an object is returned.
     309 *
     310 * The second filter, {@see 'themes_api'}, is the result that would be returned.
     311 *
     312 * Supported arguments per action:
     313 *
     314 * | Argument Name      | 'query_plugins' | 'theme_information' | 'hot_tags' | 'feature_list'   |
     315 * | -------------------| :-------------: | :-----------------: | :--------: | :--------------: |
     316 * | `$slug`            | No              |  Yes                | No         | No               |
     317 * | `$per_page`        | Yes             |  No                 | No         | No               |
     318 * | `$page`            | Yes             |  No                 | No         | No               |
     319 * | `$number`          | No              |  No                 | Yes        | No               |
     320 * | `$search`          | Yes             |  No                 | No         | No               |
     321 * | `$tag`             | Yes             |  No                 | No         | No               |
     322 * | `$author`          | Yes             |  No                 | No         | No               |
     323 * | `$user`            | Yes             |  No                 | No         | No               |
     324 * | `$browse`          | Yes             |  No                 | No         | No               |
     325 * | `$locale`          | Yes             |  Yes                | No         | No               |
     326 * | `$fields`          | Yes             |  Yes                | No         | No               |
    311327 *
    312328 * @since 2.8.0
    313329 *
    314  * @param string       $action The requested action. Likely values are 'theme_information',
    315  *                             'feature_list', or 'query_themes'.
    316  * @param array|object $args   Optional. Arguments to serialize for the Theme Info API.
    317  * @return mixed
    318  */
    319 function themes_api( $action, $args = null ) {
     330 * @param string       $action API action to perform: 'query_themes', 'theme_information',
     331 *                             'hot_tags' or 'feature_list'.
     332 * @param array|object $args   {
     333 *     Optional. Array or object of arguments to serialize for the Plugin Info API.
     334 *
     335 *     @type string  $slug     The plugin slug. Default empty.
     336 *     @type int     $per_page Number of themes per page. Default 24.
     337 *     @type int     $page     Number of current page. Default 1.
     338 *     @type int     $number   Number of tags to be queried.
     339 *     @type string  $search   A search term. Default empty.
     340 *     @type string  $tag      Tag to filter themes. Default empty.
     341 *     @type string  $author   Username of an author to filter themes. Default empty.
     342 *     @type string  $user     Username to query for their favorites. Default empty.
     343 *     @type string  $browse   Browse view: 'featured', 'popular', 'updated', 'favorites'.
     344 *     @type string  $locale   Locale to provide context-sensitive results. Default is the value of get_locale().
     345 *     @type array   $fields   {
     346 *         Array of fields which should or should not be returned.
     347 *
     348 *         @type bool $description        Whether to return the theme full description. Default false.
     349 *         @type bool $sections           Whether to return the theme readme sections: description, installation,
     350 *                                        FAQ, screenshots, other notes, and changelog. Default false.
     351 *         @type bool $rating             Whether to return the rating in percent and total number of ratings.
     352 *                                        Default false.
     353 *         @type bool $ratings            Whether to return the number of rating for each star (1-5). Default false.
     354 *         @type bool $downloaded         Whether to return the download count. Default false.
     355 *         @type bool $downloadlink       Whether to return the download link for the package. Default false.
     356 *         @type bool $last_updated       Whether to return the date of the last update. Default false.
     357 *         @type bool $tags               Whether to return the assigned tags. Default false.
     358 *         @type bool $homepage           Whether to return the theme homepage link. Default false.
     359 *         @type bool $screenshots        Whether to return the screenshots. Default false.
     360 *         @type int  $screenshot_count   Number of screenshots to return. Default 1.
     361 *         @type bool $screenshot_url     Whether to return the URL of the first screenshot. Default false.
     362 *         @type bool $photon_screenshots Whether to return the screenshots via Photon. Default false.
     363 *         @type bool $template           Whether to return the slug of the parent theme. Default false.
     364 *         @type bool $parent             Whether to return the slug, name and homepage of the parent theme. Default false.
     365 *         @type bool $versions           Whether to return the list of all available versions. Default false.
     366 *         @type bool $theme_url          Whether to return theme's URL. Default false.
     367 *         @type bool $extended_author    Whether to return nicename or nicename and display name. Default false.
     368 *     }
     369 * }
     370 * @return object|array|WP_Error Response object or array on success, WP_Error on failure. See the
     371 *         {@link https://developer.wordpress.org/reference/functions/themes_api/ function reference article}
     372 *         for more information on the make-up of possible return objects depending on the value of `$action`.
     373 */
     374function themes_api( $action, $args = array() ) {
    320375
    321376    if ( is_array( $args ) ) {
Note: See TracChangeset for help on using the changeset viewer.