WordPress.org
Get WordPress

Make WordPress Core

Changeset 34225


Ignore:
Timestamp:
09/16/2015 09:39:33 AM (9 years ago)
Author:
DrewAPicture
Message:

Docs: Add more complete documentation for top-level object cache functionality.

Adds some @see tags for corresponding WP_Object_Cache methods to DocBlocks for top-level functions. Also adds a standard description for the @global tags, spacing for parameter docs readability, and finally, properly marks optional parameters as such.

See #32246.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r34010 r34225  
    1414 * @since 2.0.0
    1515 *
    16  * @global WP_Object_Cache $wp_object_cache
    17  *
    18  * @param int|string $key The cache key to use for retrieval later.
    19  * @param mixed $data The data to add to the cache.
    20  * @param string $group The group to add the cache to. Enables the same key to be used across groups.
    21  * @param int $expire When the cache data should expire, in seconds. Default is 0 (no expiry).
     16 * @see WP_Object_Cache::add()
     17 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
     18 *
     19 * @param int|string $key    The cache key to use for retrieval later.
     20 * @param mixed      $data   The data to add to the cache.
     21 * @param string     $group  Optional. The group to add the cache to. Enables the same key
     22 *                           to be used across groups. Default empty.
     23 * @param int        $expire Optional. When the cache data should expire, in seconds.
     24 *                           Default 0 (no expiration).
    2225 * @return bool False if cache key and group already exist, true on success.
    2326 */
    … …  
    3235 *
    3336 * This function has ceased to do anything since WordPress 2.5. The
    34  * functionality was removed along with the rest of the persistent cache. This
    35  * does not mean that plugins can't implement this function when they need to
    36  * make sure that the cache is cleaned up after WordPress no longer needs it.
    37  *
    38  * @since 2.0.0
    39  *
    40  * @return true Always returns True
     37 * functionality was removed along with the rest of the persistent cache.
     38 *
     39 * This does not mean that plugins can't implement this function when they need
     40 * to make sure that the cache is cleaned up after WordPress no longer needs it.
     41 *
     42 * @since 2.0.0
     43 *
     44 * @return true Always returns true.
    4145 */
    4246function wp_cache_close() {
    … …  
    4549
    4650/**
    47  * Decrement numeric cache item's value
     51 * Decrements numeric cache item's value.
    4852 *
    4953 * @since 3.3.0
    5054 *
    51  * @global WP_Object_Cache $wp_object_cache
    52  *
    53  * @param int|string $key The cache key to decrement.
    54  * @param int $offset The amount by which to decrement the item's value. Default is 1.
    55  * @param string $group The group the key is in.
     55 * @see WP_Object_Cache::decr()
     56 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
     57 *
     58 * @param int|string $key    The cache key to decrement.
     59 * @param int        $offset Optional. The amount by which to decrement the item's value. Default 1.
     60 * @param string     $group  Optional. The group the key is in. Default empty.
    5661 * @return false|int False on failure, the item's new value on success.
    5762 */
    … …  
    6772 * @since 2.0.0
    6873 *
    69  * @global WP_Object_Cache $wp_object_cache
    70  *
    71  * @param int|string $key What the contents in the cache are called.
    72  * @param string $group Where the cache contents are grouped.
     74 * @see WP_Object_Cache::delete()
     75 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
     76 *
     77 * @param int|string $key   What the contents in the cache are called.
     78 * @param string     $group Optional. Where the cache contents are grouped. Default empty.
    7379 * @return bool True on successful removal, false on failure.
    7480 */
    75 function wp_cache_delete($key, $group = '') {
     81function wp_cache_delete( $key, $group = '' ) {
    7682    global $wp_object_cache;
    7783
    … …  
    8490 * @since 2.0.0
    8591 *
    86  * @global WP_Object_Cache $wp_object_cache
     92 * @see WP_Object_Cache::flush()
     93 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
    8794 *
    8895 * @return bool False on failure, true on success
    … …  
    99106 * @since 2.0.0
    100107 *
    101  * @global WP_Object_Cache $wp_object_cache
    102  *
    103  * @param int|string $key The key under which the cache contents are stored.
    104  * @param string $group Where the cache contents are grouped.
    105  * @param bool $force Whether to force an update of the local cache from the persistent cache (default is false).
    106  * @param bool &$found Whether key was found in the cache. Disambiguates a return of false, a storable value.
     108 * @see WP_Object_Cache::get()
     109 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
     110 *
     111 * @param int|string  $key    The key under which the cache contents are stored.
     112 * @param string      $group  Optional. Where the cache contents are grouped. Default empty.
     113 * @param bool        $force  Optional. Whether to force an update of the local cache from the persistent
     114 *                            cache. Default false.
     115 * @param bool        &$found Optional. Whether the key was found in the cache. Disambiguates a return of false,
     116 *                            a storable value. Passed by reference. Default null.
    107117 * @return bool|mixed False on failure to retrieve contents or the cache
    108118 *                    contents on success
    … …  
    119129 * @since 3.3.0
    120130 *
    121  * @global WP_Object_Cache $wp_object_cache
    122  *
    123  * @param int|string $key The key for the cache contents that should be incremented.
    124  * @param int $offset The amount by which to increment the item's value. Default is 1.
    125  * @param string $group The group the key is in.
     131 * @see WP_Object_Cache::incr()
     132 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
     133 *
     134 * @param int|string $key    The key for the cache contents that should be incremented.
     135 * @param int        $offset Optional. The amount by which to increment the item's value. Default 1.
     136 * @param string     $group  Optional. The group the key is in. Default empty.
    126137 * @return false|int False on failure, the item's new value on success.
    127138 */
    … …  
    148159 * @since 2.0.0
    149160 *
    150  * @global WP_Object_Cache $wp_object_cache
    151  *
    152  * @param int|string $key The key for the cache data that should be replaced.
    153  * @param mixed $data The new data to store in the cache.
    154  * @param string $group The group for the cache data that should be replaced.
    155  * @param int $expire When to expire the cache contents, in seconds. Defaults to 0 (no expiry).
     161 * @see WP_Object_Cache::replace()
     162 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
     163 *
     164 * @param int|string $key    The key for the cache data that should be replaced.
     165 * @param mixed      $data   The new data to store in the cache.
     166 * @param string     $group  Optional. The group for the cache data that should be replaced.
     167 *                           Default empty.
     168 * @param int        $expire Optional. When to expire the cache contents, in seconds.
     169 *                           Default 0 (no expiration).
    156170 * @return bool False if original value does not exist, true if contents were replaced
    157171 */
    … …  
    169183 * @since 2.0.0
    170184 *
    171  * @global WP_Object_Cache $wp_object_cache
    172  *
    173  * @param int|string $key The cache key to use for retrieval later.
    174  * @param mixed $data The contents to store in the cache.
    175  * @param string $group Where to group the cache contents. Enables the same key to be used across groups.
    176  * @param int $expire When to expire the cache contents, in seconds. Defaults to 0 (no expiry).
     185 * @see WP_Object_Cache::set()
     186 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
     187 *
     188 * @param int|string $key    The cache key to use for retrieval later.
     189 * @param mixed      $data   The contents to store in the cache.
     190 * @param string     $group  Optional. Where to group the cache contents. Enables the same key
     191 *                           to be used across groups. Default empty.
     192 * @param int        $expire Optional. When to expire the cache contents, in seconds.
     193 *                           Default 0 (no expiration).
    177194 * @return bool False on failure, true on success
    178195 */
    … …  
    184201
    185202/**
    186  * Switch the interal blog id.
     203 * Switches the interal blog ID.
    187204 *
    188205 * This changes the blog id used to create keys in blog specific groups.
    … …  
    190207 * @since 3.5.0
    191208 *
    192  * @global WP_Object_Cache $wp_object_cache
    193  *
    194  * @param int $blog_id Blog ID
     209 * @see WP_Object_Cache::switch_to_blog()
     210 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
     211 *
     212 * @param int $blog_id Blog ID.
    195213 */
    196214function wp_cache_switch_to_blog( $blog_id ) {
    … …  
    205223 * @since 2.6.0
    206224 *
    207  * @global WP_Object_Cache $wp_object_cache
    208  *
    209  * @param string|array $groups A group or an array of groups to add
     225 * @see WP_Object_Cache::add_global_groups()
     226 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
     227 *
     228 * @param string|array $groups A group or an array of groups to add.
    210229 */
    211230function wp_cache_add_global_groups( $groups ) {
    … …  
    220239 * @since 2.6.0
    221240 *
    222  * @param string|array $groups A group or an array of groups to add
     241 * @param string|array $groups A group or an array of groups to add.
    223242 */
    224243function wp_cache_add_non_persistent_groups( $groups ) {
    … …  
    227246
    228247/**
    229  * Reset internal cache keys and structures. If the cache backend uses global
    230  * blog or site IDs as part of its cache keys, this function instructs the
    231  * backend to reset those keys and perform any cleanup since blog or site IDs
    232  * have changed since cache init.
     248 * Reset internal cache keys and structures.
     249 *
     250 * If the cache backend uses global blog or site IDs as part of its cache keys,
     251 * this function instructs the backend to reset those keys and perform any cleanup
     252 * since blog or site IDs have changed since cache init.
    233253 *
    234254 * This function is deprecated. Use wp_cache_switch_to_blog() instead of this
    … …  
    239259 *
    240260 * @since 2.6.0
    241  * @deprecated 3.5.0
    242  *
    243  * @global WP_Object_Cache $wp_object_cache
     261 * @deprecated 3.5.0 WP_Object_Cache::reset()
     262 * @see WP_Object_Cache::reset()
     263 *
     264 * @global WP_Object_Cache $wp_object_cache Object cache global instance.
    244265 */
    245266function wp_cache_reset() {
    246     _deprecated_function( __FUNCTION__, '3.5' );
     267    _deprecated_function( __FUNCTION__, '3.5', 'wp_cache_switch_to_blog()' );
    247268
    248269    global $wp_object_cache;
Note: See TracChangeset for help on using the changeset viewer.