From 4e4737685e133e8af992b316d154e3f175ba7cd8 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Wed, 16 Sep 2015 09:40:25 +0000 Subject: [PATCH] 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 --- wp-includes/cache.php | 123 +++++++++++++++++++++++----------------- wp-includes/version.php | 2 +- 2 files changed, 73 insertions(+), 52 deletions(-) diff --git a/wp-includes/cache.php b/wp-includes/cache.php index 50ff254506..a18d24afea 100644 --- a/wp-includes/cache.php +++ b/wp-includes/cache.php @@ -13,12 +13,15 @@ * * @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 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 int $expire When the cache data should expire, in seconds. Default is 0 (no expiry). + * @param int|string $key The cache key to use for retrieval later. + * @param mixed $data The data to add to the cache. + * @param string $group Optional. The group to add the cache to. Enables the same key + * 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. */ 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. * * This function has ceased to do anything since WordPress 2.5. The - * functionality was removed along with the rest of the persistent cache. 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. + * functionality was removed along with the rest of the persistent cache. + * + * 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 * - * @return true Always returns True + * @return true Always returns true. */ function wp_cache_close() { return true; } /** - * Decrement numeric cache item's value + * Decrements numeric cache item's value. * * @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 $offset The amount by which to decrement the item's value. Default is 1. - * @param string $group The group the key is in. + * @param int|string $key The cache key to decrement. + * @param int $offset Optional. The amount by which to decrement the item's value. Default 1. + * @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. */ function wp_cache_decr( $key, $offset = 1, $group = '' ) { @@ -66,13 +71,14 @@ function wp_cache_decr( $key, $offset = 1, $group = '' ) { * * @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 string $group Where the cache contents are grouped. + * @param int|string $key What the contents in the cache are called. + * @param string $group Optional. Where the cache contents are grouped. Default empty. * @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; return $wp_object_cache->delete($key, $group); @@ -83,7 +89,8 @@ function wp_cache_delete($key, $group = '') { * * @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 */ @@ -98,12 +105,15 @@ function wp_cache_flush() { * * @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 string $group Where the cache contents are grouped. - * @param bool $force Whether to force an update of the local cache from the persistent cache (default is false). - * @param bool &$found Whether key was found in the cache. Disambiguates a return of false, a storable value. + * @param int|string $key The key under which the cache contents are stored. + * @param string $group Optional. Where the cache contents are grouped. Default empty. + * @param bool $force Optional. Whether to force an update of the local cache from the persistent + * 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 * contents on success */ @@ -118,11 +128,12 @@ function wp_cache_get( $key, $group = '', $force = false, &$found = null ) { * * @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 $offset The amount by which to increment the item's value. Default is 1. - * @param string $group The group the key is in. + * @param int|string $key The key for the cache contents that should be incremented. + * @param int $offset Optional. The amount by which to increment the item's value. Default 1. + * @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. */ function wp_cache_incr( $key, $offset = 1, $group = '' ) { @@ -147,12 +158,15 @@ function wp_cache_init() { * * @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 mixed $data The new data to store in the cache. - * @param string $group 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). + * @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 string $group Optional. The group for the cache data that should be replaced. + * 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 */ 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 * - * @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 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 int $expire When to expire the cache contents, in seconds. Defaults to 0 (no expiry). + * @param int|string $key The cache key to use for retrieval later. + * @param mixed $data The contents to store in the cache. + * @param string $group Optional. Where to group the cache contents. Enables the same key + * 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 */ 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. * * @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 ) { global $wp_object_cache; @@ -204,9 +222,10 @@ function wp_cache_switch_to_blog( $blog_id ) { * * @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 ) { global $wp_object_cache; @@ -219,17 +238,18 @@ function wp_cache_add_global_groups( $groups ) { * * @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 ) { // Default cache doesn't persist so nothing to do here. } /** - * Reset internal cache keys and structures. If the cache backend uses global - * 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 - * have changed since cache init. + * Reset internal cache keys and structures. + * + * If the cache backend uses global 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 have changed since cache init. * * 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 @@ -238,12 +258,13 @@ function wp_cache_add_non_persistent_groups( $groups ) { * high. * * @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() { - _deprecated_function( __FUNCTION__, '3.5' ); + _deprecated_function( __FUNCTION__, '3.5', 'wp_cache_switch_to_blog()' ); global $wp_object_cache; diff --git a/wp-includes/version.php b/wp-includes/version.php index a04babd8cf..62e505c54a 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -4,7 +4,7 @@ * * @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.