From 7f36a90e0ec84eaf1f0055405102b8fc7f81a8eb Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Fri, 11 Feb 2022 17:44:01 +0000 Subject: [PATCH] Docs: Update DocBlocks for some object cache functions per the documentation standards. Follow-up to [47060], [47938], [47944], [52700]. See #54729, #54574. Built from https://develop.svn.wordpress.org/trunk@52703 git-svn-id: http://core.svn.wordpress.org/trunk@52292 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/cache-compat.php | 20 +++++++++------- wp-includes/cache.php | 34 +++++++++++++-------------- wp-includes/class-wp-object-cache.php | 34 ++++++++++++++++----------- wp-includes/version.php | 2 +- 4 files changed, 49 insertions(+), 41 deletions(-) diff --git a/wp-includes/cache-compat.php b/wp-includes/cache-compat.php index 3f3df630e9..f715a5eb97 100644 --- a/wp-includes/cache-compat.php +++ b/wp-includes/cache-compat.php @@ -38,7 +38,7 @@ endif; if ( ! function_exists( 'wp_cache_delete_multiple' ) ) : /** - * Delete multiple values from the cache in one call. + * Deletes multiple values from the cache in one call. * * Compat function to mimic wp_cache_delete_multiple(). * @@ -65,7 +65,7 @@ endif; if ( ! function_exists( 'wp_cache_add_multiple' ) ) : /** - * Add multiple values to the cache in one call, if the cache keys doesn't already exist. + * Adds multiple values to the cache in one call, if the cache keys don't already exist. * * Compat function to mimic wp_cache_add_multiple(). * @@ -74,9 +74,10 @@ if ( ! function_exists( 'wp_cache_add_multiple' ) ) : * * @see wp_cache_add_multiple() * - * @param array $data Array of key and value to be added. - * @param string $group Optional. Where the cache contents are grouped. Default empty. - * @param int $expire Optional. When to expire the cache contents, in seconds. Default 0 (no expiration). + * @param array $data Array of keys and values to be added. + * @param string $group Optional. Where the cache contents are grouped. Default empty. + * @param int $expire Optional. When to expire the cache contents, in seconds. + * Default 0 (no expiration). * @return array Array of return values. */ function wp_cache_add_multiple( array $data, $group = '', $expire = 0 ) { @@ -92,7 +93,7 @@ endif; if ( ! function_exists( 'wp_cache_set_multiple' ) ) : /** - * Set multiple values to the cache in one call. + * Sets multiple values to the cache in one call. * * Differs from wp_cache_add_multiple() in that it will always write data. * @@ -103,9 +104,10 @@ if ( ! function_exists( 'wp_cache_set_multiple' ) ) : * * @see wp_cache_set_multiple() * - * @param array $data Array of key and value to be set. - * @param string $group Optional. Where the cache contents are grouped. Default empty. - * @param int $expire Optional. When to expire the cache contents, in seconds. Default 0 (no expiration). + * @param array $data Array of keys and values to be set. + * @param string $group Optional. Where the cache contents are grouped. Default empty. + * @param int $expire Optional. When to expire the cache contents, in seconds. + * Default 0 (no expiration). * @return array Array of return values. */ function wp_cache_set_multiple( array $data, $group = '', $expire = 0 ) { diff --git a/wp-includes/cache.php b/wp-includes/cache.php index b9ffe96219..2168569c58 100644 --- a/wp-includes/cache.php +++ b/wp-includes/cache.php @@ -59,7 +59,8 @@ function wp_cache_close() { * @global WP_Object_Cache $wp_object_cache Object cache global instance. * * @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 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 int|false The item's new value on success, false on failure. */ @@ -145,9 +146,8 @@ function wp_cache_get_multiple( $keys, $group = '', $force = false ) { return $wp_object_cache->get_multiple( $keys, $group, $force ); } - /** - * Delete multiple values from the cache in one call. + * Deletes multiple values from the cache in one call. * * @since 6.0.0 * @@ -156,7 +156,7 @@ function wp_cache_get_multiple( $keys, $group = '', $force = false ) { * * @param array $keys Array of keys under which the cache to deleted. * @param string $group Optional. Where the cache contents are grouped. Default empty. - * @return array Array of return values organized into groups. + * @return array Array of return values. */ function wp_cache_delete_multiple( array $keys, $group = '' ) { global $wp_object_cache; @@ -165,17 +165,17 @@ function wp_cache_delete_multiple( array $keys, $group = '' ) { } /** - * Add multiple values to the cache in one call. + * Adds multiple values to the cache in one call. * * @since 6.0.0 * * @see WP_Object_Cache::add_multiple() * @global WP_Object_Cache $wp_object_cache Object cache global instance. * - * @param array $data Array of key and value to be set. - * @param string $group Optional. Where the cache contents are grouped. Default empty. + * @param array $data Array of keys and values to be set. + * @param string $group Optional. Where the cache contents are grouped. Default empty. * @param int $expire Optional. When to expire the cache contents, in seconds. - * Default 0 (no expiration). + * Default 0 (no expiration). * @return array Array of return values. */ function wp_cache_add_multiple( array $data, $group = '', $expire = 0 ) { @@ -185,17 +185,17 @@ function wp_cache_add_multiple( array $data, $group = '', $expire = 0 ) { } /** - * Set multiple values to the cache in one call. + * Sets multiple values to the cache in one call. * * @since 6.0.0 * * @see WP_Object_Cache::set_multiple() * @global WP_Object_Cache $wp_object_cache Object cache global instance. * - * @param array $data Array of key and value to be set. - * @param string $group Optional. Where the cache contents are grouped. Default empty. + * @param array $data Array of keys and values to be set. + * @param string $group Optional. Where the cache contents are grouped. Default empty. * @param int $expire Optional. When to expire the cache contents, in seconds. - * Default 0 (no expiration). + * Default 0 (no expiration). * @return array Array of return values. */ function wp_cache_set_multiple( array $data, $group = '', $expire = 0 ) { @@ -205,7 +205,7 @@ function wp_cache_set_multiple( array $data, $group = '', $expire = 0 ) { } /** - * Increment numeric cache item's value + * Increments numeric cache item's value. * * @since 3.3.0 * @@ -213,7 +213,8 @@ function wp_cache_set_multiple( array $data, $group = '', $expire = 0 ) { * @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 Optional. The amount by which to increment the item's value. Default 1. + * @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 int|false The item's new value on success, false on failure. */ @@ -248,7 +249,7 @@ function wp_cache_init() { * 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 True if contents were replaced, false if original value does not exist. */ function wp_cache_replace( $key, $data, $group = '', $expire = 0 ) { global $wp_object_cache; @@ -335,8 +336,7 @@ function wp_cache_add_non_persistent_groups( $groups ) { * 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 * during unit tests, consider using wp_cache_init(). wp_cache_init() is not - * recommended outside of unit tests as the performance penalty for using it is - * high. + * recommended outside of unit tests as the performance penalty for using it is high. * * @since 2.6.0 * @deprecated 3.5.0 WP_Object_Cache::reset() diff --git a/wp-includes/class-wp-object-cache.php b/wp-includes/class-wp-object-cache.php index 920ec5e4da..2a93c53746 100644 --- a/wp-includes/class-wp-object-cache.php +++ b/wp-includes/class-wp-object-cache.php @@ -141,7 +141,8 @@ class WP_Object_Cache { * @param int|string $key What to call the contents in the cache. * @param mixed $data The contents to store in the cache. * @param string $group Optional. Where to group the cache contents. Default 'default'. - * @param int $expire Optional. When to expire the cache contents. Default 0 (no expiration). + * @param int $expire Optional. When to expire the cache contents, in seconds. + * Default 0 (no expiration). * @return bool True on success, false if cache key and group already exist. */ public function add( $key, $data, $group = 'default', $expire = 0 ) { @@ -185,7 +186,8 @@ class WP_Object_Cache { * @since 3.3.0 * * @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 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 'default'. * @return int|false The item's new value on success, false on failure. */ @@ -227,7 +229,7 @@ class WP_Object_Cache { * @param int|string $key What the contents in the cache are called. * @param string $group Optional. Where the cache contents are grouped. Default 'default'. * @param bool $deprecated Optional. Unused. Default false. - * @return bool False if the contents weren't deleted and true on success. + * @return bool True on success, false if the contents were not deleted. */ public function delete( $key, $group = 'default', $deprecated = false ) { if ( empty( $group ) ) { @@ -324,7 +326,7 @@ class WP_Object_Cache { } /** - * Delete multiple values from the cache in one call. + * Deletes multiple values from the cache in one call. * * @since 6.0.0 * @@ -343,13 +345,14 @@ class WP_Object_Cache { } /** - * Add multiple values to the cache in one call. + * Adds multiple values to the cache in one call. * * @since 6.0.0 * - * @param array $data Array of key and value to be added. + * @param array $data Array of keys and values to be added. * @param string $group Optional. Where the cache contents are grouped. Default empty. - * @param int $expire Optional. When to expire the cache contents, in seconds. Default 0 (no expiration). + * @param int $expire Optional. When to expire the cache contents, in seconds. + * Default 0 (no expiration). * @return array Array of return values. */ public function add_multiple( array $data, $group = '', $expire = 0 ) { @@ -363,13 +366,14 @@ class WP_Object_Cache { } /** - * Set multiple values to the cache in one call. + * Sets multiple values to the cache in one call. * * @since 6.0.0 * * @param array $data Array of key and value to be set. * @param string $group Optional. Where the cache contents are grouped. Default empty. - * @param int $expire Optional. When to expire the cache contents, in seconds. Default 0 (no expiration). + * @param int $expire Optional. When to expire the cache contents, in seconds. + * Default 0 (no expiration). * @return array Array of return values. */ public function set_multiple( array $data, $group = '', $expire = 0 ) { @@ -387,8 +391,9 @@ class WP_Object_Cache { * * @since 3.3.0 * - * @param int|string $key The cache key to increment - * @param int $offset Optional. The amount by which to increment the item's value. Default 1. + * @param int|string $key The cache key to increment. + * @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 'default'. * @return int|false The item's new value on success, false on failure. */ @@ -430,8 +435,9 @@ class WP_Object_Cache { * @param int|string $key What to call the contents in the cache. * @param mixed $data The contents to store in the cache. * @param string $group Optional. Where to group the cache contents. Default 'default'. - * @param int $expire Optional. When to expire the cache contents. Default 0 (no expiration). - * @return bool False if not exists, true if contents were replaced. + * @param int $expire Optional. When to expire the cache contents, in seconds. + * Default 0 (no expiration). + * @return bool True if contents were replaced, false if original value does not exist. */ public function replace( $key, $data, $group = 'default', $expire = 0 ) { if ( empty( $group ) ) { @@ -486,7 +492,7 @@ class WP_Object_Cache { * @param int|string $key What to call the contents in the cache. * @param mixed $data The contents to store in the cache. * @param string $group Optional. Where to group the cache contents. Default 'default'. - * @param int $expire Not Used. + * @param int $expire Optional. Not used. * @return true Always returns true. */ public function set( $key, $data, $group = 'default', $expire = 0 ) { diff --git a/wp-includes/version.php b/wp-includes/version.php index ae3d82fa87..6c5168a212 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.0-alpha-52702'; +$wp_version = '6.0-alpha-52703'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.