WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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.

Built from https://develop.svn.wordpress.org/trunk@34225


git-svn-id: http://core.svn.wordpress.org/trunk@34189 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Drew Jaynes 2015-09-16 09:40:25 +00:00
parent a7ea95f53a
commit 4e4737685e
2 changed files with 73 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
wp-includes/cache.php
View File

@ -13,12 +13,15 @@
* *
* @since 2.0.0 * @since 2.0.0
* *
* @global WP_Object_Cache $wp_object_cache * @see WP_Object_Cache::add()
* @global WP_Object_Cache $wp_object_cache Object cache global instance.
* *
* @param int|string $key The cache key to use for retrieval later. * @param int|string $key The cache key to use for retrieval later.
* @param mixed $data The data to add to the cache. * @param mixed $data The data to add to the cache.
* @param string $group The group to add the cache to. Enables the same key to be used across groups. * @param string $group Optional. The group to add the cache to. Enables the same key
* @param int $expire When the cache data should expire, in seconds. Default is 0 (no expiry). * to be used across groups. Default empty.
* @param int $expire Optional. When the cache data should expire, in seconds.
* Default 0 (no expiration).
* @return bool False if cache key and group already exist, true on success. * @return bool False if cache key and group already exist, true on success.
*/ */
function wp_cache_add( $key, $data, $group = '', $expire = 0 ) { function wp_cache_add( $key, $data, $group = '', $expire = 0 ) {
@ -31,28 +34,30 @@ function wp_cache_add( $key, $data, $group = '', $expire = 0 ) {
* Closes the cache. * Closes the cache.
* *
* This function has ceased to do anything since WordPress 2.5. The * This function has ceased to do anything since WordPress 2.5. The
* functionality was removed along with the rest of the persistent cache. This * functionality was removed along with the rest of the persistent cache.
* does not mean that plugins can't implement this function when they need to *
* make sure that the cache is cleaned up after WordPress no longer needs it. * This does not mean that plugins can't implement this function when they need
* to make sure that the cache is cleaned up after WordPress no longer needs it.
* *
* @since 2.0.0 * @since 2.0.0
* *
* @return true Always returns True * @return true Always returns true.
*/ */
function wp_cache_close() { function wp_cache_close() {
return true; return true;
} }
/** /**
* Decrement numeric cache item's value * Decrements numeric cache item's value.
* *
* @since 3.3.0 * @since 3.3.0
* *
* @global WP_Object_Cache $wp_object_cache * @see WP_Object_Cache::decr()
* @global WP_Object_Cache $wp_object_cache Object cache global instance.
* *
* @param int|string $key The cache key to decrement. * @param int|string $key The cache key to decrement.
* @param int $offset The amount by which to decrement the item's value. Default is 1. * @param int $offset Optional. The amount by which to decrement the item's value. Default 1.
* @param string $group The group the key is in. * @param string $group Optional. The group the key is in. Default empty.
* @return false|int False on failure, the item's new value on success. * @return false|int False on failure, the item's new value on success.
*/ */
function wp_cache_decr( $key, $offset = 1, $group = '' ) { function wp_cache_decr( $key, $offset = 1, $group = '' ) {
@ -66,13 +71,14 @@ function wp_cache_decr( $key, $offset = 1, $group = '' ) {
* *
* @since 2.0.0 * @since 2.0.0
* *
* @global WP_Object_Cache $wp_object_cache * @see WP_Object_Cache::delete()
* @global WP_Object_Cache $wp_object_cache Object cache global instance.
* *
* @param int|string $key What the contents in the cache are called. * @param int|string $key What the contents in the cache are called.
* @param string $group Where the cache contents are grouped. * @param string $group Optional. Where the cache contents are grouped. Default empty.
* @return bool True on successful removal, false on failure. * @return bool True on successful removal, false on failure.
*/ */
function wp_cache_delete($key, $group = '') { function wp_cache_delete( $key, $group = '' ) {
global $wp_object_cache; global $wp_object_cache;
return $wp_object_cache->delete($key, $group); return $wp_object_cache->delete($key, $group);
@ -83,7 +89,8 @@ function wp_cache_delete($key, $group = '') {
* *
* @since 2.0.0 * @since 2.0.0
* *
* @global WP_Object_Cache $wp_object_cache * @see WP_Object_Cache::flush()
* @global WP_Object_Cache $wp_object_cache Object cache global instance.
* *
* @return bool False on failure, true on success * @return bool False on failure, true on success
*/ */
@ -98,12 +105,15 @@ function wp_cache_flush() {
* *
* @since 2.0.0 * @since 2.0.0
* *
* @global WP_Object_Cache $wp_object_cache * @see WP_Object_Cache::get()
* @global WP_Object_Cache $wp_object_cache Object cache global instance.
* *
* @param int|string $key The key under which the cache contents are stored. * @param int|string $key The key under which the cache contents are stored.
* @param string $group Where the cache contents are grouped. * @param string $group Optional. Where the cache contents are grouped. Default empty.
* @param bool $force Whether to force an update of the local cache from the persistent cache (default is false). * @param bool $force Optional. Whether to force an update of the local cache from the persistent
* @param bool &$found Whether key was found in the cache. Disambiguates a return of false, a storable value. * cache. Default false.
* @param bool &$found Optional. Whether the key was found in the cache. Disambiguates a return of false,
* a storable value. Passed by reference. Default null.
* @return bool|mixed False on failure to retrieve contents or the cache * @return bool|mixed False on failure to retrieve contents or the cache
* contents on success * contents on success
*/ */
@ -118,11 +128,12 @@ function wp_cache_get( $key, $group = '', $force = false, &$found = null ) {
* *
* @since 3.3.0 * @since 3.3.0
* *
* @global WP_Object_Cache $wp_object_cache * @see WP_Object_Cache::incr()
* @global WP_Object_Cache $wp_object_cache Object cache global instance.
* *
* @param int|string $key The key for the cache contents that should be incremented. * @param int|string $key The key for the cache contents that should be incremented.
* @param int $offset The amount by which to increment the item's value. Default is 1. * @param int $offset Optional. The amount by which to increment the item's value. Default 1.
* @param string $group The group the key is in. * @param string $group Optional. The group the key is in. Default empty.
* @return false|int False on failure, the item's new value on success. * @return false|int False on failure, the item's new value on success.
*/ */
function wp_cache_incr( $key, $offset = 1, $group = '' ) { function wp_cache_incr( $key, $offset = 1, $group = '' ) {
@ -147,12 +158,15 @@ function wp_cache_init() {
* *
* @since 2.0.0 * @since 2.0.0
* *
* @global WP_Object_Cache $wp_object_cache * @see WP_Object_Cache::replace()
* @global WP_Object_Cache $wp_object_cache Object cache global instance.
* *
* @param int|string $key The key for the cache data that should be replaced. * @param int|string $key The key for the cache data that should be replaced.
* @param mixed $data The new data to store in the cache. * @param mixed $data The new data to store in the cache.
* @param string $group The group for the cache data that should be replaced. * @param string $group Optional. The group for the cache data that should be replaced.
* @param int $expire When to expire the cache contents, in seconds. Defaults to 0 (no expiry). * Default empty.
* @param int $expire Optional. When to expire the cache contents, in seconds.
* Default 0 (no expiration).
* @return bool False if original value does not exist, true if contents were replaced * @return bool False if original value does not exist, true if contents were replaced
*/ */
function wp_cache_replace( $key, $data, $group = '', $expire = 0 ) { function wp_cache_replace( $key, $data, $group = '', $expire = 0 ) {
@ -168,12 +182,15 @@ function wp_cache_replace( $key, $data, $group = '', $expire = 0 ) {
* *
* @since 2.0.0 * @since 2.0.0
* *
* @global WP_Object_Cache $wp_object_cache * @see WP_Object_Cache::set()
* @global WP_Object_Cache $wp_object_cache Object cache global instance.
* *
* @param int|string $key The cache key to use for retrieval later. * @param int|string $key The cache key to use for retrieval later.
* @param mixed $data The contents to store in the cache. * @param mixed $data The contents to store in the cache.
* @param string $group Where to group the cache contents. Enables the same key to be used across groups. * @param string $group Optional. Where to group the cache contents. Enables the same key
* @param int $expire When to expire the cache contents, in seconds. Defaults to 0 (no expiry). * to be used across groups. Default empty.
* @param int $expire Optional. When to expire the cache contents, in seconds.
* Default 0 (no expiration).
* @return bool False on failure, true on success * @return bool False on failure, true on success
*/ */
function wp_cache_set( $key, $data, $group = '', $expire = 0 ) { function wp_cache_set( $key, $data, $group = '', $expire = 0 ) {
@ -183,15 +200,16 @@ function wp_cache_set( $key, $data, $group = '', $expire = 0 ) {
} }
/** /**
* Switch the interal blog id. * Switches the interal blog ID.
* *
* This changes the blog id used to create keys in blog specific groups. * This changes the blog id used to create keys in blog specific groups.
* *
* @since 3.5.0 * @since 3.5.0
* *
* @global WP_Object_Cache $wp_object_cache * @see WP_Object_Cache::switch_to_blog()
* @global WP_Object_Cache $wp_object_cache Object cache global instance.
* *
* @param int $blog_id Blog ID * @param int $blog_id Blog ID.
*/ */
function wp_cache_switch_to_blog( $blog_id ) { function wp_cache_switch_to_blog( $blog_id ) {
global $wp_object_cache; global $wp_object_cache;
@ -204,9 +222,10 @@ function wp_cache_switch_to_blog( $blog_id ) {
* *
* @since 2.6.0 * @since 2.6.0
* *
* @global WP_Object_Cache $wp_object_cache * @see WP_Object_Cache::add_global_groups()
* @global WP_Object_Cache $wp_object_cache Object cache global instance.
* *
* @param string|array $groups A group or an array of groups to add * @param string|array $groups A group or an array of groups to add.
*/ */
function wp_cache_add_global_groups( $groups ) { function wp_cache_add_global_groups( $groups ) {
global $wp_object_cache; global $wp_object_cache;
@ -219,17 +238,18 @@ function wp_cache_add_global_groups( $groups ) {
* *
* @since 2.6.0 * @since 2.6.0
* *
* @param string|array $groups A group or an array of groups to add * @param string|array $groups A group or an array of groups to add.
*/ */
function wp_cache_add_non_persistent_groups( $groups ) { function wp_cache_add_non_persistent_groups( $groups ) {
// Default cache doesn't persist so nothing to do here. // Default cache doesn't persist so nothing to do here.
} }
/** /**
* Reset internal cache keys and structures. If the cache backend uses global * Reset internal cache keys and structures.
* blog or site IDs as part of its cache keys, this function instructs the *
* backend to reset those keys and perform any cleanup since blog or site IDs * If the cache backend uses global blog or site IDs as part of its cache keys,
* have changed since cache init. * this function instructs the backend to reset those keys and perform any cleanup
* since blog or site IDs have changed since cache init.
* *
* This function is deprecated. Use wp_cache_switch_to_blog() instead of this * This function is deprecated. Use wp_cache_switch_to_blog() instead of this
* function when preparing the cache for a blog switch. For clearing the cache * function when preparing the cache for a blog switch. For clearing the cache
@ -238,12 +258,13 @@ function wp_cache_add_non_persistent_groups( $groups ) {
* high. * high.
* *
* @since 2.6.0 * @since 2.6.0
* @deprecated 3.5.0 * @deprecated 3.5.0 WP_Object_Cache::reset()
* @see WP_Object_Cache::reset()
* *
* @global WP_Object_Cache $wp_object_cache * @global WP_Object_Cache $wp_object_cache Object cache global instance.
*/ */
function wp_cache_reset() { function wp_cache_reset() {
_deprecated_function( __FUNCTION__, '3.5' ); _deprecated_function( __FUNCTION__, '3.5', 'wp_cache_switch_to_blog()' );
global $wp_object_cache; global $wp_object_cache;

2
wp-includes/version.php
View File

@ -4,7 +4,7 @@
* *
* @global string $wp_version * @global string $wp_version
*/ */
$wp_version = '4.4-alpha-34224'; $wp_version = '4.4-alpha-34225';
/** /**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.