possible disagreement in the return types/values wp_cache_flush() and WP_Object_Cache:flush().

[pbiron]

​WP_Object_Cache::flush() always returns true.

​wp_cache_flush() returns the value of calling WP_Object_Cache::flush(). But, the DocBlock of wp_cache_flush() lists the return as:

True on success, false on failure.

Is this discrepancy just a mistake, or is it because of the possibility of an object caching plugin returning something different?

[costdev]

The Docblock for wp_cache_flush() was changed to its current form as part of general Docblock improvements for 5.4 - #48303.

Prior to this, the Docblock was changed from "Always returns true" to "False on failure, true on success" in [23328].

See @SergeyBiryukov's comment on #23058.

[SergeyBiryukov]

Replying to pbiron:

Is this discrepancy just a mistake, or is it because of the possibility of an object caching plugin returning something different?

As noted above, per the discussion in comment:2:ticket:23058, it is the latter: the core WP_Object_Cache::flush() method always returns true, but other implementations should be able to return false too.

The same applies to WP_Object_Cache::set() and wp_cache_set().

I'm open to any improvements here that could clarify this :)

[pbiron]

@SergeyBiryukov

And the way wp_cache_flush()'s return value could be different from WP_Object_Cache::flush() is a caching plugin replaces the $wp_object_cache global variable with an instance of their own, which could possibly return something different? Is that correct?

I'll think about how the DocBlock could be change to make that more clear.

[SergeyBiryukov]

Replying to pbiron:

And the way wp_cache_flush()'s return value could be different from WP_Object_Cache::flush() is a caching plugin replaces the $wp_object_cache global variable with an instance of their own, which could possibly return something different? Is that correct?

Yes, that is correct.