Add documentation notes on error handling with sync=true

See gh-36531

(cherry picked from commit 529a6fc932)

spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java

@@ -193,8 +193,18 @@ public @interface Cacheable {
 	 * This is effectively a hint and the chosen cache provider might not actually
 	 * support it in a synchronized fashion. Check your provider documentation for
 	 * more details on the actual semantics.
+	 * <p>Note that `sync=true` leads to a combined callback operation against the
+	 * cache provider. If this combined operation fails on initial cache access,
+	 * there is no separate put operation to attempt anymore. Whereas for a default
+	 * `sync=false` setup, there are independent get and put steps: If the get step
+	 * fails but its error is suppressed in the {@code CacheErrorHandler} setup,
+	 * there will still be a put attempt after calling the underlying method.
 	 * @since 4.3
 	 * @see org.springframework.cache.Cache#get(Object, Callable)
+	 * @see org.springframework.cache.Cache#get(Object)
+	 * @see org.springframework.cache.Cache#put(Object, Object)
+	 * @see org.springframework.cache.interceptor.CacheErrorHandler#handleCacheGetError
+	 * @see org.springframework.cache.interceptor.CacheErrorHandler#handleCachePutError
 	 */
 	boolean sync() default false;
 

spring-context/src/main/java/org/springframework/cache/interceptor/CacheErrorHandler.java

@@ -16,6 +16,8 @@
 
 package org.springframework.cache.interceptor;
 
+import java.util.concurrent.Callable;
+
 import org.springframework.cache.Cache;
 import org.springframework.lang.Nullable;
 
@@ -38,10 +40,17 @@ public interface CacheErrorHandler {
 	 * Handle the given runtime exception thrown by the cache provider when
 	 * retrieving an item with the specified {@code key}, possibly
 	 * rethrowing it as a fatal exception.
+	 * <p>Note that for a default {@code @Cacheable} setup, this will be called
+	 * after an initial cache access failure, whereas the subsequent put step may
+	 * independently fail and be handled in {@link #handleCachePutError} still.
+	 * However, for {@code @Cacheable(sync=true)}, there is only a combined get step
+	 * with {@code handleCacheGetError} being called in case of failure; there won't
+	 * be a separate put attempt after initial cache access failure anymore.
 	 * @param exception the exception thrown by the cache provider
 	 * @param cache the cache
 	 * @param key the key used to get the item
 	 * @see Cache#get(Object)
+	 * @see Cache#get(Object, Callable)
 	 */
 	void handleCacheGetError(RuntimeException exception, Cache cache, Object key);