WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
06/27/2020 12:00:48 PM (5 years ago)
Author:
SergeyBiryukov
Message:

Docs: Improve DocBlocks in wp-includes/theme.php per the documentation standards.

See #49572.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r48171 r48189  
    2020 *     Optional. The search arguments.
    2121 *
    22  *     @type mixed $errors  True to return themes with errors, false to return themes without errors, null to return all themes.
    23  *                          Defaults to false.
    24  *     @type mixed $allowed (Multisite) True to return only allowed themes for a site. False to return only disallowed themes for a site.
    25  *                          'site' to return only site-allowed themes. 'network' to return only network-allowed themes.
    26  *                          Null to return all themes. Defaults to null.
    27  *     @type int   $blog_id (Multisite) The blog ID used to calculate which themes are allowed.
    28  *                          Defaults to 0, synonymous for the current blog.
     22 *     @type mixed $errors  True to return themes with errors, false to return
     23 *                          themes without errors, null to return all themes.
     24 *                          Default false.
     25 *     @type mixed $allowed (Multisite) True to return only allowed themes for a site.
     26 *                          False to return only disallowed themes for a site.
     27 *                          'site' to return only site-allowed themes.
     28 *                          'network' to return only network-allowed themes.
     29 *                          Null to return all themes. Default null.
     30 *     @type int   $blog_id (Multisite) The blog ID used to calculate which themes
     31 *                          are allowed. Default 0, synonymous for the current blog.
    2932 * }
    3033 * @return WP_Theme[] Array of WP_Theme objects.
    … …  
    103106 * @global array $wp_theme_directories
    104107 *
    105  * @param string $stylesheet Directory name for the theme. Optional. Defaults to current theme.
    106  * @param string $theme_root Absolute path of the theme root to look in. Optional. If not specified, get_raw_theme_root()
    107  *                           is used to calculate the theme root for the $stylesheet provided (or current theme).
    108  * @return WP_Theme Theme object. Be sure to check the object's exists() method if you need to confirm the theme's existence.
     108 * @param string $stylesheet Optional. Directory name for the theme. Defaults to current theme.
     109 * @param string $theme_root Optional. Absolute path of the theme root to look in.
     110 *                           If not specified, get_raw_theme_root() is used to calculate
     111 *                           the theme root for the $stylesheet provided (or current theme).
     112 * @return WP_Theme Theme object. Be sure to check the object's exists() method
     113 *                  if you need to confirm the theme's existence.
    109114 */
    110115function wp_get_theme( $stylesheet = '', $theme_root = '' ) {
    … …  
    131136 *
    132137 * @since 3.5.0
    133  * @param bool $clear_update_cache Whether to clear the Theme updates cache
     138 * @param bool $clear_update_cache Whether to clear the theme updates cache.
    134139 */
    135140function wp_clean_themes_cache( $clear_update_cache = true ) {
    … …  
    148153 * @since 3.0.0
    149154 *
    150  * @return bool true if a child theme is in use, false otherwise.
     155 * @return bool True if a child theme is in use, false otherwise.
    151156 */
    152157function is_child_theme() {
    … …  
    157162 * Retrieves name of the current stylesheet.
    158163 *
    159  * The theme name that the administrator has currently set the front end theme
    160  * as.
    161  *
    162  * For all intents and purposes, the template name and the stylesheet name are
    163  * going to be the same for most cases.
     164 * The theme name that is currently set as the front end theme.
     165 *
     166 * For all intents and purposes, the template name and the stylesheet name
     167 * are going to be the same for most cases.
    164168 *
    165169 * @since 1.5.0
    … …  
    361365
    362366/**
    363  * Retrieve theme roots.
     367 * Retrieves theme roots.
    364368 *
    365369 * @since 2.9.0
    … …  
    367371 * @global array $wp_theme_directories
    368372 *
    369  * @return array|string An array of theme roots keyed by template/stylesheet or a single theme root if all themes have the same root.
     373 * @return array|string An array of theme roots keyed by template/stylesheet
     374 *                      or a single theme root if all themes have the same root.
    370375 */
    371376function get_theme_roots() {
    … …  
    385390
    386391/**
    387  * Register a directory that contains themes.
     392 * Registers a directory that contains themes.
    388393 *
    389394 * @since 2.9.0
    … …  
    391396 * @global array $wp_theme_directories
    392397 *
    393  * @param string $directory Either the full filesystem path to a theme folder or a folder within WP_CONTENT_DIR
     398 * @param string $directory Either the full filesystem path to a theme folder
     399 *                          or a folder within WP_CONTENT_DIR.
    394400 * @return bool
    395401 */
    … …  
    419425
    420426/**
    421  * Search all registered theme directories for complete and valid themes.
     427 * Searches all registered theme directories for complete and valid themes.
    422428 *
    423429 * @since 2.9.0
    … …  
    425431 * @global array $wp_theme_directories
    426432 *
    427  * @param bool $force Optional. Whether to force a new directory scan. Defaults to false.
    428  * @return array|false Valid themes found
     433 * @param bool $force Optional. Whether to force a new directory scan. Default false.
     434 * @return array|false Valid themes found on success, false on failure.
    429435 */
    430436function search_theme_directories( $force = false ) {
    … …  
    464470     *
    465471     * @param bool   $cache_expiration Whether to get the cache of the theme directories. Default false.
    466      * @param string $cache_directory  Directory to be searched for the cache.
     472     * @param string $context          The class or function name calling the filter.
    467473     */
    468474    $cache_expiration = apply_filters( 'wp_cache_themes_persistently', false, 'search_theme_directories' );
     475
    469476    if ( $cache_expiration ) {
    470477        $cached_roots = get_site_transient( 'theme_roots' );
    … …  
    560567
    561568/**
    562  * Retrieve path to themes directory.
     569 * Retrieves path to themes directory.
    563570 *
    564571 * Does not have trailing slash.
    … …  
    603610
    604611/**
    605  * Retrieve URI for themes directory.
     612 * Retrieves URI for themes directory.
    606613 *
    607614 * Does not have trailing slash.
    … …  
    656663
    657664/**
    658  * Get the raw theme root relative to the content directory with no filters applied.
     665 * Gets the raw theme root relative to the content directory with no filters applied.
    659666 *
    660667 * @since 3.1.0
    … …  
    696703
    697704/**
    698  * Display localized stylesheet link element.
     705 * Displays localized stylesheet link element.
    699706 *
    700707 * @since 2.1.0
    … …  
    727734 * @global array                $sidebars_widgets
    728735 *
    729  * @param string $stylesheet Stylesheet name
     736 * @param string $stylesheet Stylesheet name.
    730737 */
    731738function switch_theme( $stylesheet ) {
    … …  
    829836 * Will switch theme to the fallback theme if current theme does not validate.
    830837 *
    831  * You can use the {@see 'validate_current_theme'} filter to return false to
    832  * disable this functionality.
     838 * You can use the {@see 'validate_current_theme'} filter to return false to disable
     839 * this functionality.
    833840 *
    834841 * @since 1.5.0
    … …  
    870877     * If we're in an invalid state but WP_DEFAULT_THEME doesn't exist,
    871878     * switch to the latest core default theme that's installed.
     879     *
    872880     * If it turns out that this latest core default theme is our current
    873881     * theme, then there's nothing we can do about that, so we have to bail,
    … …  
    958966
    959967/**
    960  * Retrieve all theme modifications.
     968 * Retrieves all theme modifications.
    961969 *
    962970 * @since 3.1.0
    … …  
    982990
    983991/**
    984  * Retrieve theme modification value for the current theme.
     992 * Retrieves theme modification value for the current theme.
    985993 *
    986994 * If the modification name does not exist, then the $default will be passed
    … …  
    10251033
    10261034/**
    1027  * Update theme modification value for the current theme.
     1035 * Updates theme modification value for the current theme.
    10281036 *
    10291037 * @since 2.1.0
    … …  
    10551063
    10561064/**
    1057  * Remove theme modification name from current theme list.
    1058  *
    1059  * If removing the name also removes all elements, then the entire option will
    1060  * be removed.
     1065 * Removes theme modification name from current theme list.
     1066 *
     1067 * If removing the name also removes all elements, then the entire option
     1068 * will be removed.
    10611069 *
    10621070 * @since 2.1.0
    … …  
    10821090
    10831091/**
    1084  * Remove theme modifications option for current theme.
     1092 * Removes theme modifications option for current theme.
    10851093 *
    10861094 * @since 2.1.0
    … …  
    11341142
    11351143/**
    1136  * Check whether a header image is set or not.
     1144 * Checks whether a header image is set or not.
    11371145 *
    11381146 * @since 4.2.0
    … …  
    11471155
    11481156/**
    1149  * Retrieve header image for custom header.
     1157 * Retrieves header image for custom header.
    11501158 *
    11511159 * @since 2.1.0
    … …  
    11681176
    11691177/**
    1170  * Create image tag markup for a custom header image.
     1178 * Creates image tag markup for a custom header image.
    11711179 *
    11721180 * @since 4.4.0
    … …  
    12351243
    12361244/**
    1237  * Display the image markup for a custom header image.
     1245 * Displays the image markup for a custom header image.
    12381246 *
    12391247 * @since 4.4.0
    … …  
    12461254
    12471255/**
    1248  * Get random header image data from registered images in theme.
     1256 * Gets random header image data from registered images in theme.
    12491257 *
    12501258 * @since 3.4.0
    … …  
    12521260 * @access private
    12531261 *
    1254  * @global array  $_wp_default_headers
     1262 * @global array $_wp_default_headers
    12551263 *
    12561264 * @return object
    … …  
    12901298
    12911299/**
    1292  * Get random header image url from registered images in theme.
     1300 * Gets random header image URL from registered images in theme.
    12931301 *
    12941302 * @since 3.2.0
    12951303 *
    1296  * @return string Path to header image
     1304 * @return string Path to header image.
    12971305 */
    12981306function get_random_header_image() {
    … …  
    13071315
    13081316/**
    1309  * Check if random header image is in use.
     1317 * Checks if random header image is in use.
    13101318 *
    13111319 * Always true if user expressly chooses the option in Appearance > Header.
    … …  
    13151323 * @since 3.2.0
    13161324 *
    1317  * @param string $type The random pool to use. any|default|uploaded
     1325 * @param string $type The random pool to use. Possible values include 'any',
     1326 *                     'default', 'uploaded'. Default 'any'.
    13181327 * @return bool
    13191328 */
    … …  
    13401349
    13411350/**
    1342  * Display header image URL.
     1351 * Displays header image URL.
    13431352 *
    13441353 * @since 2.1.0
    … …  
    13531362
    13541363/**
    1355  * Get the header images uploaded for the current theme.
     1364 * Gets the header images uploaded for the current theme.
    13561365 *
    13571366 * @since 3.2.0
    … …  
    14011410
    14021411/**
    1403  * Get the header image data.
     1412 * Gets the header image data.
    14041413 *
    14051414 * @since 3.4.0
    … …  
    14461455
    14471456/**
    1448  * Register a selection of default headers to be displayed by the custom header admin UI.
     1457 * Registers a selection of default headers to be displayed by the custom header admin UI.
    14491458 *
    14501459 * @since 3.0.0
    … …  
    14621471
    14631472/**
    1464  * Unregister default headers.
     1473 * Unregisters default headers.
    14651474 *
    14661475 * This function must be called after register_default_headers() has already added the
    … …  
    14891498
    14901499/**
    1491  * Check whether a header video is set or not.
     1500 * Checks whether a header video is set or not.
    14921501 *
    14931502 * @since 4.7.0
    … …  
    15021511
    15031512/**
    1504  * Retrieve header video URL for custom header.
     1513 * Retrieves header video URL for custom header.
    15051514 *
    15061515 * Uses a local video if present, or falls back to an external video.
    … …  
    15371546
    15381547/**
    1539  * Display header video URL.
     1548 * Displays header video URL.
    15401549 *
    15411550 * @since 4.7.0
    … …  
    15501559
    15511560/**
    1552  * Retrieve header video settings.
     1561 * Retrieves header video settings.
    15531562 *
    15541563 * @since 4.7.0
    … …  
    15941603
    15951604/**
    1596  * Check whether a custom header is set or not.
     1605 * Checks whether a custom header is set or not.
    15971606 *
    15981607 * @since 4.7.0
    … …  
    16291638
    16301639    /**
    1631      * Modify whether the custom header video is eligible to show on the current page.
     1640     * Filters whether the custom header video is eligible to show on the current page.
    16321641     *
    16331642     * @since 4.7.0
    … …  
    16411650
    16421651/**
    1643  * Retrieve the markup for a custom header.
     1652 * Retrieves the markup for a custom header.
    16441653 *
    16451654 * The container div will always be returned in the Customizer preview.
    … …  
    16611670
    16621671/**
    1663  * Print the markup for a custom header.
     1672 * Prints the markup for a custom header.
    16641673 *
    16651674 * A container div will always be printed in the Customizer preview.
    … …  
    16821691
    16831692/**
    1684  * Retrieve background image for custom background.
     1693 * Retrieves background image for custom background.
    16851694 *
    16861695 * @since 3.0.0
    … …  
    16931702
    16941703/**
    1695  * Display background image path.
     1704 * Displays background image path.
    16961705 *
    16971706 * @since 3.0.0
    … …  
    17021711
    17031712/**
    1704  * Retrieve value for custom background color.
     1713 * Retrieves value for custom background color.
    17051714 *
    17061715 * @since 3.0.0
    … …  
    17131722
    17141723/**
    1715  * Display background color value.
     1724 * Displays background color value.
    17161725 *
    17171726 * @since 3.0.0
    … …  
    18031812
    18041813/**
    1805  * Render the Custom CSS style element.
     1814 * Renders the Custom CSS style element.
    18061815 *
    18071816 * @since 4.7.0
    … …  
    18201829
    18211830/**
    1822  * Fetch the `custom_css` post for a given theme.
     1831 * Fetches the `custom_css` post for a given theme.
    18231832 *
    18241833 * @since 4.7.0
    … …  
    18711880
    18721881/**
    1873  * Fetch the saved Custom CSS content for rendering.
     1882 * Fetches the saved Custom CSS content for rendering.
    18741883 *
    18751884 * @since 4.7.0
    … …  
    19041913
    19051914/**
    1906  * Update the `custom_css` post for a given theme.
     1915 * Updates the `custom_css` post for a given theme.
    19071916 *
    19081917 * Inserts a `custom_css` post when one doesn't yet exist.
    … …  
    20042013
    20052014/**
    2006  * Add callback for custom TinyMCE editor stylesheets.
     2015 * Adds callback for custom TinyMCE editor stylesheets.
    20072016 *
    20082017 * The parameter $stylesheet is the name of the stylesheet, relative to
    … …  
    20622071
    20632072/**
    2064  * Retrieve any registered editor stylesheet URLs.
     2073 * Retrieves any registered editor stylesheet URLs.
    20652074 *
    20662075 * @since 4.0.0
    … …  
    21182127
    21192128/**
    2120  * Expand a theme's starter content configuration using core-provided data.
     2129 * Expands a theme's starter content configuration using core-provided data.
    21212130 *
    21222131 * @since 4.7.0
    … …  
    28342843
    28352844/**
    2836  * Do not use. Removes theme support internally without knowledge of those not used by
    2837  * themes directly.
     2845 * Do not use. Removes theme support internally without knowledge of those not used
     2846 * by themes directly.
    28382847 *
    28392848 * @access private
    … …  
    29953004
    29963005/**
    2997  * Registers a theme feature for use in {@see add_theme_support}.
    2998  *
    2999  * This does not indicate that the current theme supports the feature, it only describes the feature's supported options.
     3006 * Registers a theme feature for use in add_theme_support().
     3007 *
     3008 * This does not indicate that the current theme supports the feature, it only describes
     3009 * the feature's supported options.
    30003010 *
    30013011 * @since 5.5.0
     3012 *
     3013 * @see add_theme_support()
    30023014 *
    30033015 * @global $_wp_registered_theme_features
    … …  
    30053017 * @param string $feature The name uniquely identifying the feature.
    30063018 * @param array $args {
    3007  *      Data used to describe the theme
    3008  *
    3009  *      @type string     $type         The type of data associated with this feature. Defaults to 'boolean'.
    3010  *                                     Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'.
    3011  *      @type boolean    $variadic     Does this feature utilize the variadic support of {@see add_theme_support()},
    3012  *                                     or are all arguments specified as the second parameter. Must be used with the "array" type.
    3013  *      @type string     $description  A short description of the feature. Included in the Themes REST API schema. Intended for developers.
     3019 *      Data used to describe the theme.
     3020 *
     3021 *      @type string     $type         The type of data associated with this feature.
     3022 *                                     Valid values are 'string', 'boolean', 'integer',
     3023 *                                     'number', 'array', and 'object'. Defaults to 'boolean'.
     3024 *      @type boolean    $variadic     Does this feature utilize the variadic support
     3025 *                                     of add_theme_support(), or are all arguments specified
     3026 *                                     as the second parameter. Must be used with the "array" type.
     3027 *      @type string     $description  A short description of the feature. Included in
     3028 *                                     the Themes REST API schema. Intended for developers.
    30143029 *      @type bool|array $show_in_rest {
    3015  *          Whether this feature should be included in the Themes REST API endpoint. Defaults to not being included.
    3016  *          When registering an 'array' or 'object' type, this argument must be an array with the 'schema' key.
    3017  *
    3018  *          @type array    $schema           Specifies the JSON Schema definition describing the feature. If any objects in the schema
    3019  *                                           do not include the 'additionalProperties' keyword, it is set to false.
    3020  *          @type string   $name             An alternate name to be use as the property name in the REST API.
    3021  *          @type callable $prepare_callback A function used to format the theme support in the REST API. Receives the raw theme support value.
     3030 *          Whether this feature should be included in the Themes REST API endpoint.
     3031 *          Defaults to not being included. When registering an 'array' or 'object' type,
     3032 *          this argument must be an array with the 'schema' key.
     3033 *
     3034 *          @type array    $schema           Specifies the JSON Schema definition describing
     3035 *                                           the feature. If any objects in the schema do not include
     3036 *                                           the 'additionalProperties' keyword, it is set to false.
     3037 *          @type string   $name             An alternate name to be used as the property name
     3038 *                                           in the REST API.
     3039 *          @type callable $prepare_callback A function used to format the theme support in the REST API.
     3040 *                                           Receives the raw theme support value.
    30223041 *      }
    30233042 * }
    … …  
    30563075
    30573076    if ( ! in_array( $args['type'], array( 'string', 'boolean', 'integer', 'number', 'array', 'object' ), true ) ) {
    3058         return new WP_Error( 'invalid_type', __( 'The feature "type" is not valid JSON Schema type.' ) );
     3077        return new WP_Error(
     3078            'invalid_type',
     3079            __( 'The feature "type" is not valid JSON Schema type.' )
     3080        );
    30593081    }
    30603082
    30613083    if ( true === $args['variadic'] && 'array' !== $args['type'] ) {
    3062         return new WP_Error( 'variadic_must_be_array', __( 'When registering a "variadic" theme feature, the "type" must be an "array".' ) );
     3084        return new WP_Error(
     3085            'variadic_must_be_array',
     3086            __( 'When registering a "variadic" theme feature, the "type" must be an "array".' )
     3087        );
    30633088    }
    30643089
    30653090    if ( false !== $args['show_in_rest'] && in_array( $args['type'], array( 'array', 'object' ), true ) ) {
    30663091        if ( ! is_array( $args['show_in_rest'] ) || empty( $args['show_in_rest']['schema'] ) ) {
    3067             return new WP_Error( 'missing_schema', __( 'When registering an "array" or "object" feature to show in the REST API, the feature\'s schema must also be defined.' ) );
     3092            return new WP_Error(
     3093                'missing_schema',
     3094                __( 'When registering an "array" or "object" feature to show in the REST API, the feature\'s schema must also be defined.' )
     3095            );
    30683096        }
    30693097
    30703098        if ( 'array' === $args['type'] && ! isset( $args['show_in_rest']['schema']['items'] ) ) {
    3071             return new WP_Error( 'missing_schema_items', __( 'When registering an "array" feature, the feature\'s schema must include the "items" keyword.' ) );
     3099            return new WP_Error(
     3100                'missing_schema_items',
     3101                __( 'When registering an "array" feature, the feature\'s schema must include the "items" keyword.' )
     3102            );
    30723103        }
    30733104
    30743105        if ( 'object' === $args['type'] && ! isset( $args['show_in_rest']['schema']['properties'] ) ) {
    3075             return new WP_Error( 'missing_schema_properties', __( 'When registering an "object" feature, the feature\'s schema must include the "properties" keyword.' ) );
     3106            return new WP_Error(
     3107                'missing_schema_properties',
     3108                __( 'When registering an "object" feature, the feature\'s schema must include the "properties" keyword.' )
     3109            );
    30763110        }
    30773111    }
    … …  
    30793113    if ( is_array( $args['show_in_rest'] ) ) {
    30803114        if ( isset( $args['show_in_rest']['prepare_callback'] ) && ! is_callable( $args['show_in_rest']['prepare_callback'] ) ) {
    3081             return new WP_Error( 'invalid_rest_prepare_callback', __( 'The prepare_callback must be a callable function.' ) );
     3115            return new WP_Error(
     3116                'invalid_rest_prepare_callback',
     3117                __( 'The prepare_callback must be a callable function.' )
     3118            );
    30823119        }
    30833120
    … …  
    30913128        );
    30923129
    3093         if ( is_bool( $args['show_in_rest']['schema']['default'] ) && ! in_array( 'boolean', (array) $args['show_in_rest']['schema']['type'], true ) ) {
     3130        if ( is_bool( $args['show_in_rest']['schema']['default'] )
     3131            && ! in_array( 'boolean', (array) $args['show_in_rest']['schema']['type'], true )
     3132        ) {
    30943133            // Automatically include the "boolean" type when the default value is a boolean.
    30953134            $args['show_in_rest']['schema']['type'] = (array) $args['show_in_rest']['schema']['type'];
    … …  
    35233562
    35243563/**
    3525  * Make sure that auto-draft posts get their post_date bumped or status changed to draft to prevent premature garbage-collection.
     3564 * Makes sure that auto-draft posts get their post_date bumped or status changed to draft to prevent premature garbage-collection.
    35263565 *
    35273566 * When a changeset is updated but remains an auto-draft, ensure the post_date
Note: See TracChangeset for help on using the changeset viewer.